swap_execute

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: paper vs. live behavior, server-side approval enforcement, auto-approve conditions, re-inspection at execution time, once-only fill, atomicity, kill-switch and expiry failure modes, and the paper: return reference. This is far beyond what structured fields provide.

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?

Dense but front-loaded — the paper/live distinction and approval mechanics come first, with edge cases after. Every sentence carries information; it is long but justified by the tool's conditional complexity, with only minor density cost.

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?

No output schema exists, but the description discloses the return form ('paper:' reference, never confused with real tx hashes). For a mutation tool with no annotations, all gating, failure, and safety conditions an agent needs are present.

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 67%; the description elaborates user_approved semantics well beyond the schema (explicit yes vs. auto-approve path, red flags) and reinforces quote_id freshness/expiry. trader_id remains undocumented in both places, which is the only real gap.

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 ('Execute a swap_quote') and immediately scopes it as a paper fill vs. the unwired live path. It is clearly distinguishable from the sibling swap_quote, which produces the quote this tool consumes.

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 when-to-use and when-not: paper mode fills, live mode refuses, approval via user_approved=true or auto-approve threshold, red flags need explicit yes, honeypots never fill. It names the gating conditions and points to related tools (signer_status, set_auto_approve) for the live path.

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