Skip to main content
Glama
Sign In
BeeL MCP server

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_patch_invoice_schedule

Destructive

Update only the fields sent for an already scheduled invoice, changing its scheduled date or generation mode; it never creates a schedule and returns 404 if the invoice is not scheduled.

Instructions

Updates only the fields present in the body of the scheduling of an invoice that is already SCHEDULED — same convention as PATCH …/{invoice_id} on the invoice itself. Unlike the PUT, this never creates a scheduling: an invoice that is not scheduled answers 404, it is not programmed by this call.

  • scheduled_for: moves the date. If generation_mode is not sent, the mode already scheduled is kept.

  • generation_mode: changes the mode. If scheduled_for is not sent, the date already scheduled is kept.

  • At least one of the two fields is required; an empty body is rejected with 422.

  • Availability: requires the scheduled_invoices feature, same as the PUT.

BeeL API endpoint: PATCH /v1/companies/{company_id}/invoices/{invoice_id}/schedule (reference: https://docs.beel.es)

⚠️ Read before calling:

  • Fiscal rules, domains lifecycle: beel_rules_list with domain, or resource beel://guardrails/.

  • The status names, the proforma lifecycle, and which tool performs each operation. (resource: beel://guardrails/invoice-state-machine)

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.
invoice_idYesInvoice ID

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.10.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real substance on top: partial-update semantics where an omitted field keeps its current value, no implicit creation, and explicit error codes (404, 422 SCHEDULED_DATE_IN_PAST). It stops short of describing the response body or any confirmation/audit side effects of moving a scheduled invoice.

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 PATCH semantic, then bulleted per-field rules and availability, so a caller can scan it. It is heavier than needed: the endpoint URL, docs link, and the multi-line guardrail preamble add bulk that isn't about this call's contract.

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 mutation with three required params, a nested body, and no output schema, the description covers preconditions, per-field semantics, validation failures, and the feature-flag dependency. The one gap is the return payload — nothing tells the agent what the updated scheduling looks like after a successful PATCH.

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?

Beyond the 67%-covered schema it explains the interaction between the two body fields — sending only `scheduled_for` keeps the existing `generation_mode` and vice versa — which is the non-obvious behavior an agent needs. The date-in-past rule largely repeats the schema's own `scheduled_for` description, and `company_id`/`invoice_id` semantics are left to the schema.

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?

It names a specific verb (partial update) and resource (an invoice's existing scheduling) and pins the precondition that the invoice is already `SCHEDULED`. It explicitly contrasts itself with the sibling `PUT` (beel_set_invoice_schedule), so an agent can pick between them without opening either schema.

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

Usage Guidelines5/5

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

It states when to use this over the alternative ('Unlike the `PUT`, this never creates a scheduling'), what happens when the precondition fails (404), and the validation rules (at least one field, empty body → 422). It also routes the agent to guardrail resources for fiscal rules and the invoice state machine.

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