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

This description goes far beyond the readOnly/idempotent annotations by detailing matcher behavior, compatibility codes, skipped pairs, low-confidence inspections, gross-vs-net fee disclosures, and the meaning of null temporal alignment. It discloses both what the tool does and where its output may be misleading. 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 well-organized with labeled sections for modes, response, safety fields, and codes. It is front-loaded with the core purpose and then layers necessary operational detail. Some redundancy exists around temporal_alignment_unknown and null semantics, but given the richness of the tool's output and the absence of an output schema, the length is largely justified.

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 the response shape and safety semantics, and it succeeds. It covers matched spreads, per-entry flags, compatibility warnings, skipped categories, fee modeling limitations, and temporal alignment behavior. An agent has enough context to interpret results correctly and avoid treating pre-mapped spreads as automatically tradeable.

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 meaningful semantics by explaining the two modes, that explicit ticker/slug overrides the topic-mapped side, and that both modes run the same matcher. It enriches parameter understanding without needing to restate schema text.

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 clearly identifies the tool's function: computing cross-venue spreads between Kalshi and Polymarket for matching resolving questions. It names the specific resource and explains the two input modes. However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, so distinguishing from alternatives is left somewhat implicit.

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 usage context: use topic shortcuts for pre-mapped macro events, or custom ticker/slug pairs for explicit pairings. It also warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It stops short of naming specific sibling alternatives or explicit when-not-to-use conditions, so it misses the top score.

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