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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond by disclosing exactly how the tool simulates fills: walking the order book ladder, returning fill metrics (top_of_book, vwap_fill_price, slippage_pp), computing basket-level capture_ratio, and explicitly warning about thin_legs and forced_directional_risk. It explains partial-fill risks and why the tool exists, which is meaningful behavioral context beyond 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 information-dense but well-structured, with the core purpose in the first sentence, followed by REQUIRES, then clear SINGLE-MARKET and BASKET sections, and ending with a prescriptive 'USE THIS' rule. Every sentence earns its place; no filler. Despite its length, the complexity of two modes justifies the detail.

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?

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly lists single-market returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket returns (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin legs and partial fills, making it complete for a complex dual-mode tool.

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?

Even though schema coverage is 100%, the description enriches every parameter with mode-specific meaning. For example, size_usd is detailed as 'max spend on buys, target proceeds on sells' in single-market mode, and as 'settlement notional — shares per leg' in basket mode. It also clarifies side defaults (buy_yes or auto-detect from partition sum) and the interpretation of market vs event. This adds real semantic depth beyond the schema.

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, specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and references sibling tools (polymarket_arbitrage, polymarket_edges), so an agent can immediately understand what this tool does and how it differs.

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 explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create unhedged positions), covering the 'when' clearly and implicitly defining the 'when not' (small trades or where full execution is guaranteed).

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