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

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false already present, the description still adds substantial behavioral context: the two modes, the compatibility_warning/compatibility_codes safety fields, the rule that legs with unknown metric_type/match_subtype are never paired, how temporal_alignment is reported, and the caveat that real cross-venue spreads are rarer than the shortcut list suggests. No annotation contradiction exists, and the description is exceptionally candid about limitations.

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 long, but it is structured with clear labels like 'TWO MODES', 'RESPONSE', 'SAFETY FIELDS', and it front-loads the core definition before diving into safety details. Nearly every sentence carries meaningful information for a complex tool with no output schema. It is dense rather than bloated, though it could be tightened without losing value.

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 there is no output schema, the description does a strong job of explaining return concepts: leg-by-leg prices, matched spreads in percentage points, compatibility_warning/codes, temporal_alignment, skipped counters, and low-confidence pairs. The main gap is that it never states what happens when no parameters are supplied at all, even though all parameters are optional in the schema; an agent needs to know that topic or explicit identifiers are effectively required.

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 goes beyond the schema by explaining that `topic` auto-fetches the matching event on each venue, that the explicit ticker/slug override the topic-mapped side, and how the two modes relate to each other. It also provides the concrete shortcut enum values in the schema itself, so this added behavioral meaning lifts it above baseline.

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 description opens with a specific verb-resource pair: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies what the tool computes and the two modes of operation. It does not explicitly name sibling tools like polymarket_arbitrage or polymarket_edges to draw a contrast, so it falls just short of full sibling differentiation.

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 clearly explains two usage modes: pre-mapped `topic` shortcuts and explicit `kalshi_event_ticker` / `polymarket_event_slug` pairings. It also gives important practical guidance such as 'pre-mapped ≠ tradeable' and warns that most pre-mapped topics return compatibility warnings today. However, it does not explicitly tell an agent when to choose this tool over a sibling like polymarket_arbitrage.

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