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

Annotations already declare write (readOnlyHint=false), non-idempotent, non-destructive, open-world. The description adds genuinely new behavioral context beyond that: no charge occurs at order time, payment happens on Stripe's page, delivery is by email, and the order_key is the tracking handle. It doesn't cover link expiry or retry/idempotency behavior, so not a 5.

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?

Purpose and the no-charge guarantee are front-loaded, and every sentence carries operational content (what to give the user, what to retain, what compare mode yields). The telegraphic style ('Give the person the link and the price.') is efficient but slightly fragmented, keeping it short of a 5.

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?

With no output schema, the description carries the return-value burden and does so: payment link, price, order_key. For a 4-parameter ordering tool with two required inputs sourced from sibling tools, this is nearly complete, missing only failure/link-expiry behavior and a pointer that place_id comes from find_business.

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%, so place_id and trade rely on the schema/related tools. The description meaningfully enriches compare_with_place_id, explaining it must be a business of the same trade in the same suburb and that it produces two reports plus a comparison — information the schema's one-line description does not convey.

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+resource ('Start an order') and its immediate output ('get a Stripe payment link'), then traces the full lifecycle through payment to email delivery. This is clearly distinguishable from siblings like get_report and check_order without opening either 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?

Usage is implied through the workflow ('Give the person the link and the price', 'Keep the order_key to follow the order'), which tells the agent what to do with the result. However, it never names an alternative tool or states when this should not be used (e.g., when a report already exists, use get_report; to poll status, use check_order).

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