recurring_create

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

With no annotations, the description carries the full burden, and it does disclose two real behavioral traits: the schedule is created in an active state and will issue invoices without further action, and the products are ordinary documents rather than a special entity type. It omits important consequences — that generated invoices are not finalized by default (auto_finalize defaults false), how to stop or cancel the schedule, and what state results after cancellation.

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 sentences, front-loaded with the core purpose and with zero filler. The final sentence's tool reference is inaccurate, which costs it a point, but the prose itself is tight.

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 10-parameter tool with a large nested template schema, no output schema, and no annotations, the description covers purpose and activation state but leaves the most complex surface unexplained: how the invoice_template payload is parameterized per occurrence, and how invoice numbering is resolved between the template and numbering_sequence_id. Adequate to start, not adequate to call 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 80%, so the schema already documents the key fields (frequency, start_date, interval, end_date, max_occurrences, auto_finalize), and the description adds nothing about them. The largest omission is `invoice_template`, a deeply nested payload used as the per-occurrence template — the description never explains how its invoice_number, issue_date, or currency fields interact with recurring generation or with numbering_sequence_id.

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 description names a specific verb and resource — 'Set up a schedule that issues invoices on its own' — which distinguishes it from the one-off document_create sibling by emphasizing autonomous, recurring issuance. It stops short of explicitly naming the sibling it replaces, so it lands at clear-but-not-differentiated.

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?

It gives implicit context (it starts active, first invoice fires when the schedule next falls due) and points to a reader for outputs, but offers no guidance on when to choose this over document_create, no prerequisites (an existing customer_id and business_profile_id are required), and no mention of recurring_pause/recurring_resume/recurring_cancel for lifecycle management. Notably it names `list_generated_invoices`, which does not appear in the sibling list — the closest match is `recurring_generated`.

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