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

Even though annotations already indicate read-only and idempotent behavior, the description adds substantial depth: it explains that the tool 'walks the ladder,' returns specific metrics like vwap_fill_price and slippage_pp, and warns that partial basket fills 'convert an arb into an unhedged directional position.' These details go far beyond the annotations and clarify the tool's operational and risk behavior.

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 information-dense; each sentence earns its place by covering modes, parameters, outputs, or risk rationale. However, the single-paragraph structure is less scannable than it could be; dividing into bullet points or sub-sections would improve readability without losing content.

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 on the full responsibility of explaining return values, which it does thoroughly for both modes (listing top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-specific fields). It also covers the risk context and usage thresholds, making it complete for a complex 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?

While the schema covers 100% of parameters, the description enriches each one: it explains side values in both modes, notes the default for side in basket mode ('auto from partition sum'), and clarifies size_usd semantics ('max spend on buys, target proceeds on sells' vs 'settlement notional'). This is more nuanced than the schema's 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly states what the tool does with a specific verb and resource. It distinguishes itself from siblings by framing the tool as a pre-trade validation step and explicitly naming polymarket_arbitrage and polymarket_edges as tools it should be used before. The two modes (single-market and basket) are also well described.

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?

It explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' giving a clear trigger. It also explains the rationale ('theoretical overround on thin books is not capturable') and describes when basket mode is appropriate, making the usage context unmistakable.

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