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

Goes well beyond the annotations by disclosing downstream side effects: the shop's own automations run, so the customer may receive email or SMS and webhooks may fire. It also explains the compounding behavior of repeated calls and that the reply carries a skipEventId needed for reversal — exactly the operational context a destructive, non-idempotent write 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?

Four tight sentences: intent first, precondition second, hazards and undo third, endpoint last. Nothing is padded and the leading 'WRITE:' flags the mutation before an agent reads further.

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 two-param destructive mutation with no output schema, the description covers precondition, irreversibility/undo mechanism, reply field, and external side effects. An agent has everything needed to decide and to call it responsibly.

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 both parameters are documented with formats and gid:// alternatives, so the schema carries the weight. The description adds only the endpoint template, which implicitly maps customer_id and subscription_id to path segments but supplies no new format or validation detail.

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?

Opens with a specific verb+resource phrase ('skip a subscription's next order') prefixed by a WRITE marker, and closes with the underlying endpoint. It is unmistakably distinct from sibling reads like awtomic_get_subscription and from mutators like awtomic_set_next_billing_date or awtomic_cancel_customer_subscription.

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 a clear precondition ('The subscription must be active'), an explicit warning against repeat invocation ('each call skips one more order, so do not repeat it'), and names the undo path via awtomic_undo_skip. It stops short of contrasting with the nearest sibling, awtomic_set_next_billing_date, which an agent could reasonably confuse with this when the goal is a precise date.

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