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

Annotations already declare readOnly/non-destructive, and the description corroborates rather than contradicts ('Read-only; this tool itself never moves money'). It adds substantial context annotations cannot convey: the 402 challenge flow, the exact payment headers (PAYMENT-REQUIRED, WWW-Authenticate), that the same request is retried with a payment header, and that credits land on settlement and never expire.

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?

A single dense paragraph, but it is front-loaded with the highest-value fact (what the offer returns) and each subsequent clause carries actionable payment-flow detail. Slightly long and list-free for a multi-step flow that would benefit from structure.

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 payment-negotiation tool with an output schema (so return shape need not be restated), the description covers everything an agent needs: what is returned, which rails exist, how to trigger the challenge, how to settle, and when the credit arrives.

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 genuine semantics beyond the schema: `required` originates from an insufficient-credits error and selects the smallest covering offer size, which clarifies the intended data source for that value.

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 ('Get the offer for a pay-as-you-go credit top-up') and enumerates exactly what the offer contains: the POST URL, the USD price, and the accepted rails. It is clearly distinguishable from sibling account tools like get_credits because it returns a payment offer rather than a balance.

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?

Gives clear triggering conditions: pass `required` when an insufficient-credits error blocks an action, or pass `credits` for a specific size. It never names an alternative sibling tool (e.g. get_credits) to route between, so it stops short of explicit when-not guidance.

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