merit_create_recurring_invoice

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it mostly spends its words on enum codes and date formats rather than behavior. It does not explain what invoking this tool actually does — whether an invoice is immediately generated, scheduled, or sent to the customer (the endpoint name 'sendperinvoice' hints at sending but is never explained) — nor does it disclose side effects, idempotency, or authorization needs. For a creation tool with zero annotation coverage, this is a significant transparency gap.

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?

Compact and front-loaded: the core purpose leads, followed by compact enum tables and a date-format note. No filler words. Minor deduction because the cycle enum and ISO date format duplicate what the schema already states, and that space could have been used to describe required nested object shapes, but overall the structure is tight and scannable.

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?

This is a high-complexity tool — 12 parameters, 8 required, 4 nested object parameters, no annotations, and no output schema — and the description is not nearly complete enough for this context. It omits the structure of the required customer, invoiceRows, and taxAmount objects, the meaning of totalAmount, the purpose of optional parameters, the behavior of the POST call, and the response shape. An agent could not reliably construct a valid request from this definition alone.

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 low (42%), so the description must compensate for the 7 undocumented parameters (payer, endDate, invoiceNo, taxAmount, invoiceRows, totalAmount, currencyCode) — and it does not. It does add genuine value for the period enum, decoding cryptic values like '6 = current less cycles' that the schema leaves as 'relative to the cycle', but it merely repeats the cycle enum and date formats already present in the schema. It partially compensates for low coverage but leaves the required nested objects (customer, invoiceRows, taxAmount) completely opaque.

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 ('Create a Merit Aktiva recurring invoice') and includes the exact API endpoint (POST /api/v2/sendperinvoice). The term 'recurring invoice' cleanly differentiates this from siblings like merit_create_sales_invoice (one-off) and merit_list_recurring_invoices / merit_get_recurring_invoice (read operations).

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 context is implied: the 'recurring invoice' phrasing tells an agent this is for scheduled invoices rather than one-off sales invoices, and the endpoint positions it as the create operation among the recurring-invoice siblings. However, there is no explicit when/when-not guidance, no mention of prerequisites (e.g., existing customer), and no named alternatives telling the agent which sibling to choose instead.

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