Cross-platform Polymarket vs. Kalshi price divergence

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

This description goes beyond annotations to explain match quality: matches are keyword-overlap similarity, not verified same-event guarantees. That is an important behavioral trait. The per-call price is also disclosed. The annotations only declare readOnly, openWorld, and idempotent hints, so the added caveat is valuable.

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?

Three concise sentences each contribute meaningful content: purpose, key caveat, and pricing. The core capability is front-loaded, and there is no redundant fluff.

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?

The description gives the essential context for using the tool-cluding the cross-platform differentiator and the match-quality limitation. It doesn't state the exact return structure because there is no output schema, but the caveat about verifying matches fills a key safety gap. A minor gap is the lack of explicit mention of what fields will be returned.

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 description coverage is 100%, meaning all three parameters are already fully described in the schema. The description adds a high-leel note about keyword-overlap matching, which anchors results conceptually, but does not enrich the parameter meanings beyond what the schema gives.

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 verb and resource: it finds prediction-market questions priced differently on Polymarket vs. Kalshi. It explicitly calls out the cross-platform divergence signal and differentiates it from any single-platform tool, matching the unique distinguishing angle.

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?

It gives clear context: use this when seeking cross-platform price divergence. The caveat that matches must be sanity-checked before treating as a real arbitrage signal communicates when to be cautious. It does not explicitly name alternatives like search_polymarket_markets or search_kalshi_markets, so it stops short of the full 5.

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