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

Annotations already declare readOnly/idempotent/destructive=false, and the description adds the behavior those hints cannot express: the tool is a polling endpoint with distinct queued/running states, a retry_after_s field to honor, and a 'full Forecast' payload once complete. It also notes the result is free and verifiable via commitment_hash, which is real context beyond the 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?

Purpose and polling behavior are front-loaded and the Forecast field enumeration is informative, but the trailing sentence 'Use only to poll a forecast_id returned by oracle_forecast (free).' repeats content already stated in the first and second sentences and earns no place.

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?

There is no output schema, and the description compensates well by enumerating the returned Forecast fields and the interim status shape with retry_after_s. It stops short of stating what happens on an unknown/expired id or how aggressively to re-poll, so it is strong but not fully closed.

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?

With one parameter at 100% schema description coverage, the schema already defines forecast_id and its provenance. The description restates the same origin (returned by oracle_forecast, listed by oracle_board / oracle_track_record) without adding format, constraint or validation detail, so the baseline 3 applies.

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+resource ('Poll or retrieve an oracle forecast') and immediately contrasts with the sibling that creates forecasts ('Use after oracle_forecast'). An agent can distinguish this from oracle_forecast, oracle_board and oracle_track_record without opening any 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?

Explicitly names the entry points (oracle_forecast, oracle_board, oracle_track_record) and the ordering ('Use after oracle_forecast'), so the agent knows when this tool is the right call. Minor deduction: the closing sentence 'Use only to poll a forecast_id returned by oracle_forecast' narrows the source of the id in a way that mildly conflicts with the earlier mention of oracle_board / oracle_track_record as id sources.

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