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

Annotations cover the safety profile (readOnly=false, idempotent=true, openWorld=true), and the description adds value beyond them: it clarifies the return is a checkout URL not a paid eSIM, that fulfilment only begins after verified payment, and that idempotency keys must be reused across retries to avoid duplicate orders. This is exactly the kind of consequence-level context annotations cannot express.

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 the source of quote_id, with preconditions and caveats following in a logical order. It is dense (roughly three long clauses) but no sentence is filler; minor tightening would make it a 5.

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 mutation tool with no output schema, the description supplies the missing return-value information (checkout URL, pending state), the fulfilment timing, and the retry/idempotency policy. An agent has everything needed to decide when to call it and how to handle repeats.

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 baseline is 3; the description nonetheless adds intent-level meaning by framing customer_confirmed and terms_accepted as explicit customer-approval gates rather than mere booleans, and explains the idempotency_key reuse rule beyond the schema's 'unique per purchase'. Email and lang semantics are left entirely to the schema.

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 ('Create a pending customer-paid Stripe Checkout') plus the exact input provenance ('from a quote_id returned by prepare_order'). It explicitly distinguishes the result from a completed purchase ('returns a checkout URL, NOT a paid eSIM') and names the sibling to use for other payment methods.

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 explicit preconditions for invocation (only after the customer approved the displayed plan and price and accepted terms) and routes to the alternative ('use purchase for other supported payment methods'). Retry behavior is also covered via idempotency_key reuse.

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