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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, and the description does not contradict these. It adds meaningful behavioral context: it 'walks the ladder', returns verdicts like clean|degraded|cannot_fill, and exposes failure modes like thin_legs and forced_directional_risk. The caution that 'theoretical overround on thin books is not capturable' and that partial basket fills convert an arb into an unhedged directional position provides significant insight beyond the annotations.

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 justifiably so given two distinct modes and many return fields. It is well-structured with clearly demarcated sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that aid scannability. Every sentence provides necessary information—there is no filler or repetition.

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 takes full responsibility for explaining return values. It enumerates all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, etc.). It also covers edge cases like forced_directional_risk and explicitly warns about the danger of partial basket fills, making the tool's behavior fully comprehensible.

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. The description elevates this by explaining size_usd differently for single-market ('max spend on buys, target proceeds on sells') and basket modes ('settlement notional S, shares per leg, each share pays $1'). It also clarifies the default behavior for side in basket mode ('auto — sell if partition sum > 1, buy if < 1'), which adds semantic richness beyond the schema 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 opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly separates single-market and basket modes, and the specific mention of return values like slippage_pp and capture_ratio leaves no ambiguity about its function. It also differentiates itself from siblings by explicitly positioning itself as a pre-trade risk check for polymarket_arbitrage and polymarket_edges.

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 gives explicit usage direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This directly names alternative sibling tools and states a threshold, making it clear when this tool is required and when it is likely unnecessary. The warning about partial fills becoming unhedged positions also reinforces the practical context.

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