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

Annotations only supply destructiveHint=true, so the description carries most of the burden and does so well: it discloses that Chitanta issues a numbered receipt that 'cannot be undone from this server', that other types create no document, and that invoice paid status in the books changes. It stops short of covering failure/idempotency behavior for multi-invoice or partial-value cases, so it is strong but not exhaustive.

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-loaded with the core action and built as a single dense semicolon-chained sentence with no filler; every clause adds a constraint, exclusion or side effect. The trade-off is readability — no line breaks or visual grouping across five distinct behaviors.

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 destructive, 7-parameter write with no output schema, the description covers the essentials: what it mutates, irreversibility, which types create documents, and an unsupported case. It leaves gaps on multi-invoice/partial-failure semantics and required permissions, which an agent would need before committing a bulk collection.

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 100%, so the baseline is 3. The description restates what the schema already documents (value = partial, single invoice; Chitanta needs receipt_series) and adds only one genuinely new semantic point: client and amount are derived from the invoices rather than supplied, which explains why no amount/payer parameter exists.

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 ('Record a collection (incasare) against one or more issued invoices') and immediately scopes it as a write-to-books operation, which separates it from read-side siblings like smartbill_get_invoice_payment_status. The sync name/description language (incasare, Chitanta) matches the domain so an agent knows exactly which action is being invoked.

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?

Gives clear conditional guidance: 'value (single invoice only)' for partial payments, 'type Chitanta' for a numbered receipt, an explicit exclusion ('Fiscal receipts (Bon) are not supported'), and an operational instruction ('confirm with the user'). It never names an alternative sibling tool for the excluded/near-miss cases, so routing is implied rather than explicit.

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