burn_token

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

With no annotations, the description carries the full disclosure load and does so: sponsor pays for the transaction, the call blocks until settlement (~1 minute), the response shape is given, failure delivers a `next` hint, and the dedup/resume behavior on retry is spelled out. It also warns that a deliberate second call needs a fresh idempotencyKey.

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 action and effect, then constraints, then return/retry semantics in priority order. Dense but nearly every sentence does work; the retry/idempotency portion is slightly verbose relative to the rest.

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 5-parameter mutation with no annotations and no output schema, the description supplies timing, failure handling, retry behavior, and return shape. Only minor gaps remain, such as why both txHash and transactionHash appear or how long dedup state persists.

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%, so the baseline is 3; the description goes beyond it by explaining the composite token identity (name + issuer) and what omitting issuerKey implies ('the token is one this wallet minted'). It also explains the idempotencyKey's dual role (resume vs. genuinely new call). It stops short of anything on amount units beyond what the schema says.

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 opens with a specific verb+resource: 'Burn an amount of a factory token this wallet holds', plus an effect clause ('the coins leave circulation and the factory's supply ledger drops'). That effect statement clearly separates it from mint_token and send_token among the siblings.

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 concrete preconditions (factory must be on the sponsor's contract list and have burn on its circuit list) and states the issuerKey default behavior. It never names a sibling alternative or an explicit when-not-to-use, which keeps it below a 5.

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