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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial behavioral context beyond that: pagination behavior, oldest-first ordering, per-call pricing, free-tier conditions, confidence decay tied to build freshness, and legal caveats about posted rates. It also clarifies that records are deterministic diffs rather than advisory or quote data, which meaningfully informs agent use.

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 front-loads the core purpose and then organizes the remaining information into keys, money units, pagination, pricing/free-tier rules, confidence, and legal notes. It is dense but mostly earns its space, though the long single block of text could be structured more easily for an agent to scan.

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 carries the return-shape burden and does so well: it defines record categories, composite keys, the usd_micro money unit, sha256 provenance, pagination limits, cursor handling, and confidence semantics. Given the tool's complexity and lack of an output schema, this is complete enough for correct invocation.

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 the schema already documents limit, since, and cursor. The description adds relevant pagination semantics by specifying pages of up to 100 are returned oldest first and that next_cursor should be passed back as cursor, which supplements the cursor parameter beyond its schema text.

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 states a specific resource and scope: change records derived from diffing consecutive weekly hospital builds, with enumerated record types such as republished files, item/rate additions/removals/price changes, status changes, and payer-name changes. It is clearly not a current-price or payer-list tool, but it does not explicitly name or differentiate itself from sibling tools like hospital_prices or hospital_payers.

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?

Usage is implied by the paged-feed framing and operational notes about cursor reuse, oldest-first ordering, free-tier limits, and row caps. However, the description does not explicitly say when to choose this tool over alternatives such as hospital_prices or hospital_compare, nor does it give when-not-to-use guidance.

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