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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), it discloses the key behavioral contract: RAVN never takes custody, and the agent either signs/broadcasts, signs for RAVN to submit, or sends an asset to an address. It also names the three possible return shapes, which is especially valuable with no output schema.

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: the first anchors the core purpose and the second packs in return shapes and the custody warning. It is appropriately sized for a tool with this level of behavioral 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?

It covers the three execution outputs and the custody model, which is essential for correct invocation. However, it omits guidance on the optional parameters and the conditions that select each executionType, leaving a gap for non-trivial calls. Since there is no output schema, those details would need to come from the description.

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 only 25% because only quoteToken is described, and the description mostly restates that it comes from ravn_quote. apiKey, refundAddress, and destinationAddress are not explained or mapped to the executionType shapes, so the agent must guess their roles.

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 names a specific verb ('execute'), a specific resource ('swap quote'), and the source of the input ('quoteToken from ravn_quote'). It also lists the three executionType shapes, making it easy to distinguish this execution tool from the quoting and status sibling tools.

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 clearly states the input relationship: a quoteToken from ravn_quote is turned into an execution payload, telling the agent this runs after quoting. It does not explicitly enumerate when to prefer ravn_btc_prepare_send or other siblings, so it lacks a full when-not-to-use statement.

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