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

With only readOnlyHint=false supplied, the description carries the real behavioral load and does so well: it states the first cancel call is a no-op that returns a warning text to read aloud plus a confirmation_id, and the second call produces one link per company. It also discloses the billing_not_enabled precondition and the billing.portal_own capability requirement. This is far more than the annotation conveys, so no contradiction arises despite the non-mutating first step.

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?

Information is front-loaded and every clause carries meaning; nothing is filler. The density is high, though — nested parentheses and a long middle sentence make the two-step flow harder to parse on first read than it needs to be.

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?

No output schema exists, and the description compensates by describing the return shape for the cancel flow (companies, warning, confirmation_id, one link per company) and the error state. It does not say what the plain non-cancel call returns beyond 'a link', which is a minor remaining gap for a 4-parameter tool with a capability gate.

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% and the parameter descriptions already explain each field, so the baseline would be 3. The description adds genuine ordering semantics not encoded in the schema: cancel and companies belong to the first call, confirmation_id must be sent alone on the second, and one link is produced per company.

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 names the concrete artifact (a Stripe Customer Portal link) and enumerates what it surfaces: payment method, invoices, cancellation. That is specific enough to separate it from checkout-style siblings, but it never names an alternative tool (e.g. get_checkout_link), so the differentiation is implicit rather than stated.

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 an explicit two-phase protocol: first call with cancel:true (optionally companies:"all") which changes nothing, then, only after the person verbally agrees, a second call with just the confirmation_id. It also names the alternative outcome (billing_not_enabled until billing starts), so an agent knows both the happy path and the blocked path.

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