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

Annotations already declare readOnly/openWorld/non-destructive, so the bar is lower, yet the description adds real behavior: default and max page sizes (50/200), and the non-obvious semantics that past_due surfaces active or canceled subscriptions with an overdue invoice. It also discloses the auth requirement (Cotlet API key with app access).

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-loads the core purpose and pagesize/auth facts without filler, though the opening fragment "Subscriptions with plan, state, quantity, price and renewal dates" is a slightly loose field dump rather than a clean lead sentence.

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?

No output schema exists, so the description appropriately enumerates return-item fields (subscription_id, plan code, unit amount in cents, current period end) and covers pagination and auth. Complete enough for an agent to call and consume it correctly, missing only explicit sibling routing.

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% (baseline 3), but the description goes beyond the schema by explaining the past_due enum value's special behavior, which the schema only lists as an option without defining. Pagination defaults restate per_page but the state nuance is genuine added meaning.

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 ("Lists subscriptions") and enumerates the fields carried (plan, state, quantity, price, renewal dates), which separates it from sibling readers like recurly_list_invoices or recurly_get_account. It also notes the subscription_id feeds the write tools, implicitly distinguishing it from the mutating siblings.

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?

Usage is implied rather than stated: it says items carry the subscription_id "for the write tools" and explains the past_due filter, but never explicitly says when to call this versus recurly_list_invoices or recurly_get_account, nor gives prerequisites/conditions for choosing it over alternatives.

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