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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond them: geographic scope ('US only'), result limits ('Returns up to 10 matches'), data provenance ('Verified source: NPPES NPI Registry (CMS)'), freshness ('24-hour cache'), and the feedback loop behavior. The 'Read-only. No side effects. Idempotent.' phrasing is consistent with annotations; no contradiction.

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 but every clause earns its place: purpose, safety traits, scope, limits, parameters, return shape, alternatives, source, cache, and fallback. It is front-loaded with the core purpose. A minor deduction for being a single dense run-on paragraph and for partially repeating annotation facts ('Read-only. No side effects. Idempotent.'), though repetition is defensible since descriptions are not always shown alongside 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?

An output schema exists, so return values are covered structurally. The description supplies everything else an agent needs to call it correctly: parameter requirements and defaults, geographic and result-limit constraints, data recency, source authority, the sibling alternative, and the report_feedback fallback for failure cases. Nothing material is missing for a search tool of this complexity.

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 baseline 3 applies. The description largely restates the schema's parameter text (name, state, speciality) with the same examples (CA, Cardiology), adding only light value by mapping parameters to the return fields. It does not introduce meaningfully new parameter semantics beyond what the schema already documents.

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: 'Search the NPPES NPI Registry by provider name with optional state and speciality filters.' It also names the return fields and the sibling it is not ('Use compliance_fetch_npi_provider instead when you have the exact 10-digit NPI'), so an agent can distinguish this search-by-name tool from the fetch-by-NPI tool without opening schemas.

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?

Explicitly states when to use this tool ('Use this when you do not have the NPI number') and names the alternative with its trigger condition ('Use compliance_fetch_npi_provider instead when you have the exact 10-digit NPI'). It also prescribes a fallback behavior via report_feedback with concrete arguments, leaving nothing to inference.

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