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

Even with readOnlyHint/idempotentHint/destructiveHint already declaring this a safe read operation, the description adds substantial behavioral context: the compatibility_warning/compatibility_codes mechanism and the explicit instruction to 'read them even when matched_pairs>0,' the machine-readable code list, and — most valuably — the clarification that 'temporal_alignment_unknown... is NOT the same as confirmed-aligned' and that 'null means it could not be computed, not that the two sides align.' The fees_note (gross spread, not net tradeable edge) and the skipped_unclassified counters further disclose interpretation pitfalls. No contradiction with 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 description is exceptionally dense with useful information and every sentence has earned its place — there is no filler and the purpose is front-loaded in sentence one. However, it is a single unbroken wall of text (~600+ words) with no paragraph breaks, bullets, or headers separating modes, safety fields, codes, temporal logic, fees, and skipped counters. For a tool this complex, the lack of any structural scaffolding materially hurts scannability, so despite zero padding it reads as under-structured rather than concise.

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?

Given the tool's real complexity — 3 params in 2 modes, an extensive compatibility-code taxonomy, temporal-alignment semantics, fee caveats, and skipped-pair counters — and that there is NO output schema, this description carries the full burden of explaining return values and edge cases. It covers the response shape (leg-by-leg prices, top_spreads_pp, Kalshi − Polymarket sign convention), the per-entry flags[], the never-paired 'unknown' leg rule, the temporal_alignment object, and the gross-vs-net fee limitation. Nothing an agent needs to 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 meaning beyond the schema by explaining the mode interaction: that `kalshi_event_ticker` and `polymarket_event_slug` 'Override the topic-mapped side' — an override relationship not stated in the isolated schema parameter descriptions. It also describes the topic→event auto-fetch behavior. The topic enum values are duplicated from the schema rather than newly explained, which keeps this from a 5, but the override semantics and mode-combination logic are genuinely additive.

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 first sentence states the exact resource and operation: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further quantifies the signal (2-25pp apart) and names the scope boundary ('for the same resolving question'). The cross-venue, two-specific-venues nature clearly separates it from the single-venue siblings like polymarket_arbitrage, polymarket_edges, and polymarket_edge_tracker, even without naming them. Verb, resource, and scope are all unambiguous.

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 explicitly documents TWO MODES and how to select between them: `topic` shortcuts auto-fetch mapped events, while explicit `kalshi_event_ticker` + `polymarket_event_slug` allow custom pairings, noting both run the identical matcher. It also sets expectations for reliability: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' The only gap is that it never names sibling alternatives (e.g., polymarket_arbitrage) or gives explicit when-to-use-this-vs-that exclusion rules, so routing is by content rather than by explicit comparison.

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