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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is to explain consequences — which it does by spelling out that charges and shipments stop until resume. It does not explain why the operation is flagged destructive (e.g., any state or schedule effects that are not restored by resume), which is the one thing an agent would want before pausing a live subscription.

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?

A single compact line with the operation type front-loaded, then effect, then the undo route, then the endpoint. No sentence 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?

For a one-parameter mutation with no output schema, the description covers effect, reversibility, and endpoint, which is sufficient to invoke it correctly. The remaining gap is intra-family routing versus cancel/reactivate siblings.

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?

There is a single parameter with 100% schema description coverage, and the schema already warns to use `id` rather than `internal_id`. The description adds nothing beyond that, which is the expected baseline when the schema does the work.

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 (Pause) and resource (an active subscription), and immediately quantifies the effect: "no further charges or shipments until it is resumed." The WRITE prefix and the endpoint hint make it unmistakable versus the read siblings like get_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?

Specifies the precondition (an active subscription) and points to the inverse operation, sealsubscriptions_resume_subscription, as the undo path. It does not, however, distinguish pausing from neighboring lifecycle tools such as cancel_customer_subscription, schedule_cancellation, or reactivate_subscription, so an agent facing a "stop billing" request still has to infer the right choice.

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