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

Annotations already mark the tool as read-only and non-destructive. The description adds valuable behavioral context: it explains the meaning of 'verdict' (clean|degraded|cannot_fill), the risk of partial basket fills converting arb into directional exposure, and the semantic difference of size_usd between single-market and basket modes. No contradiction with 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 very long but every sentence packs essential information for a complex tool. It is front-loaded with a clear summary, then explains modes and outputs. The single dense paragraph is less readable than structured sections, but no sentence is wasted.

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 tool's complexity (two distinct modes, no output schema), the description is remarkably complete. It enumerates the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum vs realizable_sum, capture_ratio, thin_legs, forced_directional_risk, etc.) and provides usage context tied to real losses in arb-bot P&L. The absense of an output schema is compensated.

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?

While the schema covers all parameters at 100%, the description adds significant semantic layers: it clarifies that 'market' and 'event' are mutually exclusive modes, explains side defaults and behavior in each mode, defines size_usd as 'max spend on buys, target proceeds on sells' for single-market and as settlement notional for basket mode, and notes the clamp range of 10–1,000,000. This goes far 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 specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning this tool as a pre-trade risk check, not an edge finder or arb detector.

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 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 why (theoretical edge not capturable on thin books, partial fills create unhedged directional risk), which gives clear when-to-use and alternatives.

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