Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_create_invoice_derivation

Idempotent

Creates a fresh draft invoice by duplicating an existing company invoice without modifying the source, resetting numbering, status, dates, VeriFactu data, and PDF.

Instructions

Creates a draft invoice derived from an existing invoice of this company. The source invoice, named in from_invoice_id, is not modified.

  • mode: the only value is DUPLICATE, which copies the source into a fresh draft. Recipient, lines, payment method, series and observations are copied; number, status, dates, VeriFactu data and PDF are reset.

  • Series: the one sent in series_id, or the source's when omitted. It is validated against the type of the copy, which is not always the source's: the copy of a CORRECTIVE is born STANDARD. An incompatible series fails with 422 SERIES_INCOMPATIBLE_DOC_TYPE.

BeeL API endpoint: POST /v1/companies/{company_id}/invoices/derivations (reference: https://docs.beel.es)

⚠️ Read before calling:

  • Fiscal rules, domains lifecycle: beel_rules_list with domain, or resource beel://guardrails/.

  • The status names, the proforma lifecycle, and which tool performs each operation. (resource: beel://guardrails/invoice-state-machine)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company_id": "<company_id>",
      "body": "<body>"
    },
    "name": "beel_create_invoice_derivation"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes
company_idYesUnique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
idempotency_keyNoOptional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. Changed4 schema fields changedv0.5.0
    • addedInput schema / $defs / CreateInvoiceDerivationRequest / additionalProperties
      Added value: +false
    • removedInput schema / $defs / UUID / example
      Removed value: -"550e8400-e29b-41d4-a716-446655440000"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / company_id / description
      Previous value: -"NIF (company) the operation acts on. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A NIF you do not reach answers `403`, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed."New value: +"Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed."
  3. First observedv0.3.1

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare a non-readonly, non-destructive, idempotent mutation, and the description goes well beyond them: it enumerates exactly what is copied (recipient, lines, payment method, series, observations) versus reset (number, status, dates, VeriFactu data, PDF), and names the failure mode 422 SERIES_INCOMPATIBLE_DOC_TYPE. It does not cover return shape or permission/auth requirements, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then uses bullets for mode and series, and closes with a short pre-call reading list. The API endpoint line is mildly redundant but useful for debugging; overall there is little filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter nested-body mutation with no output schema, the definition covers purpose, copy/reset semantics, series validation, and an error code, plus pointers to guardrail resources. The only meaningful gap is that it never says what the call returns (presumably the new draft invoice), which an agent may want before chaining.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema coverage the description still adds real meaning for `series_id`: it defaults to the source's series but is validated against the copy's type, and a CORRECTIVE copy is born STANDARD. It also reinforces `from_invoice_id` as the untouched source. `company_id` and `idempotency_key` are left to their already-detailed schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a draft invoice derived from an existing invoice of this company') and immediately scopes it with 'The source invoice ... is not modified.' It also rules out the adjacent operation by noting that proforma conversion is not a derivation mode, so an agent can separate this from beel_create_invoice and beel_convert_proforma_to_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete pre-call routing: consult beel_rules_list with a domain or the beel://guardrails/<domain> resource for fiscal rules, and beel://guardrails/invoice-state-machine for status names and which tool performs each operation. It does not explicitly name beel_create_invoice as the alternative for building an invoice from scratch, so the when-not-to-use case is only implied.

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

Deploy Server

Other Tools