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

Annotations already declare readOnlyHint/idempotentHint true, and the description goes far beyond them: it discloses that legs with unknown metric_type/match_subtype are 'NEVER paired,' that compatibility fields can be non-empty even when matched_pairs>0, that a null temporal_alignment means 'it could not be computed... not that the two sides align,' and that Kalshi's fee schedule is not modeled so every spread is gross. It even admits pairing_unverified applies in EITHER mode because matching is keyword/word-overlap based. No statement contradicts the 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?

The content is front-loaded — core purpose in sentence one — and sequenced logically (modes, response shape, safety fields, fees, counters). But it runs to roughly 400 words with real redundancy: compatibility codes are spelled out in the safety-fields section and then partially re-enumerated in the flags[] note, and the temporal_alignment null semantics are warned about twice. The dense parenthetical chains would be easier for an agent to act on if collapsed into structured lists.

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?

Because there is no output schema, the description is the sole source of return-shape information, and it supplies it: leg-by-leg raw probabilities 0-1, signed top_spreads_pp (Kalshi − Polymarket), the compatibility_warning/compatibility_codes safety pair, skipped_unclassified and low_confidence_pairs buckets, the temporal_alignment struct, fees_note, and skipped cross-type/subtype counters. For a dual-venue tool with heavy correctness caveats, nothing needed to invoke it or interpret results is missing.

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%, so the baseline is 3; the description adds mode-level semantics the schema does not: topic shortcuts auto-fetch matching events per venue, explicit tickers override the mapped side, and 'BOTH modes run the identical token-overlap matcher, so the same disclosures apply to both.' This helps an agent decide which parameters to pass together, which is above what the individual property descriptions provide.

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?

The opening sentence states a specific operation and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The framing of the delta as a 'real signal' only when bet shapes are equivalent, plus the standing disclaimer that every spread_pp is 'gross, not a net tradeable edge,' separates this from sibling arbitrage/edge tools like polymarket_arbitrage. Verb, resource, and scope are all explicit.

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 defines two explicit invocation modes — 10 pre-mapped topic shortcuts versus custom kalshi_event_ticker + polymarket_event_slug pairings — so a caller knows which params to supply, and it sets expectations with 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it never names sibling alternatives (e.g., polymarket_arbitrage, polymarket_edges) or states when to choose them instead, leaving cross-tool selection logic implicit.

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