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

With no annotations provided, the description carries the full burden of disclosing behavior. It explains important nuances: the meaning of fix=0 ('computed-and-none-held, never no fix exists'), what detect tracks ('detection content we track'), and the ordering for filter-only queries (KEV-first then EPSS). This adds valuable context, though it does not cover all possible behavioral aspects like rate limits or output shape.

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 dense but efficiently structured. It starts with the main purpose ('Search the catalog') and then lists filters in a logical, comma-separated fashion with inline explanations. Every sentence adds information, and the length is appropriate for the tool's 14 parameters. There is no redundancy or filler.

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 (14 parameters), absence of annotations, and no output schema, the description is remarkably complete. It covers the search scope, all input semantics, special behaviors (fix=0, ordering), and a pointer to an alternative tool. It even notes the default ordering for filter-only queries. This leaves the agent well-equipped to decide when and how to invoke the tool.

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 has no descriptions, and the description fully compensates by explaining each parameter's format, allowed values, and examples. For instance, it clarifies vendor as a slug, cwe as 'CWE-nnn', year as '2024,2025', sev as 'critical,high', and epss_gte as 0..1. It also provides a concrete package example and notes the limit range. This goes far beyond the bare schema.

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's function: 'Search the catalog.' It specifies that it supports free text and structured filters, and it differentiates from sibling tools by noting that for package ranges, one should use query_package. This makes the purpose unambiguous and distinct from other tools.

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 clear usage context by enumerating the filter parameters and explaining filter-only query behavior. It explicitly points to query_package for ranges, offering an alternative. However, it does not explicitly state when NOT to use this tool (e.g., for retrieving a single CVE, use get_cve), so it falls short of a full 5.

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