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

Goes well beyond the annotations by disclosing the human-in-the-loop payment requirement, the already-subscribed short-circuit, and that prices are returned in the result. It does not address that idempotentHint=false means repeated calls may spawn multiple checkout sessions, which is the one behavioral risk an agent could stumble into.

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?

Four short sentences, front-loaded with the purpose and the critical actor constraint before the follow-up step. Every clause carries information an agent needs to call this correctly; nothing is padding.

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 one-boolean tool with no output schema, the description covers the missing pieces itself: the key return fields (already, prices), the required next call, and the human action. Nothing an agent needs in order to invoke or follow up is absent.

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 single parameter is self-describing, so the baseline is already met; the description adds genuine economic meaning with 'yearly = 10 months' price for 12', telling the agent the actual trade-off behind the boolean.

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 concrete verb and resource ('Get a Stripe Checkout url') plus the exact scope ('extra mailboxes beyond the free limit'), which separates it from the credit-purchase sibling create_credits_checkout without naming it. An agent immediately knows what asset is being purchased and that the result is a URL, not a completed transaction.

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?

Explicitly states the workflow and the actor constraint ('The USER opens it and pays; you cannot'), names the required follow-up ('Then poll get_billing_status'), and gives a do-not-proceed condition ('Returns already:true when the account is subscribed'). Both when-to-use and the alternative path are covered.

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