BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_list_series

Read-onlyIdempotent

Retrieve a company's invoice series, filtered by active status or document type, with optional pagination. Get the full list when no page or limit is set.

Instructions

Returns the invoice series of a company.

Filters: active restricts to active or inactive series — omit it and you get all of them. document_type returns the series of that type, the only ones that can number it.
Pagination (opt-in): send page and/or limit to receive a single page plus a data.pagination block with the totals. Omit both and the response carries the full list in data.series and no pagination block.

BeeL API endpoint: GET /v1/companies/{company_id}/series (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_list_series"
  }
}

Input Schema

Name	Required	Description
`page`	No	Page number (starts at 1). Omit for the full, unpaginated list.
`limit`	No	Items per page. Omit for the full, unpaginated list.
`active`	No	Filters by activity: `true` returns only active series, `false` only inactive ones. Omit it and you get all the series, active and inactive.
`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.
`document_type`	No	Filter by document type

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.10.0Nov 5, 2026

changedInput schema / $defs / DocumentType / description

Previous value: -"Document type associated with a series. Values mirror `InvoiceType`,\nso the series a document needs is named exactly like the document:\n- UNASSIGNED: Legacy value of series created before types existed. A series numbers only\n  documents of its own type, so an `UNASSIGNED` series numbers none\n  (`422 SERIES_INCOMPATIBLE_DOC_TYPE`); give it a type to keep using it. No series can be\n  created with it or moved to it (`422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`). The live\n  ones were given the type they numbered most.\n- STANDARD: Standard invoice\n- SIMPLIFIED: Simplified invoice\n- CORRECTIVE: Corrects or cancels a previous invoice\n- PROFORMA: Proforma (commercial document, non-fiscal numbering)\n"New value: +"Document type associated with a series. Values mirror `InvoiceType`,\nso the series a document needs is named exactly like the document:\n- UNASSIGNED: Legacy value of series created before types existed. A series numbers only\n  documents of its own type, so an `UNASSIGNED` series numbers none\n  (`422 SERIES_INCOMPATIBLE_DOC_TYPE`); give it a type to keep using it. No series can be\n  created with it or moved to it (`422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`). The live\n  ones were given the type they numbered most.\n- STANDARD: Standard invoice\n- SIMPLIFIED: Simplified invoice\n- CORRECTIVE: Corrects or cancels a previous standard invoice (R1–R4)\n- SIMPLIFIED_CORRECTIVE: Corrects a simplified invoice (R5). Spanish law requires R5 to be\n  numbered apart from R1–R4, so they have a series type of their own\n- PROFORMA: Proforma (commercial document, non-fiscal numbering)\n"

changedInput schema / $defs / DocumentType / enum

Previous value: -[
-  "UNASSIGNED",
-  "STANDARD",
-  "SIMPLIFIED",
-  "CORRECTIVE",
-  "PROFORMA"
-]New value: +[
+  "UNASSIGNED",
+  "STANDARD",
+  "SIMPLIFIED",
+  "CORRECTIVE",
+  "SIMPLIFIED_CORRECTIVE",
+  "PROFORMA"
+]

addedInput schema / properties / document_type / type
```
Added value: +"string"
```

Changed2 schema fields changedv0.9.0Oct 1, 2026

changedInput schema / $defs / DocumentType / description

Previous value: -"Document type associated with a series. Values mirror `InvoiceType`,\nso the series a document needs is named exactly like the document:\n- UNASSIGNED: Legacy series, compatible with any invoice type\n- STANDARD: Standard invoice\n- SIMPLIFIED: Simplified invoice\n- CORRECTIVE: Corrects or cancels a previous invoice\n- PROFORMA: Proforma (commercial document, non-fiscal numbering)\n"New value: +"Document type associated with a series. Values mirror `InvoiceType`,\nso the series a document needs is named exactly like the document:\n- UNASSIGNED: Legacy value of series created before types existed. A series numbers only\n  documents of its own type, so an `UNASSIGNED` series numbers none\n  (`422 SERIES_INCOMPATIBLE_DOC_TYPE`); give it a type to keep using it. No series can be\n  created with it or moved to it (`422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`). The live\n  ones were given the type they numbered most.\n- STANDARD: Standard invoice\n- SIMPLIFIED: Simplified invoice\n- CORRECTIVE: Corrects or cancels a previous invoice\n- PROFORMA: Proforma (commercial document, non-fiscal numbering)\n"

changedInput schema / properties / document_type / description

Previous value: -"Filter by document type (UNASSIGNED series are always included)"New value: +"Filter by document type"

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.9/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the response shape changes with pagination (data.pagination appears only when page/limit are sent, otherwise data.series carries everything), and it points to the error semantics documented in the enum (e.g. 422 SERIES_INCOMPATIBLE_DOC_TYPE).

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 purpose sentence, then tight bulleted sections for filters, pagination and prerequisites, with the warning block last. Minor redundancy: the active filter's omit-behavior is stated in both the description and its schema entry.

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?

No output schema exists, so the description rightly explains the two possible response shapes. Combined with a fully documented 5-parameter schema and guardrail pointers, an agent has enough to call this correctly; only item ordering and series field contents are left implicit.

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 every parameter — including the richly documented DocumentType enum and company_id's 403 behavior — is already explained in the schema. The description repeats the active-filter and pagination semantics that the schema states, adding only the response-shape consequence rather than new parameter meaning.

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 first sentence states a specific verb and resource: 'Returns the invoice series of a company,' and adds the concrete endpoint GET /v1/companies/{company_id}/series. It is clearly a list operation distinct from beel_get_series or beel_create_series, though it never names those siblings 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 clear when-to-use context for the filters and an explicit opt-in pagination rule ('omit both and you get the full list'), plus a 'Read before calling' block routing the agent to beel_rules_list and beel://guardrails/series-and-numbering for fiscal/numbering rules. It stops short of stating when to prefer beel_get_series or beel_get_default_series instead.

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

Deploy Server