BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_create_invoice_batch

DestructiveIdempotent

Apply one operation to up to 50 company invoices at once: issue draft invoices or change their status, with per-invoice success and failure results.

Instructions

Applies one operation to a set of invoices of this company and reports, invoice by invoice, which succeeded and which failed.

Operations: ISSUE issues the draft invoices; STATUS moves them to the new_status given in the body.
Limit: up to 50 invoices per request (invoice_ids).
Not atomic: each invoice is processed on its own, and since issuing is irreversible, the ones already issued stay issued if a later one fails.
Related: downloading PDFs, sending email and exporting are not operations of this batch — use …/invoices/pdf-archive, …/invoices/deliveries and …/invoices/exports.

BeeL API endpoint: POST /v1/companies/{company_id}/invoices/batches (reference: https://docs.beel.es)

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_invoice_batch"
  }
}

Input Schema

Name	Required	Description
`body`	Yes
`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.
`idempotency_key`	No	Optional 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.

Changed1 schema field changedv0.10.0Nov 5, 2026
- addedInput schema / properties / body / type
```
Added value: +"object"
```

Changed5 schema fields changedv0.5.0Aug 30, 2026

addedInput schema / $defs / CreateInvoiceBatchRequest / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / CreateInvoiceBatchRequest / properties / payment_date / example
```
Removed value: -"2025-01-15"
```

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

Behavior5/5

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

On top of annotations that already flag destructiveHint=true and idempotentHint=true, the description adds the behavior that matters most: the operation is not atomic, issuing is irreversible, and partial failures leave already-issued invoices issued. It also discloses the 50-invoice cap and the per-invoice success/failure report shape, which are not derivable from the 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?

The description is front-loaded with the core verb, then organized into bolded bullets for operations, limit, atomicity and related endpoints, so an agent can scan it quickly. The operations bullet largely duplicates the enum descriptions in the schema, which is the only wasted content.

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 compensates by explaining that results are reported invoice by invoice as succeeded/failed, and it covers the mutation's risk profile and size limit. It omits prerequisite conditions such as whether STATUS transitions are validated or which draft states are issuable, but the essentials for calling it correctly are present.

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?

The description restates the ISSUE/STATUS semantics and the 50-item limit that the schema already documents, adding meaning mainly through the non-atomic partial-failure framing. It says nothing about payment_date (required for STATUS to PAID) or idempotency_key, leaving those entirely to the schema, which is consistent with the 67% coverage baseline.

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 gives a specific verb and resource ('Applies one operation to a set of invoices of this company') and enumerates the two supported operations, ISSUE and STATUS, so the agent knows exactly what the tool does. It distinguishes itself from the non-batch alternatives by naming the pdf-archive, deliveries and exports sub-resources, though it never names the single-invoice siblings (beel_issue_invoice, beel_set_invoice_status) that it most closely competes with.

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 context for use: one operation across up to 50 invoice_ids, with an explicit exclusion list for PDF download, email delivery and export, which the agent should route elsewhere. It stops short of stating when a batch is preferable to single-invoice calls, so the choice between this tool and beel_issue_invoice/beel_set_invoice_status is left implicit.

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

Deploy Server