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

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by explaining the compatibility_warning and compatibility_codes[] fields, the rule that legs with unknown metric_type or match_subtype are never paired, skipped_unclassified, low_confidence_pairs[], temporal_alignment, and skipped_cross_type/subtype counters. It also explicitly warns that compatibility fields can be non-empty even when matched_pairs>0, which an agent must know to interpret results correctly. No contradiction with the annotations 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 deliberately scaffolded with labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, and it front-loads the purpose before diving into edge-case flags. Every sentence carries operational weight, though a few caveats are repeated and the text sits at the upper edge of warranted length. It is well-structured but not maximally 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?

With no output schema, the description fully carries the burden of explaining return semantics: it covers leg-by-leg prices, top_spreads_pp, compatibility codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and dropped-comparison counters. It also provides realistic expectation-setting by noting that most pre-mapped topics return warnings and are not necessarily tradeable. Nothing important appears missing for an agent to decide whether and how to call the 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?

The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds useful context that topic values are 'pre-mapped macro shortcuts' that auto-fetch the matching event and that explicit parameters override the topic-mapped side, but this does not substantially change the meaning of the schema. The bulk of the added semantic value is about output/response interpretation rather than the parameters themselves.

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?

Opens with a concrete definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately clarifies the tool's scope and then enumerates two invocation modes, 'topic' shortcuts and explicit ticker/slug pairing, which makes the intended operation unmistakable. The cross-venue Kalshi/Polymarket focus also sets it apart from the other polymarket_* siblings.

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 two modes are explicitly contrasted: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility warnings, which is important calibration. However, it never names a sibling alternative such as polymarket_arbitrage or states when this tool should not be used at all.

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