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

The description discloses essential behavior beyond what the annotations reveal: creating the URL has no immediate charge side effect, a human must open the link, and the tool errors in three concrete cases (missing listing, free early access, unconfigured payments). Since the annotations only hint at mutability and open-world behavior, this level of detail is what makes the tool's runtime behavior predictable.

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 with no wasted space: the first states the primary action, the second adds the crucial side-effect caveat, and the third enumerates all error conditions. Core information and caveats are front-loaded, so an agent gets the semantics immediately.

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?

Given the tool's low parameter count, the existing annotations (notably openWorldHint and destructiveHint=false), the documented error conditions, and the presence of an output schema, the description covers everything necessary to invoke the tool correctly. It tells the agent how to use the returned value, what side effects to expect, and when it will fail.

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 100%, with slug already providing a concrete example and product having a fixed enum, so the description carries little parameter burden. It adds minor semantic signal (one add-on, one listing at a time) that echoes the logged behavior, but it doesn't need to compensate for gaps. This fits the baseline of 3 for fully documented parameters.

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 opening sentence states a specific verb and resource: "Create a Stripe checkout URL for one paid add-on on one listing," with explicit scoping and the human-consumption framing ("return it for a HUMAN to open"). This clearly differentiates it from siblings like get_tool, list_offers, and submit_tool, which perform different actions on listings or offers.

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?

The description conveys when to use it clearly — to generate a checkout URL for a paid add-on — and provides a critical when-not rule: never present the result as a completed purchase since nothing is charged until a human finishes checkout. However, it never explicitly names an alternative like list_offers for discovering which add-ons are purchasable; the error conditions are behavioral constraints rather than tool-selection guidance.

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