Transfer status

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds the full lifecycle state machine, tells the agent to poll again after a few seconds for submitting/sent, and explains what expired means and what to do about it. It also documents error behavior for unknown, malformed, or 30-day-old ids returning 'Transfer not found', which nothing in the structured fields conveys.

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?

Front-loaded with the core operation, then states, then usage routing, then constraints — a sensible order with no filler sentences. The state enumeration is dense but each state carries an actionable parenthetical, so it earns its space; only the explicit returns shape slightly duplicates what a caller would learn from the response.

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 single-parameter read tool with no output schema, the description supplies everything an agent needs: scope, state semantics with polling advice, sibling routing, mutation limits, the top-level response shape, and the exact error condition. There is no ambiguity left that would cause an incorrect call.

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 100% and the transferId property already explains the 24-hex-character format and that it is not a transaction hash, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the same id space covers both quotes and transfers and by documenting the failure mode ('Transfer not found') for an id that is well-formed but unknown or older than 30 days.

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 and resource — returns the current state of a quote or transfer by id — and enumerates exactly what comes back (fees, transaction hash, explorer link once sent). An agent can distinguish it from quote_send, quote_swap, and submit_signatures purely from the description.

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?

Explicitly says to use it to follow up after submit_signatures or to see whether a quote is still open, and names the alternatives for starting a flow (quote_send or quote_swap). It also closes off misuse by stating it cannot start, change, or cancel anything, so when-not-to-use is covered alongside when-to-use.

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