Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_create_series

Idempotent

Creates an invoice series for a company with a document type, unique code, and numbering format to organize and number invoices.

Instructions

Creates an invoice series under a company.

  • Document type: document_type is required. UNASSIGNED is rejected with 422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED: corrective invoices need a series of their own.

  • Code: must be unique within the company; a code already taken answers 409.

  • Unique numbers per issuer: a series whose code and format could print a number that another series of the company (in the same environment, active or not) can also print is rejected with 409 SERIES_FORMAT_OVERLAPS, naming that series. Proforma series are not compared.

  • Numbering: format must contain {NUM} or {NUM:X} and only accepts uppercase tokens. counter_reset defaults to ANNUAL, so a format with no year token has to be sent with counter_reset: NEVER.

  • Default series: the first series created for a document type is marked as default even if you send default_series: false.

BeeL API endpoint: POST /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>",
      "body": "<body>"
    },
    "name": "beel_create_series"
  }
}

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.
idempotency_keyNoOptional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.10.0
    • 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 / body / type
      Added value: +"object"
  2. Changed5 schema fields changedv0.9.0
    • addedInput schema / $defs / CreateSeriesRequest / description
      Added value: +"Request to create an invoice series. `document_type` is required: a new series always has\na type, and `UNASSIGNED` is rejected with `422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`.\nCorrective invoices need a series of their own (`CORRECTIVE`).\n"
    • changedInput schema / $defs / CreateSeriesRequest / properties / initial_number / description
      Previous value: -"Initial number for this series counter.\nUseful when migrating from another system and wanting to continue existing numbering.\nFor example, if the last invoices were 2024-0150, you can set initial_number=151.\nDefault value is 1.\n"New value: +"Initial number for this series counter.\nUseful when migrating from another system and wanting to continue existing numbering.\nFor example, if the last invoices were 2024-0150, you can set initial_number=151.\nDefault value is 1.\nIt applies only to the first period in which the series issues an invoice: with\n`counter_reset: ANNUAL` or `MONTHLY`, every later year or month starts at 1. With\n`NEVER` there is a single period, so numbering simply continues from it.\n"
    • changedInput schema / $defs / CreateSeriesRequest / required
      Previous value: -[
      -  "name",
      -  "code",
      -  "format"
      -]New value: +[
      +  "document_type",
      +  "name",
      +  "code",
      +  "format"
      +]
    • 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 / $defs / SeriesFormat / description
      Previous value: -"Format template with available variables (UPPERCASE ONLY):\n- {CODIGO}: Series code (e.g., \"FAC\")\n- {YYYY}: Year with 4 digits (e.g., \"2025\")\n- {YY}: Year with 2 digits (e.g., \"25\")\n- {MM}: Month with 2 digits (e.g., \"01\")\n- {NUM}: Sequential number without padding (e.g., \"1\")\n- {NUM:X}: Sequential number with padding (e.g., {NUM:4} → \"0001\")\n\n**REQUIRED**: Must contain at least {NUM} or {NUM:X}\n**IMPORTANT**: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)\n\nValid examples:\n- \"{CODIGO}-{YYYY}-{NUM:4}\" → \"FAC-2025-0001\"\n- \"{CODIGO}/{NUM:6}\" → \"FAC/000001\"\n- \"{YYYY}{MM}-{NUM:3}\" → \"202501-001\"\n"New value: +"Format template with available variables (UPPERCASE ONLY):\n- {CODIGO}: Series code (e.g., \"FAC\")\n- {YYYY}: Year with 4 digits (e.g., \"2025\")\n- {YY}: Year with 2 digits (e.g., \"25\")\n- {MM}: Month with 2 digits (e.g., \"01\")\n- {NUM}: Sequential number without padding (e.g., \"1\")\n- {NUM:X}: Sequential number with padding (e.g., {NUM:4} → \"0001\")\n\n**REQUIRED**: Must contain at least {NUM} or {NUM:X}\n**IMPORTANT**: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)\n\nValid examples:\n- \"{CODIGO}-{YYYY}-{NUM:4}\" → \"FAC-2025-0001\"\n- \"{CODIGO}/{NUM:6}\" → \"FAC/000001\"\n- \"{YYYY}{MM}-{NUM:3}\" → \"202501-001\"\n\nThe generated number is the invoice number sent to the AEAT, which accepts at most 60\nprintable ASCII characters and none of `\"`, `'`, `<`, `>`, `=`. A format whose longest\npossible number breaks that rule is rejected with `422 SERIES_FORMAT_NUMBER_TOO_LONG` or\n`SERIES_FORMAT_INVALID_CHARACTERS`. The counter counts as at least 9 digits, with or without\npadding: `{NUM:X}` is a minimum width, not a maximum.\n"
  3. Changed8 schema fields changedv0.5.0
    • addedInput schema / $defs / CreateSeriesRequest / additionalProperties
      Added value: +false
    • removedInput schema / $defs / CreateSeriesRequest / properties / description / example
      Removed value: -"Series for standard invoices"
    • removedInput schema / $defs / CreateSeriesRequest / properties / initial_number / example
      Removed value: -1
    • removedInput schema / $defs / CreateSeriesRequest / 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}"
    • 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?

Annotations only declare the CRUD/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true); the description goes well beyond by naming concrete rejection modes (409 SERIES_FORMAT_OVERLAPS, 422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED, 409 duplicate code) and the cross-series uniqueness rule. It also discloses a non-obvious side effect: the first series of a document type becomes default even if default_series=false. That is exactly the behavior an agent cannot infer from annotations.

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 core action, then scannable bolded bullets keyed to parameters and failure modes, followed by prerequisites. Every bullet carries a distinct rule, but a few restate what the input schema already says about counter_reset and default_series, adding some redundancy.

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 create-mutation with nested request bodies and no output schema, the description covers validation rules, uniqueness collisions and default-series side effects, and it routes the agent to guardrail resources. It never says what the successful response contains (created series id/fields), which matters more here because no output schema exists.

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 schema is already verbose, but the description adds cross-parameter meaning rather than repeating definitions: format must contain {NUM}/{NUM:X}, and because counter_reset defaults to ANNUAL, a format without a year token must be sent with counter_reset: NEVER. It also explains default_series auto-promotion and the code-uniqueness constraint. Some of this duplicates the schema's own field descriptions, which keeps it from a 5.

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 line gives a specific verb and resource ('Creates an invoice series under a company'), and the following bullets pin down exactly what a series is in this domain (document_type, code, format, numbering). An agent can distinguish this from beel_list_series, beel_patch_series, beel_delete_series and beel_set_default_series without opening any schema.

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 '⚠️ Read before calling' block tells the agent to consult beel_rules_list with a domain or the beel://guardrails/series-and-numbering resource first, which is real, actionable when-to-use guidance. It also states preconditions (a corrective invoice needs its own series). It stops short of naming sibling tools for the modify/default paths, so it is clear context rather than full alternative routing.

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