invoices_issue

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, but the description goes well beyond them: it discloses the full side-effect chain (validation, series numbering, XML generation, PDF gated behind the Pro plan) and the irreversibility of the state change. The Pro-plan gating and "cannot be edited" are exactly the kind of runtime context annotations cannot express. The irreversibility note is in tension with destructiveHint=false only superficially — nothing is destroyed — so this is not a contradiction.

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 tight sentences, front-loaded with the action and its consequences, then the irreversibility warning, then the sibling routing. No filler, and each sentence carries a distinct piece of decision-relevant information.

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?

With no output schema, the description should indicate what an agent gets back and what failure looks like; it covers the success path and the Pro-plan caveat but is silent on validation failure behavior and on the returned object. For a two-parameter mutation with full annotation coverage, this is nearly complete but leaves the error path unaddressed.

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 both parameters (uuid, companyId) are already documented, and the description adds no syntax or format guidance beyond them. The baseline 3 applies; the only extra semantic signal is the implicit precondition that the referenced invoice must be in draft, and the companyId override/active-company behavior is left entirely to the schema.

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 definition states a specific verb and resource ("Issue a draft invoice") and enumerates the concrete effects — validation, series number assignment, UBL 2.1 XML, PDF on Pro plan, draft→issued state change. It explicitly names the sibling it is not (invoices_submit for ANAF e-Factura), so an agent can separate it from invoices_validate, invoices_pdf, and invoices_submit without opening any schema.

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 a clear precondition ("a draft invoice") and routes the follow-up action to invoices_submit, naming the condition that selects it. The warning that an issued invoice cannot be edited functions as an implicit "do not use if you still need to modify it," but there is no explicit when-not list or mention of what happens on a non-draft input.

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