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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses pricing ($0.05 per call), a free-tier quota (3 calls/day per IP, 3 rows, with the _meta skip escape), deterministic read provenance via sha256, and a detailed freshness/confidence decay model. These are exactly the operational traits an agent cannot get from structured fields.

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?

It is one dense paragraph, but it is front-loaded with the core purpose and every subsequent clause (pagination, price, free tier, confidence, disclaimer) carries real information. The confidence-decay sentence is verbose but not wasteful given no output schema.

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 does the work of describing return content (record fields, sha256 citation) and pagination, plus operational constraints, so an agent can call it correctly. The remaining gap is the entity enum's precise meaning and how since interacts with effective_from.

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 only 50%, so limit, cursor and entity carry no schema docs. The description compensates partially (page size up to 100, oldest-first ordering, cursor round-trip) and loosely maps entity values via 'rates that change' and 'new files posted', but leaves the enum and the since/effective_from distinction under-explained.

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 opening sentence names a specific resource (change records from the states' rate and boundary files) and enumerates exactly what changes are captured (rate begin/end, jurisdiction shifts, new files). This clearly separates it from the current-rate siblings like tax_sales_rate, since it is a change-history feed rather than a rate lookup.

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 rather than stated: the change-record framing tells an agent it is for tracking what changed, and pagination instructions ('pass next_cursor back as cursor') are given. However, it never explicitly says when to prefer this over tax_sales_rate or tax_sales_rate_batch, leaving the choice to inference.

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