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, but the description goes far beyond them by disclosing safety fields, compatibility codes, skipped-leg counting, temporal alignment semantics, and the gross-vs-net fee caveat. It explicitly warns that compatibility_warning and compatibility_codes can be non-empty even when matched_pairs>0, and clarifies that `temporal_alignment_unknown` is not the same as confirmed alignment. This is exemplary behavioral disclosure.

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 exceptionally well structured: it opens with a clear one-sentence purpose, then uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, etc.) and upper-case cues to make scanning easy. Every paragraph adds necessary operational or safety information, and the closing warning about pre-mapped ≠ tradeable earns its place as a usage guardrail.

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?

For a tool with no output schema and three optional parameters, the description is remarkably complete: it specifies input modes, response contents, outcome flags, skipped-leg counters, fee caveats, and the meaning of null alignment fields. An agent can determine whether to call the tool, how to call it correctly, and how to interpret potentially ambiguous or incomplete results. No significant operational gap remains.

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 schema descriptions already cover all three parameters at 100%, but the tool description adds substantial meaning: it explains that `topic` is pre-mapped and lists all shortcuts, that explicit ticker/slug override the mapped side, and that both modes run an identical token-overlap matcher. It also contextualizes valid values with examples like `KXFED-26OCT` and `fed-decision-in-june-825`, enriching the schema's static descriptions.

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 states a specific function: computing cross-venue spreads between Kalshi and Polymarket for matching questions. It distinguishes itself from generic siblings by naming its two modes and emphasizing that it identifies when bet shapes are not equivalent. The title and description align tightly, and the tool's unique positioning against alternative spread/arbitrage tools is clear enough to prevent confusion.

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 explicitly explains when to use the pre-mapped `topic` mode versus the explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, and notes that both run the same matcher. It also cautions that most pre-mapped topics currently return compatibility warnings, setting accurate expectations about when the tool is useful. While it does not name sibling alternatives, the guidance is self-contained and actionable.

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