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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral burden: it states that the result is a draft, that finalization is a separate call, that duplicate external_id values are refused with a 409 rather than double-billing, and what the return values are. That is substantial context beyond the annotations.

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?

The description is front-loaded with the purpose, then moves efficiently through workflow, tax rules, idempotency, and return values. Every sentence earns its place; there is no repetition or filler.

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?

There is no output schema, but the description explains the return payload (new draft id and total, or the existing invoice id and number on a repeated external_id). It covers the critical workflow, tax, and idempotency behavior for a mutation tool. Minor gaps remain around permissions or draft editability, but they are not essential for correct invocation.

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 56%, and the description adds important semantics the schema does not fully supply: the supported VAT values (21, 10, 4, 0) and IRPF retention values (0, 7, 15, 19), plus line-level tax-rate override behavior. It does not explain customer_id, items, notes, referencia, numero_pedido, or product_group, though those are covered in the schema descriptions.

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 opens with a specific verb and resource: 'Create a new draft invoice'. It immediately distinguishes the draft-creation step from the follow-up emission step by naming finalize_invoice, so an agent can tell exactly where this tool sits in the workflow.

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 explicitly says to review the draft with the user and then emit it with finalize_invoice (or from the dashboard), naming the alternative and the condition that selects it. It also gives explicit retry guidance via external_id, covering the when-to-use case for that parameter.

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