BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_ensure_default_series

Idempotent

Ensures a default invoice series exists for STANDARD, SIMPLIFIED, and CORRECTIVE document types and returns the complete set. Missing defaults are created automatically; existing ones remain unchanged.

Instructions

Ensures the company has a default invoice series for STANDARD, SIMPLIFIED and CORRECTIVE in the current environment, and returns the resulting set. The request takes no body: the desired end state is one default per document type, so repeating it changes nothing.

Already there: a document type that already has a default keeps it, and it is returned unchanged.
Missing: it is created with code F, S or R and format {CODIGO}-{YYYY}-{NUM:4}, active and marked as default.
Code taken: if that code already belongs to another series, the document type is omitted from the response and is left with no default.

Closed catalogue. This collection is fixed and bounded — one entry per DocumentType: it carries no pagination, it takes no page/limit, and every response holds the whole set.

BeeL API endpoint: PUT /v1/companies/{company_id}/series/defaults (reference: https://docs.beel.es)

⚠️ Read before calling:

Fiscal rules, domains numbering: beel_rules_list with domain, or resource beel://guardrails/.
How a series formats numbers, and which series configurations are rejected. (resource: beel://guardrails/series-and-numbering)

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>"
    },
    "name": "beel_ensure_default_series"
  }
}

Input Schema

Name	Required	Description	Default
`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.

Changed2 schema fields changedv0.5.0Aug 30, 2026

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

A3.7/5.0

Behavior4/5

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description's repetition note reinforces rather than originates that fact. It goes genuinely beyond the annotations by spelling out the three per-document-type outcomes (kept unchanged, created with code F/S/R and format {CODIGO}-{YYYY}-{NUM:4}, or omitted with no default when the code is taken) — the last case is a non-obvious partial-failure mode an agent must be able to report. Missing are permission/auth expectations and whether the creation is reversible.

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 the action and outcome, then three tight bullets for the branching cases, then a short note on the fixed-size response, then the endpoint. Nearly every sentence earns its place. The 'Closed catalogue' paragraph is slightly over-explained for a single-parameter, non-paginated call, but it does preempt a pagination question.

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?

With no output schema, the description correctly compensates by describing the return set: one entry per DocumentType, no pagination, whole set in every response, and the case where a document type is absent from the response. That is the information an agent needs to interpret results. What is not covered is what the returned entries look like beyond code/format, and any permission requirements for the PUT.

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?

There is only one parameter and its schema description already covers 100% of the semantics, including the 403 behaviour and the header-independence detail. The description contributes the useful framing that the request takes no body and that the desired end state is one default per document type, but adds nothing company_id-specific. Baseline 3 applies when the schema does the heavy lifting.

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?

The description states a concrete verb and resource: ensure a default invoice series exists for STANDARD, SIMPLIFIED and CORRECTIVE, and return the resulting set. The scope is unambiguous. It does not, however, distinguish itself from the similarly named siblings beel_set_default_series and beel_get_default_series, so an agent still has to infer which of the three is the right call.

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

Usage Guidelines3/5

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

Usage context is implied rather than stated: the 'desired end state' framing and the 'repeating it changes nothing' note suggest when this is preferred over a blind create. But the description never names beel_set_default_series as the alternative for pinning a specific series, nor beel_get_default_series for read-only inspection, leaving the most important routing decision to inference. The 'Read before calling' pointers to beel_rules_list and the guardrails resources are useful prerequisites, but they are references, not selection guidance.

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

Deploy Server