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

With annotations only telling the agent this is a write op (readOnlyHint=false) in an open world, the description carries the rest: billing stops, the customer is unenrolled and immediately loses product access, past payments are NOT refunded, and each call needs user confirmation plus a Cotlet API key scoped to the app. That is unusually rich behavioral disclosure for a cancellation tool.

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 is front-loaded, but the middle is repetitive: "Billing stops and access ends" is restated as "prevents future charges and unenrolls the customer, who immediately loses access," and the confirmation rule appears twice ("you confirm each call; you can switch that off" then "confirm with the user before each call"), which reads as slightly contradictory rather than layered.

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, but for a single-parameter cancellation tool the description supplies everything an agent needs: the mutation's effects, irreversibility of past charges, confirmation requirements, and authentication scope. Nothing material is left for the caller to infer.

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 there is only one parameter, whose schema description points to list_subscribers as the source. The description adds nothing about subscription_id format or sourcing, but with a single fully documented parameter the schema does the work; baseline is 3-4 and the phrasing "subscriber's plan" aligns loosely with the parameter.

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 ("Cancel a subscriber's plan") and immediately defines the outcome ("Billing stops and access ends"). No sibling in the Payhip set cancels a subscription, so there is nothing it could be confused with, and the UI analogy ("Does the same as Cancel Subscription on the Subscribers tab") removes any residual ambiguity.

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 clear operational context: cancellation prevents future charges, does not refund past payments, and requires explicit per-call confirmation with the user. It stops short of an explicit when-not-to-use statement or a named alternative (e.g., pausing vs canceling), but no such alternative exists among the Payhip siblings, so the guidance is effectively complete.

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