swap_status

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

With no annotations, the description carries the full behavioral burden and adds meaningful context: it lists the returned fields and explains that paper fills carry a paper: reference rather than a real transaction hash. It does not cover authentication needs, error behavior, rate limits, or whether the fill may be pending.

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 two short sentences with no wasted words, and it front-loads the core action before adding the important paper-fill nuance.

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?

There is no output schema, so listing returned fields is useful and the paper-fill note is valuable. However, the description omits where trade_id comes from, how pending or failed fills are represented, and any permission or authentication context, leaving meaningful gaps.

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 description coverage is 0%, so the description must compensate for the single undocumented trade_id parameter. It only repeats 'by trade_id' without explaining format, source, or where the identifier originates, adding little beyond the parameter name itself.

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 states a specific verb and resource: 'Check a fill by trade_id,' and enumerates the returned fields (status, amounts, fee, venue, reference). It clearly distinguishes the tool from generic wallet or trading tools, but it does not name or contrast with the closest siblings such as swap_quote or swap_execute.

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?

Usage is implied by 'Check a fill by trade_id,' suggesting this is used after a swap execution to inspect a fill. However, the description gives no explicit when-to-use guidance, no when-not-to-use conditions, and no named alternatives such as swap_execute or claim_status.

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