Create a checkout session

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

Annotations already declare the mutation/open-world/non-idempotent profile, and the description adds real value on top: a live-mode refusal with 403 `bill_overdue` when a Perly Pay bill is past 14 days, and the constraint that test keys are required. That is exactly the kind of failure-mode context annotations cannot convey. It stops short of describing the returned session object's shape.

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 short sentences, front-loaded with the payload shape before the redirect mechanics, then the edge-case refusals. The trailing 'Test keys only: refused with a live key.' is terse to the point of being clipped, but nothing is wasted.

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?

No output schema exists, and the description covers the essential return value (`url`) and how to embed it, plus the principal failure conditions. An agent could call this correctly on the first attempt; only the full set of response fields and expiry semantics of the returned session are left implicit.

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 75%, and the description compensates with semantics the schema cannot express: line_items is constrained to a single currency across the cart, and return_url/cancel_url are explained as success vs. abandonment destinations rather than merely 'An http(s) URL.' The 20-item/one-currency business rule is the single most important thing to get right here and it is stated plainly.

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 opens with the specific verb+resource ('Create a checkout session') and immediately characterizes the payload ('A cart of 1–20 prices in one currency'), so the agent knows this is a session-creation tool rather than a one-off charge. It does not explicitly distinguish itself from siblings like create_payment_link or create_invoice, which is the only thing keeping it from a 5.

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?

It gives concrete operational context: redirect the buyer to `url`, embed via pay.js overlay with `data-session`, and where the buyer lands on success vs. abandonment. Missing is any statement of when to prefer this over create_payment_link or create_invoice, but the usage flow itself is unambiguous.

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