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

Annotations only cover safety flags (readOnly=false, destructive=false, openWorld=true); the description goes well beyond them by explaining the billing mechanics (credits unused time, charges the new plan for the rest of the term, invoice total is the difference), the fate of mandatory addons, that the customer sees the invoice, that confirmation is on by default, and the required API key scope.

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?

The purpose and the apply/prorate mechanics are front-loaded, and each sentence carries distinct information (billing behavior, addon persistence, confirmation, permissions). It is on the longer side, and the confirmation/API-key sentences could be tightened, but nothing is redundant.

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 compensates by stating what is returned ('the subscription and any invoice the change created') and it discloses the mutation's side effects, the customer-visible invoice, the confirmation gate, and the auth requirement. Nothing material for correct invocation 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 100%, so the baseline is 3. The description exceeds that by explaining the interaction of apply and prorate (the credit/charge netting that produces the invoice total) and the delay semantics of next_renewal, which the per-parameter schema strings do not spell out.

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: 'Move a subscription to another plan or quantity, now or at renewal,' and adds scope detail (quantity changes, immediate vs renewal). It is clear and actionable without opening the schema. It does not, however, contrast itself against sibling operations such as chargebee_cancel_subscription or chargebee_apply_coupon, so it falls short of full sibling differentiation.

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 real when-to-use guidance for the core decision: use apply=immediately with prorate to credit unused time, or next_renewal so nothing is invoiced until renewal. It also states the default confirmation behavior and that it can be switched off. It stops short of naming alternatives (e.g., cancel vs. downgrade paths), so no explicit when-not-to-use.

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