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

Annotations already declare a safe read-only, idempotent, open-world operation, so the bar is low — but the description goes well beyond: it discloses that fees are always non-zero and computed per-market, that basket figures are net of every leg's fee with gross counterparts retained, the verdict enum, and the failure mode (partial fills become unhedged directional exposure). That is substantively new behavioral context, and nothing contradicts the 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?

It is front-loaded well (purpose, then mode requirements, then return shape, then usage rule), but it is very dense — the 'fleet #3446 / r/PredictionsMarkets' anecdote is narrative justification rather than agent-facing guidance, and the exhaustive enumeration of return fields duplicates the output schema. Both cost readability without changing how an agent calls the 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?

For a tool with four parameters, an output schema, and rich annotations, everything an agent needs to call it correctly is present: mode requirement, defaults, side enums, size semantics per mode, fee treatment, and the pre-trade decision rule. The one acknowledged limitation (adverse selection on resting orders) is stated explicitly rather than left implicit.

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?

Schema coverage is 100%, so 3 is the floor — but the description reinterprets `size_usd` meaningfully per mode (max spend on buys vs target proceeds on sells vs settlement notional/shares-per-leg in basket mode) and explains default side resolution in basket mode. It adds real semantic value beyond the schema text rather than restating it.

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?

States a specific verb+resource ('realizable-vs-theoretical edge check against live CLOB order-book depth') and adds the distinguishing twist — Polymarket's non-zero taker fee is folded in. It also names the sibling tools it supersedes in this situation (polymarket_arbitrage, polymarket_edges), so an agent can route without opening any schema.

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?

Gives an explicit activation rule: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also states the mode-selection requirement (exactly one of `market` or `event`) and discloses a known non-coverage ('adverse selection ... is still not modeled'), which is a well-scoped when-not.

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