Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_set_recurring_invoice_status

DestructiveIdempotent

Set a recurring invoice template's lifecycle status to pause, resume, or permanently end automatic invoice generation.

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.

BeeL API endpoint: PUT /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/status (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>",
      "recurring_invoice_id": "<recurring_invoice_id>",
      "body": "<body>"
    },
    "name": "beel_set_recurring_invoice_status"
  }
}

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.
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.10.0
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. 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."
  3. 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."
  4. First observedv0.3.1

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the concrete semantics of each transition: PAUSED preserves the schedule, ACTIVE keeps a not-yet-due next date and never backfills missed periods, only a past date is rescheduled, and COMPLETED is terminal and irreversible. It also surfaces the specific rejection error (RECURRING_STATE_TRANSITION_INVALID) and the blocker condition, which annotations cannot express.

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 one-line purpose, then organized as scannable bullets per status value with a separate 'Rejected transitions' item. It is somewhat long for a three-parameter tool and overlaps with the status enum's schema description, but every bullet encodes a distinct state-machine 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 destructive, open-world mutation with no output schema, the description covers the decision-relevant behavior thoroughly, including edge cases and the failure code. Gaps remain minor: it does not state what the call returns, nor does it mention the draft auto-emission-timer side effect (that detail appears only inside the schema's status description) or any authorization prerequisites.

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?

Schema coverage is 67% and the status enum is already documented in the schema, so the baseline is 3; the description earns extra credit by adding transition legality (which source states allow which targets) and the no-backfill/rescheduling rule that the schema does not state for the ACTIVE case. It adds nothing extra about the company_id/recurring_invoice_id parameters beyond their existing schema descriptions, which is acceptable since those are well covered.

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?

The opening sentence names a specific verb and resource ('sets the lifecycle status of a recurring invoice template') and immediately defines the scope of 'status' as pausing, resuming and ending generation. Enumerating PAUSED/ACTIVE/COMPLETED makes it distinguishable from adjacent siblings such as beel_skip_recurring_invoice (skip one occurrence), beel_generate_recurring_invoice_now (force generation) and beel_patch_recurring_invoice (edit configuration).

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?

It gives clear when-to-use guidance per status value, plus explicit when-not conditions: resuming an already-active template, resuming while 'pause.blocker' is in effect, and any transition out of the terminal COMPLETED state. It does not, however, route the agent to alternative tools for related tasks (skipping a single occurrence, generating immediately, or deleting the template), so the alternative-naming part of the criterion is missing.

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