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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well past them: per-page pricing (USD 0.05, no free tier, empty poll free), typical latency, 410/422 error semantics with the 'not charged' guarantee, cursor expiry on snapshot changes, suppressed sampled removals, and a 4096-char ID exclusion. It also flags listed endpoint data as untrusted input that must not be treated as instructions.

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?

Purpose is front-loaded and almost every clause carries operational value (cost, ordering, error codes). The telegraphic, semicolon-chained style compresses well but reads as a dense block, making the cursor workflow rules slightly harder to scan than they could be.

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 paid, cursor-paginated, mutating-cursor-state tool, the description covers cost model, pagination lifecycle, error handling, latency, and trust caveats. An output schema exists, so the absence of return-shape details is not a gap.

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%, and the description still adds meaning beyond it by tying each cursor name to its producer (next_cursor, refresh_cursor, bulk delta_cursor) and clarifying that a null baseline means bulk-unfiltered. It does not add anything for limit or source beyond the schema, so it is strong but not exhaustive relative to the schema baseline.

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 — 'refresh a local x402/MCP index' — and immediately bounds scope to 'net additions, removals and price changes.' It also distinguishes itself from the sibling bulk_agent_index by naming it as the snapshot prerequisite, so an agent can route correctly without opening a schema.

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?

Explicit sequencing rules: 'For a starting snapshot use bulk_agent_index, then pass its delta_cursor as cursor,' 'Give since OR cursor,' 'follow next_cursor, then save refresh_cursor,' and the exclusion 'After bulk, use its delta_cursor, not since.' It also names the alternative summary endpoint for latest dates. This is a full when/when-not/alternative map.

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