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

No annotations are provided, so the description carries the full burden. It does well: it warns that these are non-atomic, that both exact-size legs must fill, that fees and rounding are estimated, and that results are candidates not guaranteed trades. It also discloses it walks ask depth and emits conditionally. The one gap is that it doesn't mention what happens on execution or whether it submits anything, but the explicit 'never guaranteed trades' disclosure is strong.

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 dense but well-organized: it opens with the core action, proceeds methodically through mechanics (leg sizing, depth walk, fee/rounding treatment), and closes with the critical risk caveat. Every sentence adds content with no filler. It's slightly long, but for a complex scanning tool with an important non-atomicity caveat, the length is warranted.

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 the complexity (a two-venue arbitrage scanner), an output schema present to describe return values, and 2 optional params, the description is thorough. It explains the algorithm, the cost model, the emit condition, the failure mode (non-atomic fills), and the family param workflow. The presence of an output schema relieves the need to document return fields. This is complete for the tool's purpose.

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 0%, so the description must carry parameter meaning. It explains that `family` is 'a family key returned by the tool' — connecting it to a workflow. `max_capital_usd` is not explicitly named but its purpose (capital constraint on candidate generation) is strongly implied by the 'equal whole-contract size' and 'max capital' relation. With 0% schema coverage, this is solid compensation, though one param could be more directly explained.

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 is highly specific: it names the exact scan scope (fingerprint-pinned Polymarket-Kalshi binary pairs), the method (two-leg coverage buying opposite sides at equal whole-contract size), the cost model (taker fees, Kalshi rounding), and the emit condition (all-in cost below settlement payout). This clearly distinguishes it from siblings like list_executable_opportunities, list_sportsbook_surebets, and list_trending_markets, which target different instruments or market types.

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 provides clear context on when to use this tool (scanning for arbitrage candidates across Polymarket-Kalshi pinned pairs) and includes an important caveat distinguishing it from transactional tools: results are unfilled candidates, never guaranteed trades, and cross-venue orders are non-atomic. It doesn't explicitly name alternatives like 'use find_best_price for single best quote' but the scope is specific enough that a capable agent can discriminate.

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