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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes far beyond this by detailing return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), mode-specific behavior ('walks the ladder', 'returns per-leg fill detail'), and failure modes ('thin_legs[]', 'forced_directional_risk'). This is rich behavioral context without any contradiction.

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 lengthy, but every sentence is informative and the structure uses clear section markers (SINGLE-MARKET, BASKET, USE THIS) to organize information. It front-loads the core purpose and uses all-caps keywords for key phases. A slightly tighter edit could shorten it, but the density justifies its length for a complex two-mode tool.

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 must explain return values, and it does so exhaustively for both modes. It covers all four parameters, defaults, clamping, mode selection, outputs, and edge-case risks (partial fills, thin books, forced directional risk). Combined with the rich annotations, this description is fully capable of guiding correct invocation.

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 the schema covers all parameters, the description adds crucial mode-dependent semantics: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional S (shares per leg)' in basket mode. Side defaults and meanings are also clarified (auto default from partition sum). This significantly enhances what the schema alone provides.

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?

Description opens with a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket), and the verb 'check' plus resource 'order-book depth' makes the tool's function unambiguous. It also separates it from siblings like 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?

Provides explicit usage instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also gives required parameters (REQUIRES one of market or event) and explains when each mode is appropriate, plus the risk rationale for using it.

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