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

Annotations already cover read-only and open-world behavior, but the description adds genuinely new operational context the agent cannot get from structured fields: this is a paid tool ($0.002 USDC per successful call, x402 on Base/Solana/Arc) with failures not charged, and a 20-result ceiling. That payment requirement is critical pre-call information. It does not describe pagination or whether a truncated match list is signalled, which keeps it from a 5.

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?

Three compact sentences, front-loaded with purpose and scope before the cost detail. Every clause carries distinct information (source, return shape, exclusions, limit, price), with no repetition of the title or schema fields beyond what is needed for the cap.

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?

For a two-parameter lookup with full schema coverage and an output schema, the description supplies everything operationally necessary: source authority, output contents, result ceiling, and the payment model that gates the call. The remaining gap is match semantics—an agent cannot tell how strict 'matching' is, which affects how it forms the 'term' string.

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 both 'term' and 'max' are already documented with ranges and defaults, making 3 the baseline. The description only restates the cap ('Up to 20 codes per call') and adds no matching semantics—whether 'term' is prefix, substring, or token-matched—which is the one parameter detail that would actually add value.

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?

States a specific verb and resource ('ICD-10-CM diagnosis code search') plus the exact payload returned ('matching codes and their official names, with the total match count'). The explicit exclusion ('Codes and names only; no cross-walks or clinical descriptions') separates it from siblings like health_cpt_hcpcs_procedure or health_loinc_laboratory_codes without the agent opening either schema.

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?

Clear usage context: it names the source code sets (NLM Clinical Tables, CDC), the hard cap ('Up to 20 codes per call'), and scope exclusions that tell an agent when this is the wrong tool (no cross-walks, no clinical descriptions). It stops short of naming the alternative sibling to use for cross-walks or procedure codes, so routing is implied rather than explicit.

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