Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_set_recurring_invoice_status

Idempotent

Pause, resume, or end automatic invoice generation by setting a recurring template's status to ACTIVE, PAUSED, or COMPLETED.

Instructions

Sets the lifecycle status of a recurring invoice template. This is how generation is paused, resumed and ended.

  • PAUSED: stops automatic generation, keeping the schedule configuration intact.

  • ACTIVE: resumes generation. It keeps the scheduled next generation date whenever that date has not fallen due yet (including today), so resuming never re-issues a period you already invoiced and never undoes a skipped one. Only a date left in the past is rescheduled, to the first occurrence after today; the periods missed while the template was paused are not backfilled. If nothing is left to generate — the next generation date falls beyond end_date, or max_invoices has already been reached — the template becomes COMPLETED; for end_date that holds whether the date was kept or rescheduled.

  • COMPLETED: ends the schedule for good, from ACTIVE or PAUSED; it is also reached on its own when the schedule runs out. It is terminal: ACTIVE and PAUSED are then rejected with RECURRING_STATE_TRANSITION_INVALID.

  • Rejected transitions: resuming a template that is already active, or one whose pause.blocker is still in effect.

Endpoint: PUT /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/status

⚠️ Read before calling:

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

Input Schema

TableJSON 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.
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. Changed3 schema fields changedv0.9.0
    • changedInput schema / $defs / SetRecurringInvoiceStatusRequest / properties / status / description
      Previous value: -"Target status. `PAUSED` stops automatic generation keeping the schedule; `ACTIVE`\nresumes it and recalculates the next generation date from today.\n"New value: +"Target status. `PAUSED` stops automatic generation keeping the schedule; `ACTIVE`\nresumes it and keeps the scheduled next generation date whenever that date has not fallen\ndue yet (including today), rescheduling only a date left in the past to the first\noccurrence after today; `COMPLETED` ends the schedule for good — valid from both `ACTIVE`\nand `PAUSED`.\n\n`COMPLETED` is terminal: once there, `ACTIVE` and `PAUSED` are rejected with\n`RECURRING_STATE_TRANSITION_INVALID`. Ending also disarms the auto-emission timer of any\ndraft this schedule had seeded; those drafts stay alive as regular drafts.\n"
    • changedInput schema / $defs / SetRecurringInvoiceStatusRequest / properties / status / enum
      Previous value: -[
-  "ACTIVE",
-  "PAUSED"
-]New value: +[
+  "ACTIVE",
+  "PAUSED",
+  "COMPLETED"
+]
    • 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. Changed4 schema fields changedv0.5.0
    • addedInput schema / $defs / SetRecurringInvoiceStatusRequest / additionalProperties
      Added value: +false
    • removedInput schema / $defs / SetRecurringInvoiceStatusRequest / properties / status / example
      Removed value: -"PAUSED"
    • 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.1/5.0
Behavior5/5

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

Goes well beyond the annotations: it states that COMPLETED is terminal and surfaces the exact error code (RECURRING_STATE_TRANSITION_INVALID), that missed periods are never backfilled, that a past next-generation date is rescheduled but a future/today one is kept, and that COMPLETED disarms seeded draft timers while leaving the drafts alive. This is exactly the side-effect detail an agent needs for an idempotent-but-stateful mutation.

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 purpose, then uses scannable bullets per status value, and follows with endpoint plus a guardrails pointer. The bullets are verbose, but each sentence conveys a distinct transition rule rather than 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 stateful mutation with no output schema, it covers transition validity, terminal state, error codes, side effects on seeded drafts, and routes to beel_rules_list for fiscal guardrails. It omits any mention of the response payload or required permissions, leaving a minor gap.

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 67% and the status parameter's schema text already restates the transition semantics, so the description largely duplicates structured data rather than adding new meaning. Baseline 3 is appropriate when the schema carries most of the parameter burden.

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

Purpose4/5

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

Names a specific verb and resource: setting the lifecycle status of a recurring invoice template, and immediately frames why (pausing, resuming, ending generation). This clearly separates it from sibling mutations like beel_patch_recurring_invoice or beel_delete_recurring_invoice, though it never names a sibling explicitly.

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 rich per-value guidance on when each status applies and which transitions are rejected (already-active resume, pause.blocker in effect). It does not, however, point the agent at adjacent tools such as beel_skip_recurring_invoice or beel_generate_recurring_invoice_now, which are the natural alternatives for one-off actions.

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