Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_generate_recurring_invoice_now

DestructiveIdempotent

Generate a recurring invoice now, outside its schedule, by consuming the pending occurrence and advancing the template's next generation date.

Instructions

Runs the generation of this recurring template immediately, out of its schedule. It is a fiscal act: the generated invoice consumes numbering from the series of the template and, when the template says so, is issued and sent.

  • It brings the upcoming occurrence forward, it does not add one: the call consumes the period that was pending, so the invoice is created now and next_generation advances one period. Generating manually, skipping and letting the schedule run each consume exactly one occurrence, so a monthly template still produces twelve invoices a year however you mix the three.

  • next_generation in the response: the template's next date after this call consumed the pending occurrence, or null when the advance took the template past its end_date and its status is now COMPLETED.

  • An extra invoice outside the calendar: do not use this endpoint. Create a normal invoice, or derive a draft from one the template already generated with POST /v1/companies/{company_id}/invoices/derivations. Either way the schedule stays where it was.

Endpoint: POST /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/generate

⚠️ Read before calling:

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
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.
recurring_invoice_idYesUnique identifier (UUID) of the recurring invoice template, as returned when it is created or listed. A template of another company answers `404` with `RECURRING_NOT_FOUND`, exactly like one that does not exist.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.0
    • addedInput schema / properties / recurring_invoice_id / description
      Added value: +"Unique identifier (UUID) of the recurring invoice template, as returned when it is created or listed. A template of another company answers `404` with `RECURRING_NOT_FOUND`, exactly like one that does not exist."
  2. Changed2 schema fields changedv0.5.0
    • 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.7/5.0
Behavior5/5

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

Annotations declare destructiveHint and idempotentHint, and the description adds substantial non-redundant behavior: the call is a fiscal act that consumes numbering from the template's series, issues and sends the invoice when the template is configured to, advances next_generation one period, and may flip status to COMPLETED past end_date. This is context an agent cannot get from the annotations alone.

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

Conciseness5/5

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

Front-loaded with the core action, then bolded, scannable bullets that each carry distinct information (occurrence economics, response semantics, the do-not-use case, endpoint path, fiscal-rules pointer). No filler sentences.

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

Completeness5/5

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

For a destructive, no-output-schema fiscal mutation, the description supplies everything needed: the fiscal/numbering consequence, the occurrence accounting, the return field (next_generation incl. null case), the mis-use case, and a pointer to beel_rules_list/guardrails. Nothing material is missing.

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 description coverage is 100%, so company_id, recurring_invoice_id, and idempotency_key are already fully documented in the schema. The description references next_generation but that is a response field, not a parameter, so it adds no parameter-level semantics beyond the schema. Baseline 3 applies.

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 precise verb+resource+scope: it runs the recurring template's generation immediately, out of schedule, and explicitly frames it as consuming the pending occurrence ('brings the upcoming occurrence forward, it does not add one'). This distinguishes it cleanly from siblings like beel_skip_recurring_invoice, beel_create_recurring_invoice_derivation, and beel_create_invoice.

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

Usage Guidelines5/5

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

Gives explicit when-to-use (bring the pending occurrence forward now) and a strong when-NOT: 'An extra invoice outside the calendar: do not use this endpoint,' routing the agent to create a normal invoice or a derivation via POST .../invoices/derivations. It also clarifies how manual generation, skipping, and the schedule interact so the agent understands the alternative paths.

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