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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds non-redundant behavioral details: mentions large SBOMs may take up to 10 seconds, returns CVEs grouped by package, and a 1-hour cache. It reinforces the read-only, no-side-effects, idempotent nature without contradicting annotations.

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 mostly efficient, but slightly verbose with redundant confirmations of read-only and idempotent nature already covered by annotations. However, every sentence adds value (usage guidance, parameter details, cache info). It loses a point for minor repetition but remains effective.

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 complexity of auditing an SBOM, the description covers all key aspects: input format and requirements, performance expectations, output structure (CVEs grouped with severity and fixed versions), caching behavior, and clear alternatives. The presence of an output schema (signaled in context) further complements completeness. No gaps are apparent.

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% for the single required parameter sbom_json. The description adds meaning beyond the schema: specifies accepted formats (CycloneDX or SPDX), mentions performance impact for large SBOMs, and explains the return format (CVEs grouped). This significantly aids the agent in understanding the parameter's scope and behavior.

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 starts with 'Audit a Software Bill of Materials for known vulnerabilities across all listed packages,' clearly stating the verb (audit), resource (SBOM), and scope (all packages). It distinguishes from sibling tool security_fetch_package_vulnerabilities, which checks single packages. The description also mentions the verified source and caching, adding further clarity.

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 states when to use this tool ('when you have a full SBOM to audit') and when to use an alternative ('Use security_fetch_package_vulnerabilities instead when checking a single package version'). It also provides a fallback mechanism via report_feedback, giving complete guidance on usage context.

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