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

Annotations already declare readOnly, idempotent, and openWorld hints, so the bar is lower. The description still adds meaningful behavioral context: it returns a link only once payment is confirmed, is not a busy-wait, requires the create_checkout session_id, and never returns personal data. This goes well beyond the annotations.

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 cover purpose, timing, polling behavior, source of the parameter, and privacy constraints with no filler. The main action is front-loaded and every sentence carries useful information.

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 simple one-parameter tool with rich annotations and no output schema, the description is complete: it identifies the parameter, the expected caller flow, the polling cadence, and what the tool returns. Nothing critical is missing for an agent to invoke it correctly.

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 100%, and the schema already explains that session_id is the value returned by create_checkout and starts with 'cs_'. The description reinforces that the session_id is required and cannot be replaced by email or other lookup, but it does not add substantial meaning beyond the schema.

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 states a specific verb and resource: check a checkout created by create_checkout and return the delivery link once paid. It clearly distinguishes the tool from siblings like create_checkout and the unrelated get_* and search_* tools, and explicitly notes that orders cannot be listed, searched, or looked up by email.

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 explicit guidance on when to call the tool: after handing the person the checkout URL. It also warns against using it as a busy-wait loop by recommending a few seconds between calls, and explains that the session_id must come from create_checkout. No alternatives are relevant, and the constraints are clearly stated.

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