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

The description discloses key behaviors beyond annotations: 'Never accepts payment details,' the reuse behavior ('Calling it again for the same plan reuses the pending order (reused: true) instead of creating a duplicate'), and the distinction between card (hosted page) and x402 (wallet). It also clarifies output structure (order_id, checkout_url/x402_url) without contradicting 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?

The description is well-structured and front-loaded with the core purpose. Each sentence adds value: the invocation context, parameter guidance, return values, rail-specific behavior, and edge-case reuse. It is appropriately sized for the tool's complexity, with no filler or redundancy.

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?

Given the tool's complexity (2 params, enum, output schema), the description is complete: it covers the full purchase flow (before and after this step), alternatives (cancel_order, get_order_status), constraints (no payment details), and edge cases (reuse, rail switching). The output schema is present, so the description need not enumerate return fields, but it does explain their meaning and next steps.

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?

While schema coverage is 100%, the description adds significant meaning: plan_id is sourced from search_esim_plans, pay_with has an elaborated default ('card') and a clear condition for x402 ('only choose it if you actually hold a wallet'). It also explains the implication of choosing a rail (browser vs. no browser), which is not explicit in the schema alone.

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: 'Start a purchase — the step after the user picks a plan from search_esim_plans.' It specifies the primary action (create checkout) and the scope (for a selected plan), distinguishing it from siblings like cancel_order or get_order_status by placing it within the purchase flow.

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?

Explicit when-to-use guidance is provided: 'the step after the user picks a plan... get_plan_details shows the current price first' and 'once they say they've paid, call get_order_status.' It also gives conditional advice for the x402 rail ('only choose it if you actually hold a wallet') and how to handle rail switching ('cancel it and start a new one'), naming the alternative cancel_order.

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