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

Annotations already flag destructiveHint=true and non-idempotent, and the description earns credit beyond that by disclosing the actual money movement ('Charges the wallet'), the side effect ('Restores paused numbers once paid'), and a confirmation requirement. It stops short of covering failure modes like insufficient funds or partial payment, which matters for a billing mutation.

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?

Three short sentences, each carrying distinct information: the action, the trigger condition, and the cost/approval constraint. The wallet-charge warning is placed last where it lands as the final gate before invocation; no filler.

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 single-parameter, annotation-rich mutation with no output schema, the description covers purpose, timing, side effects, and the approval requirement. It leaves the return behavior unstated (e.g., which numbers were restored, what a partial success looks like), which is the one remaining gap an agent would care about.

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% and the confirm property is already thoroughly documented, so the baseline is 3. The description adds the rationale behind the flag ('Charges the wallet: confirm the amount with the user first'), telling the agent why an explicit approval gate exists rather than just that it does.

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 ('Retry') and resource ('overdue monthly number and registration fees') plus the funding source ('from the Spur wallet'), and adds the timing context ('normally retried daily') that no sibling covers. Nothing else in the sibling list does wallet-funded fee retry, so it is unambiguous.

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?

'Use after the user adds funds' gives a concrete triggering condition, and 'normally retried daily' implicitly signals this is an out-of-band expedite rather than a routine call. It does not explicitly name alternatives such as spur_top_up_wallet or spur_check_payment, which would have made routing fully explicit.

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