Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of behavioral disclosure. It details what the tool verifies (ASH installation, scanner availability) and the return dictionary contents, making behavior transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured, opening with a clear purpose, then adding usage context and return details. It is slightly verbose in listing return items, but all sentences contribute value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an output schema, the description adequately covers installation status, scanner dependencies, and return items. It doesn't detail how availability is determined, but the output schema likely handles the return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description correctly does not invent any parameter semantics. This aligns with the baseline for no-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks if ASH is installed and available, with a specific verb and resource. It also distinguishes itself from sibling scanning tools by framing this as a preflight check, not a scan.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs users to 'Use this before attempting to scan with ASH,' providing a clear when-to-use context. It doesn't specify when not to use it or list alternatives, but the intended usage is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that the tool 'produces a structured Markdown report with executive summary, STRIDE threat model, compliance notes, and prioritized recommendations,' which gives valuable insight into the output. However, it does not mention whether the report is returned directly, saved to a file, or how it handles malformed JSON input, leaving some behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—just two sentences—with the purpose front-loaded in the first sentence and the additional breakdown of the report's contents in the second. Every word earns its place, and there is no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has only two parameters, full schema coverage, and an output schema, the description is sufficiently complete for an agent to understand its role. It could have mentioned more about the expected input format or error behavior, but the existing detail about the report contents is enough for basic invocation. The output schema presumably covers return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage of parameters with descriptions, and the description adds no additional semantic detail beyond what is in the schema. For example, the schema details that 'scan_results' is a JSON string from specific scan tools, and the description merely references 'one or more security scans.' This matches the baseline expectation for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: 'Generate a SECURITY.md report from scan results.' The verb 'generate' and resource 'SECURITY.md report' are specific, and the tool is clearly distinguished from sibling scanning tools like scan_with_checkov and scan_with_semgrep by focusing on report generation rather than scanning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: 'Takes output from one or more security scans.' This implies it should be used after scanning, and since no other report-generation siblings exist, the usage is unambiguous. However, it does not explicitly mention alternative tools or exclusions, so it falls short of a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It states the tool 'returns information,' implying a non-mutating, read-only operation. However, it does not disclose potential side effects, dependencies, or the exact structure of the returned dictionary beyond a high-level description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The first and second sentences are redundant ('Get list of supported formats and languages' vs. 'returns information about what file formats and programming languages are supported'). The Returns section adds minimal new info. This could be condensed to one sentence, resulting in wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, parameterless getter, the description is sufficient: it explains the purpose and return type. The output schema is noted as present, so the description does not need to enumerate every field. It is complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline for this dimension is 4. The description correctly focuses on the output rather than inputs, and no parameter clarification is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Get list') and resource ('supported formats and languages for all security scanning tools'), immediately distinguishing it from sibling scan tools. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: this appears to be a pre-scan information tool. However, it does not explicitly state when to use it (e.g., 'before scanning, use this to check compatibility') or mention alternatives/exclusions. The context is clear but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses several behavioral traits: multiple scanners are run, semgrep is excluded, and installation requirements are provided. However, it omits a key behavior reflected in the schema: the return_output parameter defaults to false, meaning output is saved to file rather than returned, and the 'Returns' section implies a dictionary is always returned without mentioning this flag. Since no annotations exist, the description carries the full burden and this is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections, front-loaded purpose, and no fluff. The supported file types list and installation notes are useful, though the text is somewhat long. It earns a high score for organization and relevance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description covers many important aspects: scanner list, file type support, installation, and the semgrep exclusion. However, it does not explain the return_output/save-to-file behavior, which is a significant omission for a tool that can save results. The overall picture is fairly complete but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema provides complete parameter documentation. The description's Args section repeats directory_path and severity_threshold but adds no new meaning; it also omits the return_output parameter entirely. The supported file types and severity level list add some context, but not enough to raise the score above the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Scan an entire project directory with ASH for comprehensive security analysis.' It distinguishes itself from scan_with_ash ('Unlike scan_with_ash which scans code snippets') and from scan_directory_with_semgrep ('Use scan_directory_with_semgrep instead'). It also names the underlying scanners.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use this tool vs alternatives: it scans actual project directories, while scan_with_ash scans snippets, and semgrep is excluded so scan_directory_with_semgrep is recommended. It also lists supported file types and gives installation instructions, providing clear context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavior. It discloses that it scans all Python files, requires Bandit to be installed, returns a dictionary of findings, and honors severity thresholds. It also notes installation instructions. The only notable gap is that the description omits the 'return_output' parameter's behavior (returning output vs. saving to file) even though it's in the schema, which would have added extra transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, contrast, issue types, args, returns, note). It is somewhat lengthy due to the bulleted list of security issues, but these bullets are informative and give the agent a concrete sense of what Bandit detects. The front-loaded purpose sentence is strong, and the overall organization aids comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a security scanning tool with an output schema and no annotations, the description covers most essential context: purpose, scope, return type, installation requirements, and parameter meanings. It does not describe the exact structure of the returned dictionary (though the output schema handles that), nor does it mention performance or side effects. Given the tool's moderate complexity, this is a solid, complete-enough description, though not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all three parameters, so the baseline is 3. The description adds a few extra details (e.g., 'relative or absolute' for directory_path) but largely repeats the schema information. It does not clarify the 'return_output' parameter beyond the schema, so it does not significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans whole directories with Bandit for Python security issues, using a specific verb ('scan') and resource ('project directory'). It explicitly distinguishes itself from the sibling scan_with_bandit, which scans code snippets, and enumerates the types of issues it catches, leaving no ambiguity about its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly contrasts this tool with scan_with_bandit, stating the former scans directories while the latter scans snippets. This gives clear guidance on when to use this tool over that specific alternative. However, it does not mention sibling directory scanning tools (e.g., sync_directory_with_grype) or explicitly state that it is Python-specific, though the implication is clear from the 'Python files' phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses prerequisites (Checkov must be installed), supported file types, and return type. However, it fails to explain the behavioral implication of the return_output parameter (default false saves output to file), which creates ambiguity about the actual output behavior. With no annotations, this gap leaves significant behavioral disclosure unmet.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is thorough but contains some redundancy (first two sentences both say it scans IaC files). The file type list and install note are useful, and the structure with clear headings helps readability. It is longer than strictly necessary but not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and the presence of an output schema, the description covers key aspects: purpose, scope, supported formats, and installation requirement. It misses explaining the default file-saving behavior tied to return_output, but the overall context is sufficient for an agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters. The description redundantly restates directory_path and severity_threshold but adds no additional semantic detail beyond the schema. It omits return_output entirely, so no added value for that parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'Scan an entire project directory with Checkov for IaC security issues.' It immediately distinguishes itself from sibling tool scan_with_checkov, which scans code snippets, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly contrasts with scan_with_checkov ('Unlike scan_with_checkov which scans code snippets'), offering a clear alternative. It also lists supported file types to indicate applicable scenarios. However, it does not provide explicit when-not-to-use guidance relative to other sibling scanners like semgrep or trivy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the prerequisite that Grype must be installed and available in PATH, and notes that it reports known vulnerabilities. However, it does not mention potential side effects like downloading vulnerability databases or network access, which a security scanner might perform.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Supported ecosystems, Args, Returns, Note) and front-loaded with its purpose. It is somewhat verbose with installation instructions and ecosystem lists, but these are useful and not excessive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description does not need to elaborate beyond the dictionary return. It covers dependencies scanned, supported ecosystems, arguments, and installation prerequisites. It lacks error-handling details but is otherwise complete for typical usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers all three parameters (100% coverage). The description adds value by specifying that directory_path can be relative or absolute and that severity_threshold is the minimum severity to report. It does not mention the return_output parameter, but the schema describes it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans a project directory with Grype for dependency vulnerabilities, using a specific verb and resource. It explicitly distinguishes itself from scan_with_ash by noting that tool scans code snippets while this one scans the project directory for dependency files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use this tool versus scan_with_ash, and lists supported ecosystems. However, it does not explicitly mention exclusions or compare to other directory scanners like scan_with_trivy or scan_directory_with_syft, so the guidance is not comprehensive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It explains the scanning scope, ruleset focus, and return type, and notes Semgrep must be installed. However, the 'Returns' section conflicts with the schema's 'return_output' parameter (default false implies saving to file rather than returning), which is confusing and undermines transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections for purpose, differentiation, supported languages, args, returns, and note. It is longer than minimal but each section adds value, such as the installation instructions. Front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a moderately complex scanning tool with an output schema, the description covers core behavior, languages, and differences from sibling. However, the inconsistency about saving vs returning output (due to return_output) creates a completeness gap, and there is no mention of performance implications or failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for all three parameters. The description restates directory_path and severity_threshold but does not add substantial meaning beyond the schema. The installation note is helpful but not parameter-specific.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Scan') with a specific resource ('entire project directory with Semgrep') and clearly distinguishes itself from 'scan_with_semgrep' which scans code snippets. It also lists supported languages, making the scope evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly contrasts with 'scan_with_semgrep' and gives installation prerequisites. While it doesn't discuss when to choose this over other directory scanners like scan_directory_with_bandit, it provides clear context for its own appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full transparency burden. It discloses that only a summary is returned by default, that save_sbom=True writes to a .sbom directory, the output format options, the exact return dictionary structure, and the prerequisite that Syft must be installed (with installation commands). It does not explicitly state it is read-only/non-destructive, but the catalog/inventory language strongly implies it. This is rich behavioral context beyond the minimal, but not exhaustive enough for a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with a clear purpose statement. It uses headings, bullet points, and concise sections for behavior, parameters, returns, and installation. While the supported package list is long, it is useful and directly relevant to an SBOM tool. Every section serves a purpose, and the overall structure is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the purpose, usage context, parameters, return format, and installation prerequisites. It differentiates the tool from vulnerability scanner siblings and explains the downstream use of the generated SBOM. Given the tool's moderate complexity, this is sufficiently complete for an agent to invoke it correctly, though it could mention edge cases like nonexistent directories or recursive scanning behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description's Args section largely repeats the schema descriptions, adding only minor clarifications like 'relative or absolute' for directory_path and spelling out the output_format options (which are already in the schema). This adds marginal value beyond the schema, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific statement: 'Scan an entire project directory with Syft to generate Software Bill of Materials (SBOM).' It explicitly distinguishes the tool from vulnerability scanners, which is a key differentiator among the many scanning siblings. The verb and resource are precise, leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states this is for generating an SBOM inventory, not for vulnerability scanning, and even suggests using Grype later for vulnerability scanning. It gives clear context on when to use the tool, but it doesn't explicitly name sibling alternatives or state exclusions (e.g., 'use scan_directory_with_grype for vulnerabilities'). This is a clear context without explicit alternative naming, matching a 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It mentions installation requirements, image pulling, and minimized output format. However, it fails to mention the `return_output` parameter behavior, which is key: the description says 'Returns: A dictionary' but the schema for `return_output` indicates that by default it saves to file (return_output=false), not returns a dictionary. This internal inconsistency means an agent could be misled about the return behavior. The description does not disclose this crucial aspect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (overview, output details, use cases, Args, Returns, Note). It is reasonably concise and front-loaded with the core purpose. The inclusion of installation instructions is slightly beyond the core, but they are relevant and add value without being excessive, so it earns a 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description has clear gaps. The `return_output` parameter is not covered in the description and the Returns statement conflicts with the schema. Additionally, it does not mention any registry authentication requirements or network access considerations for private images. For a security scanning tool with three parameters and no annotations, these omissions reduce completeness below the minimum viable level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds useful examples for `image_name` (e.g., nginx:latest) and severity levels, but it omits the `return_output` parameter entirely from its Args section, which could create confusion about its existence. Overall it adds some value beyond the schema but not enough to exceed the baseline given the omission.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource statement: 'Scan a container image using Trivy for vulnerabilities.' It clearly distinguishes this tool from sibling scanning tools by focusing on container images and mentions specific vulnerability categories (OS packages, application dependencies, base images).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear use cases ('Scanning base images used in Dockerfiles', 'Checking for vulnerabilities before deployment', 'Security audits of container images') and explicitly indicates the tool is for container images. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks the explicit 'when-not' guidance needed for a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool performs delta scanning, creates a temporary file, runs in local mode, and requires ASH to be installed with specific install commands. This is substantial behavioral transparency, though it doesn't mention failure modes or timeout behaviors, hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections: overview, file types, args, returns, and install notes. It is somewhat long and repeats the Semgrep exclusion twice, but overall each section adds relevant information. Slight redundancy prevents a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all essential aspects: what it does, how it scans, file-type support, parameters, return type, and installation prerequisites. An output schema exists, so the return dictionary is already indicated. This is thoroughly complete for a security scanning tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters, and the description enriches this by explaining how file_extension maps to specific scanners and file types. It also clarifies the meaning of severity_threshold. This adds value beyond the schema descriptions, earning above the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: scanning code with ASH for comprehensive security analysis. It lists specific scanners and explicitly distinguishes itself from the sibling scan_with_semgrep tool. The verb 'Scan' plus the resource and scope ('code snippet') make it unambiguous and well-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for usage, including supported file types and the note that Semgrep is intentionally excluded and should be handled by scan_with_semgrep. It also explains the delta-scanning approach. A stronger explicit 'when to use ASH vs. individual scanners' would push it to 5, but the guidance is solid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It explains the types of issues detected and the return shape, but does not mention whether the code is executed, whether the operation is read-only, or any limitations/edge cases. Adequate but not deeply transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an opening summary, a bulleted list of security issues, and an Args/Returns section. There is slight redundancy between the first line and the second line, but the content is focused and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool, the description covers the input, the tool's purpose, representative issue types, and the return format. An output schema already exists, so detailed field documentation is unnecessary. It could have mentioned the directory-based sibling, but the scope is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the only parameter as 'Python code content to scan' with 100% coverage. The description's 'code: The Python code content to analyze' adds no meaningful new semantics, so a baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Scan Python code using Bandit') with a resource ('Python source code') and a nameable tool (Bandit). The included vulnerability examples and Python-specific framing distinguish it from sibling tools like scan_with_semgrep or scan_directory_with_bandit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: it is for scanning Python code snippets/content for security issues. It does not explicitly describe when to use this tool versus directory-level scanners or alternative scanners, but the Python+code scope is well implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full transparency burden. It states the tool analyzes IaC files for security misconfigurations and compliance violations, and mentions it returns a dictionary of results. However, it does not disclose potential limitations (e.g., file size, network access), whether it executes the scanned code, or that it is a read-only operation. This is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with sections for purpose, supported formats, args, and returns. The list of formats is essential and earns its place, though the second sentence restates the first line with minor detail, making it slightly verbose. Overall, it is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema and 100% parameter coverage, the description is reasonably complete. It covers what the tool does, supported formats, input arguments, and return type. It does not explain how results are structured beyond 'dictionary with scanned issues', but the output schema likely handles that. It could mention whether multiple formats can be scanned at once, but the schema implies single format per call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage, so the baseline is 3. The description adds meaningful value by listing the accepted format types (e.g., terraform, cloudformation, kubernetes) and clarifying that 'code' is the content to analyze. This goes beyond the schema's brief 'etc.' and helps the agent select valid values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans Infrastructure as Code using Checkov for security issues, with a specific verb ('Scan'), a resource ('Infrastructure as Code'), and the tool name ('Checkov'). It also distinguishes itself from siblings like scan_with_semgrep and scan_with_bandit by focusing on IaC formats and listing supported types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by specifying that it analyzes Infrastructure as Code files and lists supported formats, which implies when to use it. However, it does not explicitly name alternatives or state exclusions, such as 'use this for IaC scanning rather than semgrep'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions that the tool 'analyzes' and 'returns' results, but it does not state whether the scan is read-only, whether any network calls are made, rate limits, or limitations. Since it's a security scanner, it likely has no side effects, but this is not disclosed, leaving a transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for purpose, languages, args, and returns. The language list is necessary but length, and there is no redundant fluff. It front-loads the primary purpose and provides the essential details without excessive verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with an output schema, the description is mostly adequate. It explains the arguments and return type. However, it does not explicitly distinguish this tool from the sibling 'scan_directory_with_semgrep', so an agent might be unclear when to use this content-based variant versus a directory scan. This is a notable completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes both parameters, but the description adds value by listing the full set of supported languages (expanding on the schema's 'etc.') and clarifying that 'code' refers to source code content. This helps the agent select valid values for the language parameter, going beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Scan source code using Semgrep for security vulnerabilities.' It identifies the specific tool (Semgrep), the resource (source code), and the scope (security vulnerabilities, bugs, anti-patterns). This distinguishes it from other sibling scanners by naming the engine and the input type (code content vs directory).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by listing supported languages and describing the code parameter, but it does not explicitly state when to choose this tool over alternatives like scan_with_bandit or scan_directory_with_semgrep. There is no 'use when...' or 'not for directories' guidance, leaving the context implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the installation requirement for Trivy (with install instructions), notes the return format (a dictionary with scan results), and lists the types of issues it detects. This provides valuable behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for supported scans, Args, Returns, and Notes. While somewhat long, each section provides useful information without unnecessary filler. The opening line is clear and the list format improves readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema and only two parameters, the description covers the essential aspects: supported scan types, return type, and the installation prerequisite. It doesn't explain the contents of the returned dictionary, but the output schema covers that, so the description is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description doesn't need to compensate much. It adds meaning by explicitly enumerating the valid values for scan_type (dockerfile, terraform, kubernetes, config) and clarifying what 'code' should contain, going slightly beyond the schema's generic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans Infrastructure as Code or Dockerfiles using Trivy, with a specific verb ('Scan'), resource, and tool named. It includes a list of supported scan types (dockerfile, terraform, kubernetes, config), which distinguishes it from sibling tools like scan_with_checkov or scan_with_semgrep.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists supported scan types and specifies Trivy as the scanner, implying usage for security scanning of IaC and Dockerfiles. However, it provides no explicit guidance on when to choose this tool over alternatives like Checkov or Semgrep, and no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.