beel_create_invoice

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

The annotations are weak (readOnlyHint=false, openWorldHint=true, no destructive info), so the description carries the full behavioral burden — and it delivers. It discloses the crucial async semantics: a 2xx means 'accepted for submission', never 'registered with AEAT', with submission_status returned as PENDING. It also discloses that proforma is created directly in ACTIVE state, numbered PRO- from the non-fiscal series, and that issue_directly does not apply to it. This goes well beyond the schema, and there is no contradiction with the annotations — the write/issue semantics align with readOnlyHint=false.

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 long but dense, and nearly every sentence earns its place: core semantics, proforma exception, derivation alternative, endpoint, and the guardrail pointers. It is well front-loaded with the issue_directly and submission_status semantics before the proforma aside. The six-bullet guardrail list is somewhat verbose but each bullet points to a distinct legal constraint, and closing on the beel_docs_search referral is a sensible compression strategy. Slightly long, but appropriately so for the complexity.

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 tool of this magnitude — a nested body schema, no output schema, weak annotations — the description is remarkably complete. It covers the async submission semantics, the proforma special case, the derivation sibling, the endpoint, and surfaces six guardrail resources plus a docs-search fallback for exhaustive rules. Nothing an agent needs to call it correctly is missing; the external resource pointers are the correct way to handle the depth of Spanish fiscal law here.

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 high at 75%, so the schema already documents most parameters in exhaustive detail. The description adds real semantic value on top for the highest-stakes parameters: it explains what issue_directly actually does (numbered and issued in the same call), the verifactu submission_status=PENDING meaning, and how type: PROFORMA behaves. Given the schema does the heavy lifting, the description's targeted clarification of the trickiest fields earns a 4 rather than the baseline 3.

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: 'Creates an invoice under this company (NIF)' with issuer data drawn from the company in the path. It clearly distinguishes itself from siblings by name — it routes copying to beel_create_invoice_derivation, notes CORRECTIVE is handled elsewhere, and lays out proforma issuance behavior. An agent can immediately tell what this tool does and what it is not.

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?

The description gives contextual usage guidance: the issue_directly vs draft distinction, when proforma semantics apply, and an explicit pointer to derivations for copying an existing invoice. However, it does not explicitly contrast against close siblings like beel_create_invoice_batch or beel_create_recurring_invoice, and only implicitly implies CORRECTIVE lives on beel_create_corrective_invoice via the schema rather than the description prose. Clear context with one named alternative, but not a systematic when-to-use/when-not-to-use matrix.

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