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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds genuinely non-obvious behavior: a per-call cost of $0.002 USDC settled via x402 on Base, Solana or Arc, with failed calls not charged, plus a hard cap of 20 codes per call. That payment/auth detail is exactly the kind of context annotations cannot carry. It stops short of describing failure modes or empty-result behavior, so not 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: what it searches and returns first, the critical scope exclusion second, the operational limits and pricing last. No filler, nothing repeated from the name or annotations.

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 a 2-parameter schema at full coverage, an output schema, and read-only annotations, the description covers the remaining agent-relevant facts: source provenance, CPT exclusion, result cap, and cost. Missing only edge-case behavior such as zero-match handling or whether `term` is substring vs. token matching.

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 in the schema. The one addition — 'Up to 20 codes per call' — reinforces the `max` ceiling but adds no new syntax or format guidance beyond the schema's '1 to 20 (default 10)'. Baseline 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?

States a specific verb and resource ('HCPCS Level II billing code search'), names the authoritative source (CMS code set via NLM Clinical Tables), the covered domain (procedures, supplies, drugs), and what is returned (code, short description, total match count). The explicit exclusion of AMA-licensed CPT codes draws a clean boundary that separates it from other coding tools like health_icd10_cm_diagnosis or health_loinc_laboratory_codes.

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 scope statement ('HCPCS Level II... procedures, supplies and drugs') implies when the tool applies, and the CPT exclusion tells the agent when it does not apply. But no alternative tool is named for the CPT or diagnosis-code case, and there is no explicit 'use this when...' routing guidance among the many health coding siblings.

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