BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_patch_series

Partially update an invoice series: only fields sent in the body change, the rest stay as-is. Use null to clear the description; numbering fields lock after invoices are issued.

Instructions

Updates only the fields present in the body, leaving every other field of the series as it is.

Clearing a field: a field sent as null is cleared, which only description supports.
Numbering fields: code, format, counter_reset and initial_number are rejected once the series has issued invoices (numbering_locked is true).
default_series: it cannot be used to clear the default. Sending false for the series that currently is the default answers DEFAULT_CANNOT_BE_UNMARKED, because it would leave the document type with active series and no default, and issuing without an explicit series_id would then fail with SERIES_DEFAULT_NOT_FOUND. Hand the default over with PUT /v1/companies/{company_id}/series/{series_id}/default on the new series, which unmarks the previous one. Sending false for a series that is not the default is a no-op.

Endpoint: PATCH /v1/companies/{company_id}/series/{series_id}

⚠️ Fiscal guardrails — read before calling:

How invoice numbers are formed, and why numbering can never be rewritten. (resource: beel://guardrails/series-and-numbering)

For the exhaustive rules and worked examples, call beel_docs_search.

Input Schema

TableJSON Schema

Name	Required	Description
`body`	Yes
`series_id`	Yes	Series ID
`company_id`	Yes	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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.5.0Aug 30, 2026

addedInput schema / $defs / PatchSeriesRequest / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / PatchSeriesRequest / properties / description / example
```
Removed value: -"Series for standard invoices"
```
removedInput schema / $defs / PatchSeriesRequest / properties / initial_number / example
```
Removed value: -54
```
removedInput schema / $defs / PatchSeriesRequest / properties / name / example
```
Removed value: -"Main Series"
```
removedInput schema / $defs / SeriesCode / example
```
Removed value: -"FAC"
```
removedInput schema / $defs / SeriesFormat / example
```
Removed value: -"{CODIGO}-{YYYY}-{NUM:4}"
```

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."

First observedv0.3.1Aug 25, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description goes far beyond the annotations by explaining field-level PATCH semantics: omitted fields are kept, null clears only description, numbering fields are rejected once numbering_locked is true, and default_series=false errors with DEFAULT_CANNOT_BE_UNMARKED when applied to the current default. It even explains the downstream failure mode (SERIES_DEFAULT_NOT_FOUND) and the no-op case for non-default series. This is exemplary disclosure of non-obvious behavior.

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?

The description is long, but every section earns its place: core semantics, clearing rules, numbering restrictions, default_series edge cases, endpoint, fiscal guardrail, and pointer to deeper docs. Bullets and bolded headers make it scannable, and the most important behavioral rule is front-loaded in the first sentence. Nothing feels like filler.

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 PATCH tool with multiple non-obvious constraints, the description is remarkably complete. It covers partial-update behavior, null handling, numbering locks, default_series pitfalls, the exact alternative endpoint, and a safety-guardrail resource. Since there is no output schema, the agent still gets enough context to invoke the call correctly and avoid the most likely errors.

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 moderate at 67%, with company_id and body already richly described in the schema. The description adds critical parameter-level semantics not fully captured there: the default_series clearing restriction, the behavior of false on non-default series, and the specific fields rejected after invoices are issued. It does not redundantly re-explain every parameter, but it highlights the ones most likely to cause errors.

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 description opens with a precise, scoped statement: 'Updates only the fields present in the body, leaving every other field of the series as it is.' This names the operation (PATCH) and resource (series) while distinguishing it from full updates, creating series, or deleting series. Sibling tools like beel_create_series, beel_delete_series, and beel_set_default_series are clearly set apart by the partial-update framing.

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?

The description provides explicit context on when this tool is appropriate: partial updates, and it details the important exception for default_series, pointing to the alternative default-handover endpoint (PUT /v1/companies/{company_id}/series/{series_id}/default). It also tells the agent to consult beel_docs_search for exhaustive rules and worked examples. It stops short of a full when-to-use/when-not-to-use matrix against every sibling, but the guidance is clear and actionable.

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

Deploy Server

beel_patch_series

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools