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

Annotations already declare destructive/non-idempotent, but the description adds real context beyond them: the customer's card is actually charged, the server-side 409 ORDER_RECENTLY_PLACED guard, and that the shop's automations may send email/SMS and fire webhooks. That is the side-effect disclosure an agent needs before committing a charge.

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?

Front-loaded with 'WRITE' and a capitalized charge warning, then constraints, then usage guidance, then side effects, then the endpoint. Dense but every sentence carries decision-relevant information; no filler.

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, no-output-schema action the description covers risk, preconditions, error behavior, and side effects. It stops short of saying what a successful response returns (e.g., the created order id), which would help an agent chain follow-up calls.

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 the baseline is 3, but the description adds operative meaning beyond the schema by scoping manual_retry ('only to retry a failed billing attempt') and reinforcing that confirm_charge must be true as a consent gate. It does not add anything about id formats, which the schema already covers well.

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: bill the saved payment method and create the subscription's next order immediately rather than waiting for the billing date. This clearly distinguishes it from siblings such as awtomic_set_next_billing_date and awtomic_skip_next_order.

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?

Explicit when-to-use ('Only use it when the user explicitly asks to place this order now'), the guard condition (confirm_charge must be true), and a narrow conditional path for manual_retry ('only to retry a failed billing attempt'). The refusal condition (409 ORDER_RECENTLY_PLACED under 10 minutes) further bounds when the call is appropriate.

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