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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) to explain the semantics of statuses and authorities, how to interpret 'unknown' and null fields, and that exploitation status is never falsely reported from a partial catalog. It also warns about deprecation and the tool not being refreshed. This is comprehensive behavioral disclosure that the annotations alone do not provide.

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 long and front-loaded with the deprecation notice, which is important information that should be prominent. It packs a significant amount of behavioral detail in a structured way, moving from deprecation warning to core function to interpretation rules. It is not overly verbose relative to the complexity it conveys, but it could be more concise by trimming some redundancy (e.g., repeating 'status' explanations). The structure is logical: warning, purpose, and interpretation guidance.

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 (returning structured claims with authority semantics, handling unknowns, nulls, and partial catalog behavior), the description covers all necessary aspects: what it returns, how to interpret statuses and authorities, what null means, and the deprecation timeline. The output schema is absent, so the description must explain the return format, and it does sufficiently for an agent to understand the results. The annotations cover safety, so the description doesn't need to repeat them. This is complete for the tool's purpose.

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 only one parameter 'cve' with minLength 1, and no description in the schema (coverage 0%). The tool description explains that the parameter is a vulnerability identifier such as a CVE, which adds some meaning. However, the schema is minimal and the description doesn't specify expected format (e.g., 'CVE-2024-1234') beyond the example, but since there is only one parameter, the description is sufficient to guide invocation. The baseline for 0 params is 4, but here there is one param, and the description covers it adequately, so 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 looks up a vulnerability by identifier (e.g., CVE) and returns held evidence about it, including affected package, version range, fix version, severity, and known-exploited status. It distinguishes itself from sibling tools like discover_daystruct_capabilities and compat_check by naming them explicitly as alternatives for building. However, the purpose is slightly muddled by the deprecation notice and the extensive behavioral detail, which could distract from the core 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?

The description provides explicit usage guidance: it is for when you have an identifier rather than a package you are running, and it names specific alternatives (discover_daystruct_capabilities and compat_check) for building use cases. It also warns that the tool is deprecated and will be removed, effectively telling the agent when not to use it. This is strong, clear routing.

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