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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds value beyond that by disclosing the returned payload shape (customer, status, recurring items, billing cycle, next billing date, scheduled changes) and that results are 'bounded' — meaningful since there is no output schema. It omits rate limits and auth requirements, which the schema partly covers.

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?

Two tight sentences with the returned-field list front-loaded and no filler. The second sentence is arguably a restatement of the status enum, but it frames the practical question the tool answers, so it earns most of its place.

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 usefully enumerates the return fields and scoping, and the 6-parameter schema is well documented (83% coverage). Remaining gaps — pagination mechanics, max per_page, and environment defaulting — are handled by the schema, so little is missing for correct invocation.

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 83%, so the schema already documents after, status, _apiKey, per_page, customer_id and _environment. The description adds only implicit linkage to the status categories, not syntax or format detail. Baseline 3 is appropriate.

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 (Return) and resource (Paddle subscriptions) and enumerates the fields included, which lets an agent distinguish it from paddle_list_customers and paddle_list_transactions. It does not, however, contrast itself against the ambiguous sibling 'list_subscriptions', so it stops short of a 5.

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?

The second sentence implies usage by naming the questions it answers (which accounts are active, trialing, paused, past due, canceled), which maps to the status filter. There is no explicit when-not guidance, no mention of alternatives like paddle_list_transactions, and no note on when to page with 'after'.

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