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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: thin buckets (<30 windows) withhold rates and intervals entirely, venues are never pooled and venues_pooled is always false, coverage fields reveal gaps in the store, and fill-price fields exist only for polymarket.com. It also warns that net_edge_distinguishable_from_zero is false for most cells, which prevents a serious misreading of the output.

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?

Front-loaded with the core definition in the first two sentences, then organized into clearly demarcated sections (why an archive, venue pooling, intervals, thin cells, coverage, fill price). It is long for a 6-parameter read tool, and the "WHY AN ARCHIVE EXISTS AT ALL" paragraph — including a dated measurement anecdote — is the most trimmable material, but nearly every remaining sentence carries behavioral information.

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, so the description must carry the return contract, and it does: it enumerates every grid field (n, realized_win_rate_pp, calibration_gap_pp, breakeven_win_rate_pp, net_edge_pp, CI bounds, verdict, coverage), explains their units and sign conventions, and flags per-venue field availability. An agent has everything needed to call it and to interpret the result correctly.

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 100%, so every parameter is already documented with defaults and accepted values, establishing a baseline of 3. The description reinforces a few semantics (venue:"all" returns one grid per venue, minute=5 is the cheapest row, side_convention reflects the favorite frame), but these largely restate the schema rather than adding new syntax or constraints.

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 + scope: realized win rate by shown price bucket and minute elapsed for short-horizon crypto up/down markets, from a settled-outcomes archive rather than live prices. It explicitly distinguishes itself from the live-price siblings (polymarket_edges, polymarket_arbitrage) and from the archival siblings by naming the exact quantity it computes (calibration gap, net edge).

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?

Clear about the situations it serves ("Answers the one question no venue will" — post-hoc calibration of a shown price) and implicitly excludes live-price use by stating it reads the archive, not live prices. It does not, however, name a specific alternative sibling or state an explicit "use X instead when..." condition, so the routing is contextual rather than prescriptive.

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