Create a subscription

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

Annotations already flag a non-idempotent, non-destructive write in an open world, so the description's contribution is the state machine: the first invoice is issued immediately via `latest_invoice` when there is no trial, and the subscription only becomes active once that invoice is paid. That, plus the live-key refusal, is real behavioral context an agent cannot infer from the annotations. It still omits what happens on failure or what identifier is returned.

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?

Three short paragraphs with the constraint front-loaded and zero filler; every sentence carries information. The only wasted line is the opening 'Create a subscription', which duplicates the title verbatim.

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 non-idempotent creation tool with a nested metadata object, no output schema, and 67% param coverage, the description covers lifecycle and key restrictions but leaves the agent guessing about prerequisites (must the customer and price already exist?) and what the response contains. It is adequate to attempt the call but not to call it confidently.

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 67%, so the description is expected to fill gaps and it does not — coupon, quantity, metadata, and the price/customer interactions are never mentioned. The one parameter-adjacent statement (trial timing) describes the consequence of omitting `trial_days` rather than explaining any of the six inputs.

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?

The opening line 'Create a subscription' merely restates the tool name and title, and the rest of the text describes a billing lifecycle rather than the operation itself. The 'renewed by invoice' detail hints at a specific collection mode, but it never states that this is one of several ways to start a paid relationship (checkout session, payment link, invoice), so the sibling boundary stays blurry.

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 only explicit guidance is a hard constraint — 'Test keys only: refused with a live key' — which is valuable but is a precondition, not a when-to-use rule. Nothing says when to prefer this over create_checkout_session, create_payment_link, or create_invoice, all of which sit in the sibling list and could plausibly start the same billing relationship.

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