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

The description adds substantial context beyond the annotations: the link is Stripe-hosted, creating it triggers no charge/change/cancel, the user confirms on Stripe, and the flow returns to Patch's fixed billing page. It also discloses retry behavior (reuse request_id after a lost response) and a security constraint about card details. Note that request_id reuse reads as an idempotency key while idempotentHint=false; this is a nuance about deduplication rather than a direct contradiction.

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?

Four short sentences, each earning its place: purpose first, then safety/what-it-does-not-do, then return destination, then operational and security guidance. No filler or repetition of schema fields.

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 an output schema present, return values need not be described, and the description still adds the meaningful outcome (redirect to Patch's fixed billing page). For a one-parameter, non-destructive mutation with annotations covering the safety profile, nothing an agent needs to invoke it correctly 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 description coverage is 0% for the single request_id parameter, so the description must carry the meaning — and it does, explaining that the same request_id should be reused after a lost response, which tells the agent this is a deduplication key. It does not mention the UUID format, though the schema pattern already constrains that.

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?

"Create a Stripe-hosted billing portal link for this account's existing Stripe customer" states a concrete verb (create), resource (billing portal link), and scope (this account's existing Stripe customer). It also implicitly separates itself from the subscription-change siblings by noting it does not charge, change, or cancel a subscription, though no sibling is named explicitly.

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 makes clear the intended path: the agent generates a link and the user makes billing changes on Stripe, so this is the tool for handing billing management off rather than executing changes directly. It also gives operational guidance (reuse request_id after a lost response) and a hard exclusion (never request or accept card details in chat). It stops short of naming a sibling like execute_subscription_change as the alternative when the agent is supposed to act directly.

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