Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_create_recurring_invoice_derivation

DestructiveIdempotent

Creates a recurring invoice template from an existing invoice, copying its lines, recipient, series, and payment data so you only define the recurrence schedule.

Instructions

Creates a recurring invoice template of this company taking its lines, recipient, series and payment data from an existing invoice, so only the recurrence has to be described.

  • from_invoice_id: the source invoice. It must belong to the company in the path, and one you cannot reach is reported the same way as one that does not exist. It is not modified by this call.

  • Recurrence: name, day_of_month and start_date are required; end_date and frequency are optional. The cadence is not taken from the source invoice — a one-off invoice has none to copy — so it is described here like any other recurrence field: every 1 (MONTHLY), 3 (QUARTERLY) or 12 (YEARLY) months, MONTHLY when omitted. It governs the step from the first invoice onwards, not where that first one lands.

  • VeriFactu: not inherited from the source invoice. Each generated invoice is registered with AEAT, or not, according to the company's regime when it is issued.

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

⚠️ Read before calling:

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

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_recurring_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. Changed2 schema fields changedv0.10.0
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / start_date / description
      Previous value: -"Date the subscription started. A past date is accepted and stored as sent — useful\nwhen migrating subscriptions from another system — but it never anchors generation\nin the past. `next_generation` becomes the next date of the template's own calendar\nthat is still ahead: the grid of `day_of_month` dates anchored at `start_date`, one\nevery `frequency`. On a quarterly or yearly template that can be months from now, not\nthis month. Invoices are never back-dated, so the missed periods are not generated.\n"New value: +"Date the subscription started. A past date is accepted and stored as sent — useful\nwhen migrating subscriptions from another system — but it never anchors generation\nin the past. `next_generation` becomes the first date of the template's own calendar\non or after today (today included): the grid of `day_of_month` dates anchored at\n`start_date`, one every `frequency`. On a quarterly or yearly template that can be\nmonths from now, not this month. Invoices are never back-dated, so the missed periods\nare not generated. If today's period was already invoiced in the system you are\nmigrating from, send a `start_date` of tomorrow (or of the next period) so it is not\ninvoiced twice.\n"
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. Changed13 schema fields changedv0.9.0
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / day_of_month / description
      Added value: +"Day of the month the invoices are issued. A month that does not have that day falls\nback to its last day: a template on `31` issues on 28 February (29 in a leap year)\nand on 30 April. So `31` is how you ask for the last day of the month it generates\nin — there is no separate flag for it, and the accepted range stays 1–31.\n\nThe adjustment does not stick and the schedule does not drift: every generation is\nrecalculated from the `day_of_month` you sent, never from the date it was adjusted\nto (31 Jan → 28 Feb → 31 Mar).\n"
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / draft_in_advance
      Added value: +{
      +  "description": "Whether the template prepares a draft for review before emitting. The window is fixed at\n5 days and both options emit on the scheduled day. Omitted, the template is created\nwithout the review draft. Same field, same meaning and same default as when you create a\ntemplate from scratch: deriving from an invoice does not give it a second semantics.\n",
      +  "type": "boolean"
      +}
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / frequency / description
      Previous value: -"Generation cadence. Only `MONTHLY` is supported today; the field exists in the\nrequest so an unsupported cadence is rejected instead of silently creating a\nmonthly template. Omitted, `MONTHLY` applies.\n"New value: +"Generation cadence: `MONTHLY` every month, `QUARTERLY` every 3 months, `YEARLY` every 12 months. Omitted, `MONTHLY` applies.\n\nIt governs the step from the first invoice onwards, not where that first one lands: the\nfirst occurrence is the first `day_of_month` on or after `start_date`, found one month at\na time whatever the cadence. A yearly template starting 15 February with `day_of_month`\n10 first invoices on 10 March, then every 10 March after that — it does not wait a year.\n"
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / frequency / enum
      Previous value: -[
      -  "MONTHLY"
      -]New value: +[
      +  "MONTHLY",
      +  "QUARTERLY",
      +  "YEARLY"
      +]
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / name / minLength
      Added value: +1
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / name / pattern
      Added value: +"^\\S.*$"
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / start_date / description
      Previous value: -"Date the subscription started. A past date is accepted and stored as sent — useful\nwhen migrating subscriptions from another system — but it never anchors generation\nin the past: `next_generation` moves to the first upcoming `day_of_month`. Invoices\nare never back-dated, so the missed periods are not generated.\n"New value: +"Date the subscription started. A past date is accepted and stored as sent — useful\nwhen migrating subscriptions from another system — but it never anchors generation\nin the past. `next_generation` becomes the next date of the template's own calendar\nthat is still ahead: the grid of `day_of_month` dates anchored at `start_date`, one\nevery `frequency`. On a quarterly or yearly template that can be months from now, not\nthis month. Invoices are never back-dated, so the missed periods are not generated.\n"
    • removedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / verifactu_enabled
      Removed value: -{
      -  "description": "Whether the invoices this template generates enter VeriFactu.\n\nOmitting it inherits the value from the source invoice: pointing at one of your\nVeriFactu invoices and asking for it every month keeps VeriFactu. Send `true` or\n`false` explicitly to override that inheritance.\n",
      -  "type": "boolean"
      -}
    • addedInput schema / $defs / Email
      Added value: +{
      +  "description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)",
      +  "format": "email",
      +  "maxLength": 255,
      +  "minLength": 5,
      +  "type": "string"
      +}
    • addedInput schema / $defs / RecurringEmailConfigRequest / properties / cc / items / $ref
      Added value: +"#/$defs/Email"
    • removedInput schema / $defs / RecurringEmailConfigRequest / properties / cc / items / type
      Removed value: -"string"
    • addedInput schema / $defs / RecurringEmailConfigRequest / properties / recipients / items / $ref
      Added value: +"#/$defs/Email"
    • removedInput schema / $defs / RecurringEmailConfigRequest / properties / recipients / items / type
      Removed value: -"string"
  3. Changed3 schema fields changedv0.5.0
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / additionalProperties
      Added value: +false
    • 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."
  4. First observedv0.3.1

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare write/destructive/idempotent/openWorld, so the bar is lower; the description still adds substantive behavior: the source invoice is not modified, an unreachable invoice is reported identically to a non-existent one (deliberate information hiding), and AEAT registration is decided by the company's regime at issuance rather than inherited. It does not discuss the response payload or what the created template exposes afterwards.

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-loaded with a single defining sentence, then clean bulleted sections for source invoice, recurrence, and VeriFactu, followed by the guardrails pointer. Some content overlaps the schema text, but every block is scannable and none is 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 derived-template creation with a nested body, no output schema, and destructive semantics, the description covers source requirements, recurrence semantics, and fiscal side effects well. The remaining gap is the result: it never says what comes back (template id, computed next_generation), and sibling routing is only implicit.

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

Parameters3/5

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

Schema coverage is a moderate 67% and the three top-level parameters (company_id, body, idempotency_key) are already well documented in the schema with the same wording the description reuses. The description usefully restates which recurrence fields are required vs. optional and how frequency maps to months, but that duplicates the schema's own field descriptions rather than adding new meaning.

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 recurring invoice template') plus the distinguishing mechanism ('taking its lines, recipient, series and payment data from an existing invoice, so only the recurrence has to be described'). That clause alone separates it from beel_create_recurring_invoice, which builds a template from scratch and must supply series/lines.

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 real preconditions — the source invoice must belong to the company in the path, the cadence is deliberately not copied, VeriFactu is not inherited — and a 'Read before calling' pointer to beel_rules_list for fiscal guardrails. It stops short of an explicit routing statement naming the from-scratch sibling as the alternative when no suitable source invoice exists.

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