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

Annotations already define readOnlyHint=true and destructiveHint=false, and the description adds substantial context beyond those: it walks the ladder, returns specific metrics, and discloses failure modes like forced directional risk and partial baskets converting arbs into unhedged positions. 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 long but appropriately so for a tool with two modes, four parameters, and complex return logic. It is front-loaded with the core purpose, uses clear SINGLE-MARKET/BASKET sections, and every sentence conveys necessary information. No fluff.

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 and lack of output schema, the description fully lists return values for both modes, explains edge cases (thin books, forced directional risk), and gives sizing context. It is complete enough for an agent to invoke correctly and interpret results.

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?

Although the schema has 100% coverage, the description adds critical semantics that the schema doesn't convey: how size_usd is interpreted differently in single-market (spend vs proceeds) vs basket (settlement notional per share), and how side defaults differ between modes. This meaningfully extends 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 clearly states the tool's purpose with a specific verb and resource: checking realizable-vs-theoretical edge against live CLOB order-book depth. It distinguishes between single-market and basket modes, and explicitly positions itself as a pre-trade risk check for polymarket_arbitrage and polymarket_edges trades, distinguishing it from sibling tools.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the trade-off between modes and why partial fills are dangerous, giving actionable context for tool selection.

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