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

Goes well beyond the annotations: the link is one-time, payment happens on Stripe's own page, the connection never sees the card, credits land within a minute regardless of device, nothing renews, and the call requires a signed-in connection with billing:checkout permission and is rate limited per account. This is exactly the context the readOnly/openWorld/idempotent hints cannot convey.

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 critical constraint and the sibling exclusion are front-loaded, and the return shape is stated last. It is a dense single block, though, and the product enumeration partially repeats the schema enum, which costs some readability against a tool an agent only calls occasionally.

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 both the preconditions (permission, user consent, price disclosure) and an explicit return shape ({ checkout_url, product, pack, price_cents, units, unit, then }). Nothing material an agent needs before calling is missing.

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 already 100%, but the description adds real meaning: it ties each product value to concrete pack ids, prices and units (min40 = 40 minutes for $10, out200 = 200 resolved conversations for $98), and states when line_id is required. That pricing and unit mapping is information the schema does not carry.

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 artifact: 'Returns a one-time Stripe checkout link for a prepaid pack,' and immediately scopes it as topping up something that already exists. It distinguishes itself from set_up_answering_line by name, so an agent can route between the two without opening a schema.

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 preconditions: 'Only call it when the customer asked to buy, and tell them the price first,' plus the alternative 'to start a new answering line use set_up_answering_line.' It also states the constraint that for line products the pack must match the line's billing_mode.

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