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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds a genuinely non-obvious behavioral trait — that matching happens against CPE vendor/product strings with the exact examples ('apache' + 'log4j', 'windows_10') — which is exactly the kind of detail annotations cannot carry.

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?

Front-loaded with example query strings, followed by purpose, use cases, and the CPE constraint. Three near-synonymous query examples is slightly redundant, but every sentence carries actionable content, and the most critical constraint (CPE spelling) lands last with emphasis.

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 still implies what comes back (vulnerabilities recorded against the vendor/product pair) and the schema's limit parameter covers result capping. It is complete enough to call correctly, though it says nothing about result ordering or pagination beyond the limit.

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, and the description earns above it by explaining the matching semantics of vendor/product (CPE strings, not marketing names) and supplying real example pairs, adding meaning beyond the schema's short field hints.

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?

Uses a specific verb (search) and resource (CIRCL Vulnerability-Lookup vulnerabilities) scoped to a vendor/product pair, with illustrative query phrasings. However, it never names nearby siblings circl_vuln or circl_vuln_recent, so the boundary between them must be inferred from the scope wording 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?

Gives concrete use contexts (software inventory triage, dependency review, vendor risk assessment) and the crucial prerequisite that inputs must be CPE strings, not marketing names. It stops short of stating when NOT to use it (e.g., a single CVE lookup belongs in circl_vuln), leaving that inference to the agent.

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