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

Annotations already declare readOnlyHint, idempotentHint and non-destructive; the description's real additions are the 5-credit cost and the plan-tier/archive-depth gating, which are genuinely useful and not in structured fields. It still says nothing about result volume, pagination behaviour, or what happens when the requested date falls outside the plan's archive window.

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, all load-bearing: what it returns, what it costs, who can reach which date range. The core definition is front-loaded with no preamble or filler.

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 shape need not be described. Cost and plan gating are disclosed, which is the main hidden complexity for a 10-parameter read tool. The remaining gap is coverage of the pagination and filtering parameters, which neither the schema nor the description fully explains.

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 50%, and the schema itself documents date, venue, country, race_id and categories well. The description adds meaning to the `signal` parameter by listing its classes and to `from_date`/`to_date` by revealing the 90-day vs full-archive window, but says nothing about limit, offset or how the signal filter interacts with the archive limits.

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 — per-runner market summary for past races — and enumerates exactly what it contains (opening/closing consensus, the move, and its signal class). The signal-class taxonomy (strong_firm through strong_drift) distinguishes it from siblings like market_movers and closing_lines, though it never names an alternative directly.

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?

The description supplies access conditions ('Standard and above (last 90 days); Plus and above for the full archive') and a cost, which gives the agent context on when the call is available. However, there is no guidance on when to choose this over market_movers, odds_changes or closing_lines, so selection between siblings is left to inference.

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