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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description fully complements this by disclosing significant behavioral nuances: gross vs net spreads, unmodeled Kalshi fees, temporal alignment uncertainty, compatibility code semantics, skipped-unclassified legs, and the fact that returned pairs are keyword-matched rather than resolving-source-verified. No annotation contradiction exists.

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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, codes, fees_note, skipped counters) and front-loads the core purpose. Every section carries substantive operational or interpretational guidance. Some redundancy and density makes it less concise than ideal, but the structure compensates for the length.

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 carries the full burden of explaining return semantics, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning vs compatibility_codes, per-entry flags, temporal_alignment fields, skipped counters, and fee limitations. It also covers edge cases such as unknown metric types never being paired and temporal_alignment null meaning uncomputed, not aligned. This is highly complete for a complex analytical 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%, and the schema already documents the topic values and override behavior. The description adds meaningful context beyond the schema, such as the fact that both modes use an identical token-overlap matcher, that explicit params override the topic-mapped side, and that the same disclosures apply in both modes. This is useful but not dramatically beyond what the schema already supplies.

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 precise statement of what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also distinguishes the two modes (topic shortcuts vs explicit event pairings). However, it does not explicitly differentiate this tool from closely related siblings like polymarket_arbitrage, leaving some differentiation to the name and context.

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 clear invocation guidance: use topic shortcuts for pre-mapped macros, or provide explicit ticker/slug pairings for custom comparisons, and notes that both modes run the same matcher. It also warns that most pre-mapped topics return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly state when to prefer this tool over sibling alternatives, but the mode-selection guidance is strong.

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