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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered; the description adds the non-obvious default behavior (no since = last hour) and the near-real-time staleness caveat, which are genuinely extra context. It stops short of describing response shape, ordering, or truncation behavior when limit is hit, which matter for a polling feed.

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 sentences plus a parenthetical example, front-loaded with what it is, then how to use it, then the alternative it displaces. The only mild restatement is the last-hour default, which also appears in the schema, but it is load-bearing for the polling guidance.

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 4-parameter, all-optional read feed with no output schema, the description gives enough to call it correctly: cursor strategy, default window, filter vocabulary, and the monitoring-vs-search decision. Remaining gap is what the returned change objects contain and how to advance the cursor under limit truncation.

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 coverage is 100%, so baseline is 3; the description earns above that by explaining the cursor contract in operational terms ('everything newer than your cursor', vs the schema's 'newest timestamp you have already seen') and by enumerating valid reason values that the schema only gives as an example list without an enum constraint.

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 resource and shape: a near-real-time change feed backed by GET /v1/changes, and immediately distinguishes it from re-scanning search_bills. The enumerated reason types (NewBill, StatusChange, Text, Vote, Amendment) tell an agent exactly what kind of content the feed carries.

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 names the use case (monitoring, incremental sync, 'what moved in Florida since yesterday') and the alternative it replaces (re-scanning search_bills). Polling semantics are stated as a directive — pass since as your cursor — leaving no inference needed about incremental usage.

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