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

Adds real value beyond the annotations by disclosing consequences and timing: refund 'revokes access' and cancel takes effect 'at period end', plus the confirmToken gating. It doesn't explain resume/portal behavior or what the response contains, so it stops short of rich behavioral disclosure. Note the access-revocation disclosure sits in mild tension with destructiveHint=false, though it is framed as billing consequence rather than data destruction.

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?

Two tight sentences with the action list front-loaded and the token requirement appended. Minimal waste, though the terse fragment style and the missing 'resume' leave the enumeration feeling slightly incomplete rather than polished.

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 no output schema, the description should carry more of the return/error story (e.g., that confirmToken issues a CONFIRMATION_REQUIRED reply, what portal returns). It covers calling correctly for three of four actions but leaves resume and outcomes unexplained; annotations at least carry the safety profile.

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%, so baseline is 3, but the description adds a relationship the schema doesn't state: which actions (cancel, refund) require confirmToken. The action enum itself is described only as 'Action' in the schema, so the prose enumeration is the main source of meaning for those values, though it omits resume.

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?

Enumerates concrete actions (cancel at period end, refund last payment, open billing portal), which is far more specific than the vague name. However, it omits the 'resume' action that the schema enum permits, and it doesn't explicitly distinguish this from the sibling billing_status or upgrade_plan.

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?

Implies context by stating that cancel and refund require a confirmToken, which signals these are gated/destructive-flow actions. But it gives no explicit guidance on when to choose this over billing_status or upgrade_plan, and no preconditions such as which plan states allow a resume.

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