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

With readOnlyHint=false and destructiveHint=false already declared, the description still adds real value: no card is ever charged by the agent, nothing is charged until the person completes Stripe's page, refused quantity/currency combinations are stated, and credit goes to the initiating agent. The notable gap is idempotency – idempotentHint=false, yet the description never says whether calling twice yields two checkout links or how long a link lives.

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 purpose and return value are front-loaded in the opening clause, and each subsequent sentence covers a distinct decision (quantity, currency, exclusions, payment flow). It runs long as a single block and the two currency sentences partially overlap, but little is genuinely redundant.

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?

There is no output schema, so the description must describe the return value and does ('a Stripe checkout link'). Combined with the exclusions, refusal rules, and the human-pays-on-Stripe model, an agent has everything needed to call this correctly and set user expectations.

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 67%, and offerKey has no schema-level description at all, so the description carries that weight by pointing to get_offers as the source of the key. It also adds semantics beyond the schema for quantity (one diamond per session, other offers refused) and explains currency matching the caller's country, though it stops short of an offer-key format example.

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 outcome ('Start a purchase ... get back a Stripe checkout link') and enumerates exactly which offers qualify (Pirate Pass, Forge Pass, Captain on Deck, Pirate Forge tier). It explicitly routes away from event tickets and names get_offers/list_events as the related siblings, so an agent can distinguish it without opening schemas.

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 both when-to-use (offers from get_offers that are on sale/listed) and when-not (event tickets belong on the event page from list_events). It also spells out the conditional rules for quantity and currency, including the refusal case for quantity on non-session offers.

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