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

Annotations only declare the safety profile (non-readonly, non-destructive, non-idempotent, closed-world); the description adds real behavioral context beyond them: a real charge is initiated, the guest must approve a prompt on their own phone, and the ticket is issued only after payment confirms. It does not, however, warn about duplicate charges on retry despite idempotentHint=false.

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 sentences, each carrying distinct load: the action/channel, the payment/approval flow, and the card alternative. The critical constraint (real charge, guest approval) is front-loaded with zero filler.

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 7-param mutation with no output schema and low schema coverage, the description covers the essential async payment loop and the card fallback, so an agent knows the flow will not complete synchronously. It still leaves tier/quantity semantics and retry-safety unspecified.

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 description coverage is only 29% (mobileNumber and billingCountry), so the description should compensate. It reinforces that mobileNumber is the guest's own phone for approval, but says nothing about tierId, eventId, quantity limits, customerName, or customerEmail — a notable gap given tier selection is likely required to buy.

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+resource+channel ('Buy event ticket(s) via mobile money on behalf of a real guest'), which immediately distinguishes it from the reservation/room/service booking siblings. It also names the adjacent read tool (check_event_availability) that exposes what is available.

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 explicit routing: use this for mobile money, and card payment is not supported here — check_event_availability returns a cardCheckoutUrl for that case. What is missing is guidance on prerequisites (e.g. whether availability/tier must be resolved first) and whether retries are safe.

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