BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_generate_payment_event_draft

Idempotent

Builds a draft invoice from an unbilled payment event, applying the same recipient resolution and tax rules as the automatic flow so you can review and issue it yourself.

Instructions

Builds a draft invoice from a payment event that could not be invoiced automatically, applying the same recipient resolution and tax treatment the automatic flow would have applied, under the NIF in the path.

Draft only: the document is not issued, not numbered against the series and not emailed. Issue it yourself once it is right.
Eligible events: only those that produced no invoice can produce a draft; otherwise the request returns 400.
Rejected documents: if invoicing rules reject the resulting document the request returns 422 and no draft is created.

BeeL API endpoint: POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/draft (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>",
      "connection_id": "<connection_id>",
      "event_id": "<event_id>"
    },
    "name": "beel_generate_payment_event_draft"
  }
}

Input Schema

Name	Required	Description
`event_id`	Yes	Identifier of the payment event, as returned by the list operation.
`company_id`	Yes	Unique identifier (UUID) of the company the events belong to — 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.
`connection_id`	Yes	Unique identifier (UUID) of the payment connection the operation acts on, as returned by `GET /v1/companies/{company_id}/payment-connections`. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers `404`, exactly like one that does not exist.
`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.

Changed3 schema fields changedv0.9.0Oct 1, 2026

addedInput schema / properties / connection_id

Added value: +{
+  "description": "Unique identifier (UUID) of the payment connection the operation acts on, as returned by `GET /v1/companies/{company_id}/payment-connections`. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers `404`, exactly like one that does not exist.",
+  "format": "uuid",
+  "type": "string"
+}

removedInput schema / properties / provider

Removed value: -{
-  "description": "Payment provider slug in **lowercase**. Currently only `stripe` (Stripe Connect) is\noperative; `woocommerce` and `shopify` are reserved for future providers.\n",
-  "enum": [
-    "stripe"
-  ],
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "company_id",
-  "provider",
-  "event_id"
-]New value: +[
+  "company_id",
+  "connection_id",
+  "event_id"
+]

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 events belong to. 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 events belong to — 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.4/5.0

Behavior5/5

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

Annotations already declare idempotentHint=true, readOnlyHint=false and destructiveHint=false, and the description goes well beyond them: it spells out that the document is not issued, not numbered against the series and not emailed, and it maps failure modes to status codes (400 for an already-invoiced event, 422 for a document rejected by invoicing rules, with no draft created). That is exactly the mutation-safety context an agent needs before calling a create-style tool.

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 purpose is front-loaded in the opening sentence and the three bullets each earn their place by covering draft status, eligibility and rejection handling. The trailing endpoint/reference line is useful for traceability. Slightly long overall, but no sentence is 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?

There is no output schema, yet the description covers what matters for the caller: what is produced (an un-issued, un-numbered draft), what is not produced (no email send), and what errors to expect. Combined with annotations that already carry the idempotency and safety profile, nothing essential is missing for correct invocation.

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 coverage is 100%, so all four parameters — including the subtle idempotency-key collapsing behavior — are already documented in the schema, and the description adds little per-parameter meaning. The one phrase it does add, 'under the NIF in the path', is actually in tension with the schema's note that company_id is the identifier and 'not its NIF', which sows mild confusion rather than resolving it. Baseline 3 fits: the schema carries the parameter burden.

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 first sentence names a specific verb and resource ('builds a draft invoice') and scopes the input precisely to 'a payment event that could not be invoiced automatically', which separates it from beel_create_invoice, beel_issue_invoice and beel_retry_payment_event. It also states what the automatic flow would have applied (recipient resolution, tax treatment), so the agent knows this is a replay of existing rules rather than a fresh manual invoice.

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 an explicit eligibility gate ('only those that produced no invoice can produce a draft') and an explicit follow-up alternative ('Issue it yourself once it is right'), which points the agent at beel_issue_invoice for the next step. What it does not do is name the recovery siblings it should be preferred over — beel_retry_payment_event, beel_resolve_payment_event, beel_discard_payment_event — so the routing decision among those is left to inference.

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

Deploy Server