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

The description discloses far beyond annotations: it explains that the tool walks the order-book ladder, returns a verdict (clean/degraded/cannot_fill), handles partial fills, and identifies forced directional risk. It also notes the basket-mode behavior of summing theoretical vs realizable values. These add rich behavioral context to the readOnly/openWorld/idempotent hints, without contradicting them.

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 meticulously structured: a one-line summary, then REQUIRES/SINGLE-MARKET/BASKET sections, and a USE THIS closing. Every sentence carries task-critical detail—mode distinctions, output fields, risk warnings. No filler; the length is justified by the tool's inherent 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?

Given two distinct operating modes and a rich set of return values (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.), the description comprehensively covers both modes, their inputs, outputs, and the risk consequences of partial fills. With no output schema, the description fully enumerates return fields, and it ties the tool into the broader arb trading workflow. Absolutely complete for its context.

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%, but the description adds substantial meaning: it defines the REQUIRES relationship between market and event, explains side defaults for both modes, clarifies size_usd as 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional S' in basket mode, and even mentions clamping (10–1,000,000). This goes well beyond the schema's bare parameter lists.

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 clear, specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by focusing on fill risk/execution viability, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to frame its role. The two modes (single-market vs basket) are clearly defined.

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?

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two distinct usage modes and interprets size_usd differently for each, giving clear context for selection. No alternatives are needed because it names the specific sibling signals it validates.

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