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

Annotations already declare a safe read-only, idempotent operation, yet the description still adds substantial operational context: quotes cached up to 60 seconds so cross-venue gaps carry skew, the not_listed vs unavailable distinction, the bid_only/one-sided-book behavior with null mid, and the fact that top-of-book size is missing from Kalshi's payload. This is behavior an agent could not infer from annotations.

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 core purpose and the key warning (THE VENUES ARE NOT ONE CONTRACT), and nearly every sentence carries real information. It is dense to the point of being a wall of text with no paragraph breaks, so structure could be improved, but there is little filler to cut.

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?

With no output schema, the description fully specifies return shape: per-venue fields, the pairs[] structure with equivalence states, mid_diff_pp sign convention, read_as, and the two status objects. Settlement-feed differences and the 1.2–1.8% divergence figure give an agent everything needed to interpret results 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 the baseline is 3, and the description still adds value: it restates the asset enum, explains the window options including ISO-start form, and warns that an unaligned timestamp is refused rather than rounded. Coverage differences per venue are also noted, which the schema mentions but the description reinforces usefully.

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?

Opens with a precise verb+resource: the same 15-minute up/down window priced side by side on polymarket.com, Polymarket US and Kalshi, plus whether each pair is actually the same contract. That scope, especially the cross-venue equivalence framing, clearly separates it from siblings like polymarket_kalshi_spread and resolution_diff.

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?

Names the accepted asset/window inputs, states the default window, and explicitly restricts scope ('Only the 15m horizon is offered'). It also routes the agent elsewhere for a different need ('For the settled history… call updown_divergence_rate'), which is exactly the when/when-not/alternative pattern.

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