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

With no annotations, the description carries the full burden and does so richly: cost model (free, never x402-gated), error codes and their triggers (404 swap_not_found, 400 invalid_request), rate limits (one read per quote every 5s, 132 per quote then permanent 429), and finality semantics ('the first result from a mined swap is final'). This is far beyond anything a schema or annotation would convey.

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?

Bold headers (Cost, Key inputs, Returns, Limits, Next) front-load the critical routing info, and most sentences are information-dense. It is long and occasionally dense enough that a few clauses could be tightened, but the detail is largely warranted for the tool's complexity.

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 2-param tool with no annotations, no output schema, and no param descriptions, the description supplies everything needed: return-value semantics (pass/fail/pending, delivered, block, status, reason), failure reasons, rate limits, and post-result actions. Nothing an agent needs to call or interpret it correctly appears missing.

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 0%, so the description must compensate, and it does: quoteId is identified as the one passed to POST /trade/v1/swap, and txHashes as the 1-to-4 transactions sent (the swap plus any approvals). It also explains the validation scope tied to each parameter, adding real meaning the bare schema cannot.

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?

Starts with a specific verb+resource statement: it tells you whether the transactions that POST /trade/v1/swap returned did what the quote promised, and clarifies 'It only reads the chain.' This cleanly separates it from the mutating siblings (tradeSwap, tradeSwapTx), so an agent can distinguish it without opening the 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?

Explicit about when to call it ('once you've sent them'), when it does not apply (smart-contract wallets sending from an executor/bundler instead get 400 invalid_request, with a redirect to checking the transaction's own receipt), and what to do next based on result (requote/stop/pending). Alternatives and exclusions are named, not implied.

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