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

Annotations already mark this as readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond that: response structure, safety fields, compatibility code semantics, fee disclosure, skipped-leg counting, and temporal alignment pitfalls. It explicitly discloses that the tool does not model Kalshi's fee schedule and that spreads are gross, not net — exactly the behavioral context 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?

Although long, the description is well organized (purpose, modes, response, safety, fees, counters) and every section carries operational value. The core purpose is front-loaded, and the caveats are placed where they matter. There is no filler or repetition; the length is justified by the tool's complexity.

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 documents the returned structure (leg prices, spread[].top_spreads_pp, compatibility fields, skipped counters) and failure/safety semantics. It gives an agent everything needed to invoke the tool correctly and interpret results, without requiring an external schema.

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 already describes each parameter, but the description enriches them significantly: it enumerates all 10 topic values, explains that explicit ticker/slug override the mapped side, and clarifies that both modes run the same matcher. This gives the agent the full semantic range and override behavior beyond the schema's terse examples.

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?

States a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling polymarket tools by framing the output as a matched spread with safety disclosures, and explicitly differentiates it from a tradeable arbitrage ('not a net tradeable edge'). The title and description align closely, and the description adds scope beyond the title.

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?

Describes two modes — topic shortcuts vs explicit ticker/slug pairing — and when each is appropriate. Warns that 'pre-mapped ≠ tradeable' and that most topics return a compatibility_warning, setting clear expectations. It doesn't explicitly name sibling alternatives like polymarket_arbitrage or polymarket_edges for comparison, so it provides clear context but lacks explicit exclusionary guidance.

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