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

With no annotations, the description carries the transparency burden, and it discloses the KYA gate as fail-closed, optional agent credentials, the returned executionId/approve_execute action, and the no-fill behavior. It does not cover error conditions, idempotency, or how mode values like live/mainnet affect the quote, which keeps it from a 5.

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?

Four compact, information-dense sentences front-load the pipeline and example, then cover output, auth, and the crucial no-fill caveat. There is no filler or repetition of schema-only facts.

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?

The description gives the core interaction loop and return contract, which is sufficient for a basic call. But with no annotations and no output schema, it should clarify mode behavior, portal/userId semantics, and a fuller description of the returned actions/errors; the 'testnet quote' wording is too narrow relative to the mode enum.

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 only 33%, so the description must add meaning; it does so for the required message with a concrete natural-language example and for agentId/agentCredential by explaining the KYA gate. However, mode, portal, and userId are left undefined—mode is especially important given the live/mainnet/testnet enum and the description's 'testnet quote' phrasing.

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 defines a concrete function: a natural-language copilot turn that converts a message into an intent, plan, and quote, returning approve_execute actions with an executionId. The worked example ('Swap 10 USDC to SUI on sui with 50 bps slip') pins down the input style, and the explicit 'Does NOT fill until ava_approve_execute' differentiates it from the execution sibling.

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?

It gives clear usage context: send a natural-language request to get a plan/quote and actions, and it explicitly establishes the follow-up tool by stating execution does not happen until ava_approve_execute. It does not enumerate alternatives such as ava_plan_workflow or ava_preview_tx, so it stops short of full when/when-not routing.

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