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

Annotations only note non-readOnly, openWorld, non-idempotent, non-destructive. The description goes beyond by disclosing that the two legs are NOT atomic, that each is a separate transaction/signature, and the critical sequencing requirements. It also explains the risk of proceeding if leg A fails, which is crucial behavioral context.

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 a single dense paragraph with no bullets, but it's reasonably concise and information-dense. It front-loads the core message (builds both legs) and includes important warnings. However, it could be better structured with visual breaks for the execution sequencing guidance, but it's still efficient.

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 (nested objects, multiple legs, non-atomic behavior) and lack of output schema, the description covers key aspects: what it does, the non-atomicity, and execution order. It lacks details on error handling and edge cases, but those might be overkill. The presence of sibling tools like swap_build lets an agent infer comparison. Overall, it's well-covered for an agent to call correctly.

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 60%, with legA and legB having detailed inner property descriptions (amount vs amountRaw, receiver conditions, Solana nuances). The description adds a global maxSlippageBps applying to both legs and the alias semantics for legA/legB, but these are mostly covered by schema descriptions. The description doesn't add significant new parameter meaning beyond what's in the schema, so a 3 is appropriate.

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 it builds plans for both legs of a Double Out or Double In swap, wrapping two swap_build calls, and explicitly differentiates it from ordinary swap_build by noting the convenience wrapper and the separate legs. It also specifies the return shape ({ legA, legB }), which isn't in 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?

Provides explicit instructions: execute leg A fully and confirm it landed before starting leg B, and do NOT execute leg B if leg A fails. It also references sibling swap_build as the underlying mechanism, distinguishing this tool. No explicit alternatives are given, but the context makes it clear when to use this vs a single swap.

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