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

Beyond the readOnlyHint annotation, the description discloses important behavior: status is authoritative where the venue exposes it, and some venues report 'unknown' honestly rather than guessing. This helps an agent correctly interpret ambiguous results and avoids false assumptions about failures.

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 sentences with no filler. It front-loads the verb and resource, then adds essential venue-specific context and an important caveat. Every sentence earns its place.

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 covers the core inputs, the source of the ref, and how to interpret venue-reported statuses, including the 'unknown' case. It doesn't enumerate possible status values or polling behavior, but it is sufficient for an agent to invoke the tool correctly in the described workflow.

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 partially compensates by explaining the semantics of 'ref' in detail and indicating quoteToken is part of the lookup key. However, quoteToken is not fully defined and apiKey is not mentioned at all, leaving some parameter meaning unresolved.

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 the tool's function: polling swap status using quoteToken and the ref from ravn_execute. It also disambiguates the ref by venue type, making the tool's purpose specific and distinguishable from siblings like ravn_execute or ravn_quote.

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?

The description gives clear usage context: this tool is used after ravn_execute, using the returned ref and the relevant quoteToken. It does not explicitly state when not to use it or name alternative tools, but the dependency on ravn_execute's output makes the intended workflow clear.

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