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

No annotations provided; description informs that git apply is used and refuses paths escaping target directory, which is a key safety behavior. Covers destructive nature implicitly.

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?

Three sentences, each adding value: purpose, safety mechanism, usage recommendation. No superfluous 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?

Given the tool's simplicity (3 parameters, straightforward behavior), the description is complete: explains what, how (git apply), safety check, and options.

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%, and description adds minimal additional meaning beyond schema descriptions. Slightly rephrases schema but does not add new constraints or examples.

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?

Description clearly states the tool applies a unified diff to files under target_path using git apply. It specifies the verb 'apply' and resource, and no sibling tool performs similar function.

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?

Explicitly recommends using check_only=True first to verify the patch applies cleanly before writing changes, providing a clear workflow guideline. Does not mention when not to use, but siblings are distinct.

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 the action (posting a comment) and authentication method (env vars), but does not detail behavior on failure, idempotency, or whether it replaces existing comments. Basic behavior is clear but not comprehensive.

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 two efficient sentences: one for purpose and one for credential setup. No extraneous text, front-loaded with the primary action.

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 tool has 4 required parameters and an output schema (present but not shown). The description covers the credential setup, which is critical for usage. It could mention return value or error handling, but overall it is reasonably complete for a simple posting 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?

Schema description coverage is 100%, so the schema already explains all four parameters. The description does not add meaning beyond the schema, justifying the baseline score of 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 uses a specific verb 'Post' and clearly identifies the resource: 'security summary comment on a GitHub PR or GitLab merge request'. This distinguishes it from sibling notification tools (e.g., notify_slack) which target different platforms.

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 mentions credential setup (environment variables) which is essential for using the tool, but does not explicitly state when to prefer this tool over alternatives like notify_slack or notify_teams. The guidance is implied via the platform-specific context.

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 full burden. It only states the action and output, failing to disclose behavioral traits like required permissions, rate limits, or behavior when no baseline exists.

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?

Two short sentences, front-loaded with core action, no unnecessary words. Efficient and to the point.

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?

Output schema exists, so return value explanation is unneeded. However, description omits prerequisites (e.g., baseline must exist) and behavioral context, leaving gaps for a 5-parameter 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?

Schema coverage is 100% with descriptions for all parameters. The tool description adds no additional parameter semantics beyond the overall purpose, so baseline score of 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 the verb (compare), resource (scan results against baseline), and output details (new, fixed, severity trends). It distinguishes from sibling 'save_baseline' which saves rather than compares.

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 after a baseline is saved but provides no explicit when-to-use or when-not-to-use guidance. It does not mention prerequisites or alternatives among siblings.

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 carry the full burden. It explains the mapping uses CWE/OWASP metadata but does not disclose whether the tool is read-only, whether it modifies data, or any required permissions. Adequate but has 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 two sentences, front-loaded with the core purpose, and contains no unnecessary words. Every part adds 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 the tool has an output schema and the description covers the main action and frameworks, it is fairly complete. However, it omits prerequisites like the existence of scan findings.

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%, providing a baseline of 3. The description adds context about framework mapping using CWE/OWASP metadata, but does not further elaborate on parameter meanings or constraints beyond the schema.

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 maps findings to a compliance framework and reports posture, listing specific frameworks (OWASP, SANS, PCI, CIS). However, it does not explicitly differentiate from sibling tools like 'generate_report'.

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 no guidance on when to use this tool versus alternatives such as 'evaluate_policy' or 'generate_report'. It lacks explicit context on prerequisites or exclusions.

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 full burden. It mentions environment variable dependencies but fails to disclose whether the operation is idempotent, what side effects occur (e.g., creating a Jira ticket, triggering notifications), or error handling behavior.

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?

Two sentences: first states the purpose, second notes prerequisites. Front-loaded, no redundant information. Every word adds 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?

Despite the presence of an output schema, the description does not mention what the tool returns (e.g., issue key or URL). There is no context on rate limits, authentication scope, or typical use cases. Sibling tools are not differentiated.

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 baseline is 3. The description adds no additional meaning beyond the schema; parameters are already documented with examples (e.g., 'SEC' for project_key). No extra details on format, constraints, or relationships.

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 'Open a Jira issue for a security finding', specifying the verb, resource, and context. This distinguishes the tool from siblings like 'scan_vulnerabilities' or 'export_sarif' which have different purposes.

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?

No guidance on when to use this tool vs alternatives. It does not specify prerequisites beyond environment variables or indicate situations where other tools (e.g., 'upload_to_defectdojo') might be preferred. The description is purely functional.

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?

Without annotations, the description does well to disclose key behaviors: it runs all scanners, evaluates against a policy, returns a verdict, explains the -1 threshold semantics, and the interaction between 'fail_on_new' and baseline. It does not mention side effects (e.g., data mutation) or authentication requirements, but given the read-only nature implied, it is transparent enough.

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 three sentences long, front-loaded with the core purpose and outcome. Each sentence contributes unique information: first the general action and result, second the threshold semantics, third the special fail_on_new behavior. No redundant or irrelevant content.

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 context signals (9 parameters, 100% coverage, output schema exists), the description is sufficiently complete. It explains the return format (PASS/FAIL), the threshold mechanism, and the baseline condition. Some edge cases (e.g., what if no scanners are enabled?) are not covered, but the overall picture is adequate for selection and invocation.

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 parameters have individual descriptions. The description adds value by explaining the -1 threshold meaning and the condition when 'fail_on_new' causes failure relative to a baseline. This connects parameters like 'fail_on_new' and 'baseline_tag' beyond what the schema provides individually.

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 runs all scanners and evaluates findings against a CI security policy, returning an explicit PASS/FAIL verdict for pipeline gating. It uses specific verbs ('run', 'evaluate') and identifies the resource ('scanners', 'CI security policy'). It distinguishes from sibling tools like 'scan_all' which only scans or 'compliance_report' which likely just generates reports.

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 mentions the threshold behavior ('-1 means no limit') and the 'fail_on_new' option with baseline reference. However, it does not explicitly state when to use this tool versus alternatives like 'scan_all' or 'compliance_report', nor does it provide context on when not to use it. The mention of 'save_baseline' is a cross-reference but not a usage guideline.

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 provided, so description carries full burden. It discloses that the tool runs a scan and exports results, but does not mention potential side effects, authentication requirements, rate limits, or whether the scan is destructive. The description adds context about SARIF format but lacks behavioral details beyond the basic operation.

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?

Two sentences, no waste. First sentence states the core action, second adds valuable context about SARIF format and integration platforms. Efficiently structured.

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?

Output schema exists, schema coverage is 100%, and the description explains the output format (SARIF) and CI/CD integration purpose. However, it lacks guidance on when to prefer this tool over siblings like import_sarif or other scan tools. Overall, it is adequate for the given complexity and structured fields.

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?

Input schema has 100% description coverage for all 5 parameters. The description does not add parameter-specific details beyond what the schema provides, except for the context about SARIF being an industry standard. Baseline score of 3 is appropriate since schema already documents parameters adequately.

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?

Description clearly states the tool runs a SAST scan and exports results in SARIF 2.1.0 format for CI/CD integration. The verb 'run a SAST scan and export' with the specific resource 'SARIF format' distinguishes it from siblings like import_sarif or other scan-only tools.

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?

Explicitly mentions usage for CI/CD integration and lists common platforms (GitHub Code Scanning, GitLab SAST, Azure DevOps). However, it does not provide when-not-to-use guidance or compare to alternatives like import_sarif or other scan tools. The context is clear but exclusions are missing.

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 burden. It discloses behavioral details: CycloneDX vs SPDX output, dependency on Syft for full dependency lists, and derivation from findings otherwise. However, it doesn't state if the tool is read-only or modifies state, nor any authentication needs.

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 concise and front-loaded. The first sentence captures the core purpose, and the following sentences add essential details without redundancy. Every sentence earns its place, making it efficient for an AI agent.

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 tool complexity (5 params, output schema exists), the description covers key behaviors: output formats, Syft dependency, and fallback behavior. It omits potential side effects (e.g., time to run all scanners) but is largely complete. The output schema compensates for missing return value details.

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 baseline is 3. The description adds value by explaining the format parameter's behavior difference (CycloneDX with/without Syft). This goes beyond the schema's brief 'cyclonedx or spdx' and provides meaningful context for agent decisions.

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 exports an SBOM/vulnerability report after running all scanners. It specifies the resource (SBOM) and action (export), and distinguishes between CycloneDX and SPDX modes. This makes the purpose specific and distinct from siblings like 'export_sarif' or 'compliance_report'.

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 when an SBOM is needed but lacks explicit guidance on when to use this tool versus alternatives (e.g., 'export_sarif', 'compliance_report'). It doesn't mention prerequisites like scanner installation or provide when-not-to-use scenarios.

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 discloses the core behavior: recovering a finding from cache, extracting a source window, and returning a prompt for a unified diff. It doesn't cover all behavioral aspects like side effects or error conditions, but it provides sufficient context for safe invocation.

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 concise with three sentences, front-loading the main purpose. Every sentence adds meaningful context without redundancy.

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 three parameters and existence of an output schema, the description is adequate. It explains the workflow and prerequisites (scan cache). The output schema exists but is not detailed, which is acceptable as per rules. Some information about the output format could add completeness.

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 baseline is 3. The description adds value by explaining that target_path requires a '.sast-mcp-cache' directory, finding_hash comes from scan output, and context_window specifies lines before/after. This goes beyond the schema 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 builds an LLM-ready prompt to fix a cached finding as a unified diff, specifying the source recovery and output format. It distinguishes from sibling 'apply_patch' by indicating the patch should be applied after generation.

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 for generating a fix prompt before applying, referencing 'apply_patch'. However, it does not explicitly state when to use this tool versus other remediation or scanning tools, nor does it exclude alternative approaches.

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 full burden. It discloses that the tool runs all scanners before rendering, which is helpful, but lacks details on whether it modifies state, required permissions, or side effects.

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?

Single sentence that is concise and front-loaded with the core action and output format. No 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?

Given the presence of an output schema and 4 params, the description adequately covers purpose and format options. It could mention prerequisites like scanner configuration, but overall sufficient.

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 adds minimal value beyond the schema. It restates that format can be HTML or PDF, which is already in the schema.

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 runs all scanners and renders an executive security report in HTML or PDF. It distinguishes from sibling tools like 'scan_all' which only scans without generating a report.

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 use after scanning but does not explicitly state when to use this tool versus alternatives like 'compliance_report' or 'export_sarif'. No exclusion criteria or prerequisites are mentioned.

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 full burden for behavioral disclosure. It only states the high-level effect without explaining side effects (e.g., file modifications), permission requirements, reversibility, or impact on future scans.

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 a single, clear sentence that efficiently conveys the tool's purpose. It is front-loaded and contains no unnecessary 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?

Despite modest complexity (3 parameters, no nested objects), the description lacks context about the expected output, confirmation of the ignore operation, or how it interacts with sibling tools. The existence of an output schema is noted but not described.

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 covers all parameters with 100% description coverage, so the description adds no extra meaning beyond summarizing the tool's action. Baseline score of 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 the tool's action ('Ignore a specific vulnerability finding') and its effect ('so it won't appear in future scans'). It distinguishes from siblings like 'unignore_vulnerability' by specifying the suppression of results.

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 the use case (suppressing findings) but does not explicitly state when to use versus alternatives like 'triage_finding' or 'unignore_vulnerability'. No exclusions or contextual cues are provided.

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 cover behavioral traits. It mentions re-enrichment and stable hashes, but does not disclose potential side effects (e.g., idempotency, overwrite behavior, network requirements). Adequate but not comprehensive.

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 two clear sentences (with a bullet-like second line) that front-load the primary purpose and then add value with context about the pipeline. No redundancy, but the enrichment detail could be integrated more smoothly.

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 presence of an output schema (though not shown), and high schema coverage, the description covers purpose, use case, and processing details. It lacks prerequisites or error handling, but is fairly complete for a data import 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?

Schema coverage is 100%, with each parameter having a concise description. The tool description adds little to parameter semantics beyond stating the overall pipeline flow. Baseline 3 is appropriate as the schema already does the heavy lifting.

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 'Ingest an external SARIF file into the normalized finding pipeline' – a specific verb+resource. It clearly distinguishes from sibling tools like export_sarif and scan_* commands by focusing on importing external results. The usage context is explicit.

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 explains that the tool allows results from any SARIF-producing tool to join native flows, which implies when to use (external SARIF ingestion). It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent.

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 cover behavioral traits. It mentions 'currently ignored' but does not explicitly state that the tool is read-only, safe, or that no changes are made. It lacks details on authentication requirements or side effects.

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 a single sentence with no unnecessary words. It is front-loaded and direct.

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 simplicity of the tool (one parameter, output schema present), the description is adequate but minimal. It does not explain the return format, pagination, or any filtering behavior beyond 'currently ignored'. Slightly more context would improve completeness.

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 baseline is 3. The tool description does not add any additional semantic information beyond what the schema already provides for the 'target_path' 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 the verb 'list' and the resource 'ignored vulnerability findings for a project'. It distinguishes the tool from sibling tools like 'ignore_vulnerability' and 'unignore_vulnerability'. However, it could be more specific about the scope and that it is read-only.

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?

There is no guidance on when to use this tool versus alternatives like scanning or triage tools. The description does not provide any prerequisites, examples, or exclusions.

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 fully carries the transparency burden. It accurately describes a read-only operation with no side effects, detailing what information is returned (installed status, supported languages, installation instructions).

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 concise at two sentences, with the main purpose in the first sentence. Minor improvement could be trimming 'Returns information about each scanner including' but overall 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?

Given the simple operation (no parameters, expected output schema present), the description adequately covers what the tool returns. The mention of installed status, languages, and installation instructions is sufficient.

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?

There are no parameters, so the schema coverage is 100% by default. The description adds no parameter info, but the baseline score for 0 params is 4. Given the clarity of the output, a 5 is warranted.

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 lists all available SAST scanners, their status, and supported languages. This distinctively separates it from sibling tools that perform scans or manage vulnerabilities.

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?

While no explicit 'when to use' vs alternatives is provided, the context implies use for discovering available scanners before selecting one. Since there are no similar listing siblings, the purpose is clear enough.

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 provided. Description lacks disclosure of side effects, rate limits, error behavior, or output format. Only mentions the action and a configuration requirement.

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?

Two sentences, front-loaded with the core action. Every sentence provides necessary information without fluff.

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 notification tool with one parameter and an output schema, the description covers the main requirement and action. Could mention that the webhook must be correctly configured, but overall adequate.

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% and the parameter description in the schema is clear. The tool description does not add additional meaning beyond what the schema already provides.

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?

Clearly states the verb (send a notification) and resource (Slack incoming webhook). Distinguishes from sibling tools like notify_teams by specifying the platform.

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?

Specifies a prerequisite (SLACK_WEBHOOK_URL environment variable) but does not explain when to use this tool versus alternatives like notify_teams or other notification methods.

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 provided; description only states the primary action without detailing side effects, idempotency, error handling, or any behavioral traits beyond sending a notification.

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?

Two sentences, no wasted words, and the key information is front-loaded.

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?

Tool is simple but lacks mention of return values (output schema exists), failure behavior, or confirmation. Adequate for a straightforward notification but could be improved.

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% and descriptions already cover meaning. The tool description adds no additional semantic value beyond what the schema provides.

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?

Description clearly states the action ('Send a notification') and target ('Microsoft Teams incoming webhook'), distinguishing it from sibling tools like notify_slack.

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?

Mentions a prerequisite (TEAMS_WEBHOOK_URL environment variable) but gives no explicit guidance on when to use vs. alternatives or when not to 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?

No annotations are provided, so the description carries full burden. It discloses the full process: scan, dry-run, re-scan before/after, PASS conditions, and auto-rollback behavior. The only omission is potential side effects like file locking, but it clearly states the working tree is left clean.

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 ~100 words, front-loaded with the core action, and each sentence adds value. Efficient and well-structured.

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?

An output schema exists, so return values need not be detailed. The description covers the remediation loop fully, including failure handling. For a parameter-heavy tool, it is 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% (baseline 3). The description adds value by explaining the purpose of auto_rollback and noting that patch can be produced via generate_fix_prompt. It also clarifies scanner_name fallback behavior. A 4 is appropriate for the extra context.

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 'Apply a fix and prove it worked: scan → patch → re-scan → confirm gone.' This verb+resource summary distinguishes it from siblings like apply_patch by emphasizing the verification loop.

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 context through 'The closed remediation loop' and details about recovery, dry-run, and re-scan. However, it does not explicitly contrast with siblings or state when not to use, so a slight deduction from perfect.

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 provided, so description carries burden. It discloses orchestration steps (Docker Compose, waiting, ZAP scan) but omits potential impact on running instances, permissions needed, or rate limits. Adequate but not thorough.

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?

Two concise paragraphs, front-loaded with key action and contrast. Every sentence adds value with no redundancy.

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?

Complex tool with three parameters and an output schema. Description covers the main process but could mention prerequisites like Docker installation or non-destructive nature. Mostly 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% with clear descriptions. Description adds no extra meaning beyond the schema; baseline score of 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?

Clear verb 'Run an active dynamic scan (DAST)' specifies resource (DAST/OWASP ZAP) and action. Contrasts with SAST and sibling tools, distinguishing its purpose effectively.

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?

Description states it's for DAST vs SAST, providing context. However, it does not explicitly list when not to use or name alternatives, though the sibling list offers implicit choices.

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 bears full responsibility for behavioral disclosure. It fails to mention that running 'save_baseline' with the same 'tag' will overwrite an existing baseline, or whether the scan results are persisted beyond the current session. The impact on system state is unclear. The description only states the action without side effects.

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 a single sentence that is front-loaded with the action. It is concise without filler. However, it could be structured to include a brief note on usage context, but remains above average.

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 explain return values. The description is adequate for a tool with 5 parameters all described. However, a mention that the saved baseline can be used with 'compare_baseline' would improve completeness. Still, it covers the core functionality.

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% (all 5 parameters are described in the schema). The description does not add any extra meaning beyond the schema, meeting the baseline expectation.

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 runs a scan and saves results as a named baseline for future comparison. It uses specific verbs 'run a scan' and 'save', and the resource 'baseline'. This distinguishes it from sibling scanning tools like 'scan_all' and 'run_active_scan' which do not save baselines, and from 'compare_baseline' which compares existing baselines.

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?

No guidance is provided on when to use this tool versus alternatives. It does not mention that this tool is appropriate for establishing a baseline for later comparison with 'compare_baseline', nor does it exclude scenarios where a simple scan without saving is needed. No exclusion criteria or alternative tool references are given.

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 provided, so description carries full burden. Discloses parallel execution, automatic scanner detection, and content-based deduplication. Lacks details on caching or nondestructive nature, but parameter descriptions cover some 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?

Three sentences, front-loaded with core action, no superfluous words. Efficient and clear.

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?

Covers main functionality, parallelism, deduplication, and recommendation. With output schema present, return values are documented. Missing some details like caching behavior or prerequisites, but sufficient for a scan 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?

Schema description coverage is 100% with thorough parameter descriptions. Tool description adds no new parameter-specific meaning beyond overall purpose. 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?

Description uses specific verb 'scan', resource 'ALL installed scanners', and outcome 'deduplicated results'. Clearly distinguishes from sibling tools like scan_git_history or scan_image by being comprehensive.

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?

States 'This is the recommended tool for comprehensive security scanning', implying use for broad scans. Does not explicitly list when to avoid or alternatives, but context with sibling tools makes it clear.

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 full burden. It discloses using Gitleaks, analyzing .git directory, and finding API keys/passwords/tokens. However, it omits potential side effects like performance impact, required dependencies, or error handling.

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 concise at 4 sentences, front-loaded with the main action, and efficiently contrasts with traditional SAST without unnecessary 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?

The description explains the tool's purpose and value well. Given the existence of output schema and full parameter documentation, it is reasonably complete, though a note on prerequisites (e.g., Git installed) would improve it.

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 parameters are already documented. The description adds no additional meaning to parameters beyond what the schema provides.

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 it scans git history for leaked secrets using Gitleaks, and distinguishes it from traditional SAST that scans current files. Among sibling tools like scan_image or scan_vulnerabilities, this is uniquely focused on git history secrets.

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 explains when to use (to find past committed secrets missed by SAST) and contrasts with traditional SAST. It does not explicitly state when not to use or name alternative tools, but the context is clear.

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 bears full responsibility. It discloses that the tool pulls and analyzes images, implying network usage, but does not detail potential side effects like large data transfers, authentication needs, or performance impact. The read-only nature is not explicitly confirmed.

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 concise, front-loaded with the main purpose, and uses clear language. Every sentence adds value without redundancy. It is well-structured and easy to read.

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 scanning tool with an output schema, the description mentions the normalized findings format, which partially covers output. However, it does not address potential failures (e.g., image not found, pull errors), time/network costs, or how it differs from sibling tools like scan_all. This leaves gaps for an AI agent to infer.

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%, providing baseline 3. The description adds context for the image_ref parameter with example formats (e.g., nginx:1.25) and explains the tool's purpose container-specific, but other parameters like scanner_name and min_severity are adequately covered by schema descriptions. The added value is marginal.

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 container images for vulnerabilities and secrets, uses Trivy/Grype, and returns normalized findings. It specifies the resource (container image) and the action (scan, pull, analyze). However, it does not explicitly distinguish itself from sibling tools like scan_all or scan_vulnerabilities, which may have overlapping scope.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or specific use cases. An agent would have to infer usage context from the tool name and examples alone.

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 convey behavioral traits. It only says 'scan' and 'SAST tool', leaving out whether the tool is read-only, requires permissions, or modifies the target.

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 one sentence, which is concise but lacks structure. It is too brief to convey critical information about the tool's capabilities and limitations.

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 9 parameters and many siblings, the description is incomplete. It omits details about prerequisites, scanning behavior, and how results are returned (though output schema exists).

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% with detailed parameter descriptions. The tool description adds no additional parameter-specific meaning beyond what the schema already provides, meeting 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 clearly states the tool scans a directory for vulnerabilities using SAST, but does not differentiate it from sibling tools like scan_all or scan_image that may also scan directories.

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?

No explicit guidance on when to use this tool versus alternatives such as scan_all or scan_git_history. The description only implies usage for scanning a specific directory.

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 provided, so the description carries full burden. It discloses two behavioral modes but omits side effects, permissions, or state changes (e.g., recording a VEX decision is a write operation). No contradictions.

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?

Extremely concise single sentence, front-loaded with verb and resource. Could be more structured (e.g., two bullet points) but no 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?

Given no annotations but presence of output schema, the description covers the tool's two modes. However, it lacks explanation of the exploitability prompt concept and does not discuss return values or prerequisites, leaving gaps for an agent.

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% with descriptions for all 4 parameters. The description adds context linking disposition/justification to VEX decisions, but does not significantly enrich beyond schema details.

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: 'Triage a finding' with two specific modes (get exploitability prompt, record VEX decision). It distinguishes from siblings by focusing on triaging a single finding, unlike scanning or reporting tools.

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 when to use (triage a finding) but provides no explicit guidance on when not to use or alternatives among related siblings like 'ignore_vulnerability' or 'remediate_and_verify'.

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 convey behavioral traits. It accurately states that the vulnerability will reappear in future scans, but it does not disclose required permissions, reversibility, or impact on past scan results.

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 a single sentence that efficiently conveys the tool's core function. Every word is necessary, and there is no extraneous information.

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 simplicity (2 required params) and the presence of an output schema, the description covers the essential behavior. However, it may leave some operational details unstated, such as error handling or preconditions.

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?

Both parameters have schema-level descriptions covering 100% of the properties. The tool description adds no additional explanation for the parameters beyond what the schema already provides.

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 action ('Remove a vulnerability from the ignore list') and the resulting effect ('so it appears in future scans again'). It distinguishes itself from sibling tools like 'ignore_vulnerability' and 'list_ignored_vulnerabilities' by specifying the inverse operation.

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 does not provide explicit guidance on when to use this tool versus alternatives. While the purpose is clear as the inverse of ignore_vulnerability, the description lacks contextual cues or prerequisites 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, description discloses the action (upload), environment requirements, and prerequisite file generation. Lacks details on side effects (e.g., overwrite behavior, idempotency) but provides basic behavioral context.

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?

Two sentences: first states purpose, second gives prerequisites. No extra words, front-loaded with the main action.

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?

Covers environment setup and a key dependency (export_sarif). Since an output schema exists, return values are not needed. Could mention error scenarios or authentication steps, but is adequate for a straightforward upload 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?

Schema coverage is 100%, so description does not need to add much. It reinforces that sarif_path comes from export_sarif and engagement_id is numeric, but adds no new semantic meaning beyond the schema 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?

Description clearly states the tool uploads a SARIF report to a DefectDojo engagement, specifying the resource type and target. It distinguishes from siblings like export_sarif (generates) and import_sarif by focusing on uploading to an engagement.

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?

Provides explicit prerequisite: generate the SARIF file with export_sarif first. Mentions required environment variables. Does not explicitly state when not to use, but the context implies it is only appropriate when you have an engagement ID and a SARIF file.

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 convey behavioral traits. It mentions the required token and that the tool uploads (a write operation). However, it does not disclose potential side effects, rate limits, or confirmation of success/failure. This is adequate but not thorough.

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: two sentences conveying purpose, prerequisite, and workflow. No wasted words, and the critical information is front-loaded.

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 (4 required params, output schema present), the description covers the essential workflow (export first, upload) and prerequisite. It assumes the output schema documents return values, which is acceptable. The only missing part is optional behavior or error scenarios, but overall 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 input schema has full description coverage (100%), so each parameter's purpose is already documented. The description adds no extra meaning beyond the schema, mentioning only the token requirement not in the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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 action ('Upload a SARIF report') and the target system ('GitHub Code Scanning'), using a specific verb and resource. It differentiates from siblings like 'export_sarif' (which exports locally) and 'import_sarif' (likely different scope).

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 notes prerequisites: the GITHUB_TOKEN with required scope and the need to first call export_sarif. This gives clear when-to-use guidance. However, it does not explicitly state when not to use this tool or mention alternative tools like import_sarif.

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