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

With readOnly/openWorld/idempotent annotations already present, the description goes far beyond them: it discloses that Kalshi fees are not modeled, that compatibility_codes can be non-empty even with matches, that unknown legs are never paired, that temporal_alignment null means unknown rather than aligned, and that pairing is keyword-based not source-verified. 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 nearly every sentence carries operational or safety-relevant information that would not appear elsewhere. It is front-loaded with the core purpose and mode distinction. Some redundancy exists around compatibility_codes and skipped counters, which could be tightened, but the dense structure is mostly 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?

Given three optional parameters and no output schema, the description bears the full burden of explaining response semantics, safety fields, failure modes, fee caveats, and pair-quality indicators. It covers all of these in enough detail for an agent to select the right mode and interpret results correctly. Nothing critical is missing.

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%, so the baseline is 3, but the description adds real meaning: it enumerates the ten pre-mapped topic values, explains that explicit parameters override the topic-mapped side, and clarifies that both modes run the identical matcher. This goes beyond the schema's brief property 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?

States a specific function: compute cross-venue spread between Kalshi and Polymarket for the same resolving question. It also names the two modes (topic shortcuts vs explicit ticker/slug) and clearly distinguishes this from same-venue or arbitrage tools by emphasizing the participant-pool difference and matching logic.

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?

Gives concrete when-to-use guidance: use pre-mapped topics for fast lookups, use explicit ticker/slug for custom pairings, and warns that pre-mapped topics often return warnings and are not automatically tradeable. It does not explicitly name sibling tools or say 'use this instead of X', but the mode-selection guidance is strong enough to route an agent.

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