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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive, and the description adds substantial behavioral context beyond that: response shape, top_spreads_pp semantics, compatibility_warning and compatibility_codes, skipped_unclassified and low_confidence_pairs, and the explicit warning that spread_pp is gross because Kalshi fees are not modeled. It also clarifies the tricky temporal_alignment null semantics, which is exactly the kind of nuance an agent needs.

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 almost every sentence carries operational weight: modes, response fields, safety codes, skipped-leg counters, and fee caveats. It is front-loaded with the core definition and then layers detail logically, though it is dense enough that an agent must parse carefully and a couple of warnings are repeated for emphasis.

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 carries the full burden of explaining return values, and it delivers: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, and temporal_alignment semantics. It also covers edge cases like unknown metric_type/match_subtype, cross-type and cross-subtype skipping, and the fees_note standing disclosure, making it complete for a complex cross-venue comparison tool.

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, but the description adds real meaning beyond the parameter descriptions by explaining what topic actually does (10 pre-mapped shortcuts that auto-fetch matching events), how explicit ticker/slug overrides interact with the topic mode, and that both modes use the identical token-overlap matcher. This helps an agent choose parameter combinations confidently.

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—computing the cross-venue spread between Kalshi and Polymarket for the same resolving question—and clearly frames the tool's unique value. It distinguishes itself from sibling tools by emphasizing Kalshi/Polymarket pairings and by calling out when bet shapes are equivalent versus when they are not, so an agent can tell it apart from descriptors like polymarket_arbitrage.

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 gives explicit usage context: two modes (topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug), when each applies, and that both run the same matcher. It also warns that pre-mapped topics are often not tradeable and that real cross-venue spreads are rarer than the shortcut list suggests, giving the agent strong expectations about when the result is meaningful. It does not name or contrast sibling tools explicitly, so it falls just short of a 5.

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