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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it warns about the MPP 402 challenge in live payments and explains that sandbox credits are simulated. This is exactly the kind of behavioral disclosure that helps an agent anticipate edge cases. No contradiction with annotations.

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 sentences, each with a distinct purpose: state the action, warn about a live-payment edge case, and clarify sandbox behavior. No filler or repetition. The most important operational detail (MPP 402 handling) is front-loaded after the action statement.

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 purchase tool with no output schema, the description covers the key operational caveats: live payment challenges and sandbox simulation. It doesn't explain return values or all parameter semantics, but the annotations (idempotentHint=true) and schema constraints fill some gaps. The description is reasonably complete for an agent to invoke the tool correctly, though a bit more parameter guidance would push it higher.

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 0%, so the description carries the burden of explaining parameters. It mentions 'card authorization' and 'account token' in the context of MPP 402, which maps to the payment_authorization parameter, but it doesn't explain amount_cents, idempotency_key, or automatic. The description adds some semantic value but leaves most parameters to be inferred from their names and schema constraints.

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: 'Purchase prepaid credits.' It uses a specific verb and resource, and the additional context about MPP 402 challenges and sandbox simulation distinguishes it from sibling tools like get_balance or set_spending_policy. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate within the broader set.

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 provides clear context on when to use this tool: when purchasing prepaid credits. It also gives a specific usage note about handling MPP 402 challenges in live payments, which is actionable guidance. It doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to select it appropriately.

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