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

Annotations already cover the safety profile (readOnlyHint, idempotentHint), and the description goes well beyond them, disclosing the exact result buckets (direct claims, range_affected_cves, all_versions_cves, shadowed_range_cves) and how affected_total is composed. It also flags a genuine semantic caveat: fix_stated_by_source=false means the fix was derived from a range bound rather than stated by the vendor. Gaps: no mention of truncation/pagination behavior from limit, and no guidance on error cases or empty 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 core question is correctly front-loaded, but the remainder is a single dense run-on paragraph of jargon (shadowed_range_cves, open-start entries, restated branches) that is hard to parse on one read. Every clause is arguably substantive, yet the material would be far more usable as a short bulleted breakdown of the four result buckets.

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?

With no output schema, the description carries the return-value burden and does so thoroughly - defining four buckets, the affected_total arithmetic, and the fix_stated_by_source caveat. What is missing for a paginated, parameterized query is any statement about result limits or truncation and about what an unknown product/version returns.

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 product, version, role and limit are already documented with examples and defaults in the schema. The description adds nothing about the role or limit parameters - notably it never explains that results can be narrowed to 'affected' or 'fix' only, despite describing both categories at length. Baseline 3 applies when the schema carries the parameter burden.

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?

Opens with a specific, verb-driven scope statement: 'which CVEs affect this exact version of a product, and which version fixes each'. That is a clear resource+scope an agent can match to a request, and the scope ('exact version') implicitly distinguishes it from product-level siblings like product_cves. It stops short of naming an alternative, so the boundary is inferred rather than stated.

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?

Framing the tool as 'the core question' signals it is the default entry point, which is weak but real usage guidance. There is no explicit when-to-use vs. when-not, no mention of lookup_cve or product_cves as alternatives, and no stated preconditions (e.g. does the product need to be tracked first?).

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