recover_sponsor_nonce

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

With no annotations, the description carries the full burden and does so: it discloses that rbf rebroadcasts with a higher fee, that fill-gaps submits placeholder transactions, the default of 'both', the wallet-unlocked prerequisite, the counter re-seeding behavior, and that 404/501 is converted into a clear message instead of an error. These are exactly the mutation and failure traits an agent needs before invoking.

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 purpose and prerequisite, then a clean mode-by-mode breakdown — the structure is easy to scan. The closing tip pointing at earning_opportunities is unrelated filler that does not earn its place, and the mode list is somewhat verbose.

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 zero-required-parameter mutation tool with no annotations and no output schema, the description covers triggers, per-mode behavior, prerequisites, defaults, and degradation when the relay does not support the endpoints. What it does not describe is what a successful recovery returns (txids bumped, gaps filled), leaving the agent to infer the outcome shape.

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, but the description adds meaning the enum names alone do not carry — what 'rbf' and 'fill-gaps' actually do on-chain, and that omitting txids/nonces widens the blast radius to all stuck transactions or all detected gaps. It adds real semantics rather than restating the schema, though it does not explain format constraints on the txid/nonce arrays.

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 ('automated recovery of stuck sponsor transactions via the relay API, or resync the local nonce counter') and immediately contrasts itself with check_relay_health, which is named as the diagnostic predecessor. An agent can tell it apart from nonce_fill_gap, nonce_heal, and check_relay_health from the description alone.

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 prescribes the workflow ('Run check_relay_health first to identify stuck txids and missing nonces, then use this tool') and gives a concrete condition for each mode, including the specific situations that warrant resync-local-nonce (server restart, tx sent outside the MCP server, confirmed-but-locally-stuck counter). It also states the fallback when the relay lacks support.

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