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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses refusal conditions (worst-permissible-fill over pinned tolerance, frozen feed >24h, stale commitment), the 300-second envelope expiry, that the token is never an input, that it never signs or submits, and that it returns the pair unchanged plus a preview. There is no contradiction with annotations; the idempotentHint=false aligns with the fresh-envelope requirement.

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?

Although long, every clause carries operational weight — mechanism, validation rules, failure modes, return shape, follow-up tool, and expiry policy. The structure is logical and front-loaded with the core purpose, with no filler and no redundant restating of schema text.

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 security-sensitive, delegation-aware tool with nested parameters and an output schema, this is a complete operational contract: it covers what is produced, what is refused and why, the 300s validity window, the non-mutating guarantee, and the required next step. Nothing an agent needs to call it correctly is 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?

With 50% schema coverage, the description adds real meaning to the domain-critical parameters: executableEquityId names a registry row and is never the token input, registryCommitment must equal the commitment recomputed over the current record, and amount/slippage feed into the worst-permissible-fill check against the equity's Chainlink mark. accountProfile and client_ref remain undocumented in both schema and description, which prevents a 5.

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 opening sentence names a specific verb ('prepare'), a precise resource (the otto_prepare_swap envelope + prepareInput pair), and a narrow scope (Coinbase B20 tokenized equities on Base bought with USDC via a LI.FI route through the fenced diamond). This unambiguously differentiates it from siblings such as otto_prepare_swap, otto_prepare_bridge, and otto_prepare_perp_order without needing to open their schemas.

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?

The description gives clear operational context: the tool only prepares and previews, the pair must be submitted via otto_submit_under_delegation under the end user's per-swap cap, and a fresh envelope must be requested when one goes stale. It stops short of explicitly stating when NOT to use this versus the generic otto_prepare_swap, though the B20-only scope and 'never an input' phrasing make that exclusion largely implicit.

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