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

While annotations declare readOnlyHint, openWorldHint, and idempotentHint, the description adds critical behavioral details: payment requirements (USDC/x402, Bearer key), the specific HTTP error-response flow, and the guarantee that each returned row carries an 'affected' list and numeric severity_score. It also explains that a buyer can act directly on the row without an extra hop, which is non-obvious 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?

The description is structured with clear intent: purpose, use cases, payment, error handling, and result structure. Each section is dense but not padded. It front-loads the purpose and usage immediately, making it easy for an agent to evaluate relevance without reading the full text. No redundant sentences.

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 payment authentication complexity, error recovery steps, and rich output semantics, the description covers everything an agent needs to invoke correctly. It even addresses optional parameters (min_severity) with practical guidance. The existence of an output schema means return-format details aren't strictly required, but the description still provides enough context for acting on results.

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 four parameters, so the baseline is 3. The description adds value by explaining the 'affected' list structure ('ecosystem, name, vulnerable_range, patched_range') and severity_score semantics (CVSS baseScore, nullable on OSV-only rows). It also gives concrete min_severity thresholds ('Use 7.0 for high+critical only, 9.0 for critical only'). This goes beyond the schema's terse 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 explicitly states the tool queries a 'daily snapshot of CVE / supply-chain advisories from NVD, GitHub Security Advisories, and OSV' and gives specific use cases ('before merging dependency updates, when triaging an alert, or when a user asks...'). This clearly differentiates it from sibling search tools like query_markets or query_papers.

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 when-to-use guidance with concrete scenarios and also outlines the exact flow for handling payment_required errors (fillin_probe → fillin_signup or fillin_payment_challenge). This goes beyond vague context and gives an agent a decision path.

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