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

Annotations already flag destructive=true and idempotent=true, but the description goes well beyond them: it discloses the billing consequence ('Nothing is refunded'), the deferred timing of reductions ('scheduled for the end of the paid period. Capacity stays until then'), that the current count cancels a scheduled reduction, and that nothing happens on any client until confirm is true. That is exactly the operational context a destructive mutation needs.

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 in the first sentence and every following sentence carries a distinct fact about billing, timing, or idempotency. The telegraphic sentence fragments ('Capacity stays until then. Nothing is refunded.') are efficient but occasionally read as compressed notes rather than prose, slightly reducing scannability.

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?

For a destructive, charge-incurring mutation with no output schema, the description covers the important unknowns: cost implications, irreversibility of refunds, deferred downgrade timing, preview semantics, and idempotency. It does not address required permissions or error/refusal responses beyond 'A higher count is refused,' leaving some gaps for a billing-adjacent write operation.

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 50% — confirm and idempotency_key are documented in the schema, while number_id and channel_count are not. The description compensates by explaining confirm as a preview-versus-charge gate ('Every client changes nothing until confirm is true') and by describing the cross-tool idempotency behavior of idempotency_key shared with add_number_channels, which the schema does not state. The 'number includes 2' phrasing about channel_count is cryptic and only partly clarifies the minimum already in the schema.

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?

States a specific verb and resource: 'Sets how many calls one number on this account can take at once.' It also explicitly distinguishes itself from the sibling add_number_channels by declaring 'Single extra channels are not sold by this tool,' so an agent can route between the two without opening either schema.

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?

Gives concrete decision context: higher counts are refused (use a different path), lower counts are scheduled for period end rather than applied immediately, and setting the current count clears a pending reduction. The alternative for acquiring single channels is implied by naming add_number_channels in the idempotency sentence rather than stated as an explicit 'use X to add channels' instruction.

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