Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_update_invoice_customization

DestructiveIdempotent

Update how a company's invoices are rendered and delivered: PDF template, accent colour, invoice and email language. Changes apply to future invoices only.

Instructions

Updates how the invoices of a company are rendered and delivered: PDF template, accent colour, invoice language and email language. Only the properties present in the request body are modified, and the logo is managed through the logo sub-resource.

The change applies to invoices rendered after it and does not alter already issued documents.

BeeL API endpoint: PUT /v1/companies/{company_id}/invoice-customization (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_update_invoice_customization"
  }
}

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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. Changed1 schema field changedv0.9.0
    • changedInput schema / $defs / Language / description
      Previous value: -"Supported languages"New value: +"Supported languages: `es` Spanish, `en` English, `ca` Catalan.\n"
  3. Changed11 schema fields changedv0.5.0
    • removedInput schema / $defs / InvoiceTemplateType / example
      Removed value: -"MODERN_TABLE"
    • removedInput schema / $defs / Language / example
      Removed value: -"es"
    • addedInput schema / $defs / UpdateInvoiceCustomizationRequest / additionalProperties
      Added value: +false
    • changedInput schema / $defs / UpdateInvoiceCustomizationRequest / properties / email_language / allOf
      Previous value: -[
      -  {
      -    "$ref": "#/$defs/Language"
      -  },
      -  {
      -    "description": "Language used for the emails that deliver the invoice."
      -  }
      -]New value: +[
      +  {
      +    "$ref": "#/$defs/Language"
      +  },
      +  {
      +    "anyOf": [
      +      {
      +        "description": "Language used for the emails that deliver the invoice."
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ]
      +  }
      +]
    • removedInput schema / $defs / UpdateInvoiceCustomizationRequest / properties / invoice_accent_color / example
      Removed value: -"#fc481d"
    • changedInput schema / $defs / UpdateInvoiceCustomizationRequest / properties / invoice_language / allOf
      Previous value: -[
      -  {
      -    "$ref": "#/$defs/Language"
      -  },
      -  {
      -    "description": "Language used to render the invoice PDF."
      -  }
      -]New value: +[
      +  {
      +    "$ref": "#/$defs/Language"
      +  },
      +  {
      +    "anyOf": [
      +      {
      +        "description": "Language used to render the invoice PDF."
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ]
      +  }
      +]
    • removedInput schema / $defs / UpdateInvoiceCustomizationRequest / properties / invoice_template_type / allOf
      Removed value: -[
      -  {
      -    "$ref": "#/$defs/InvoiceTemplateType"
      -  }
      -]
    • addedInput schema / $defs / UpdateInvoiceCustomizationRequest / properties / invoice_template_type / anyOf
      Added value: +[
      +  {
      +    "allOf": [
      +      {
      +        "$ref": "#/$defs/InvoiceTemplateType"
      +      }
      +    ],
      +    "description": "Template used to render the invoice PDF."
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedInput schema / $defs / UpdateInvoiceCustomizationRequest / properties / invoice_template_type / description
      Removed value: -"Template used to render the invoice PDF."
    • 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.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true; the description adds genuinely new behavioral facts beyond them — that the update is a partial merge, that it is forward-looking only and does not mutate already-issued documents, and that the logo is out of scope. It does not discuss required permissions or what the call returns, but the company_id schema text already covers the 403 non-disclosure behavior.

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?

Three short paragraphs, front-loaded with the action and the affected fields, then the partial-update rule, then the future-only caveat. Slight redundancy in restating the partial-update rule that also appears in the body $ref description, and the trailing endpoint/URL line is reference metadata rather than agent-facing guidance.

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 two-parameter but deeply nested mutation with no output schema, the description covers scope, partial semantics, the logo exception, and the future-invoices-only effect — enough to call it correctly. It omits the response shape and any permission/precondition notes, which would be the remaining gap.

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?

With 50% schema coverage and a nested body, the description compensates by naming all four mutable body properties in plain language, reinforcing the $defs-level descriptions. It does not add format detail (the #RRGGBB pattern and the enum meanings live in the schema), but it correctly signals that the body is a partial object rather than a full replacement.

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?

States a specific verb and resource ('Updates how the invoices of a company are rendered and delivered') and enumerates the exact configurable surface: PDF template, accent colour, invoice language, email language. It also carves out the logo as belonging to a different sub-resource, which lets an agent distinguish it from both beel_get_invoice_customization and beel_delete_company_logo without opening a 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?

Gives a clear operating context: partial semantics ('Only the properties present in the request body are modified') and a scoping rule ('applies to invoices rendered after it'). It names the logo sub-resource as the alternative for that concern, but never explicitly points to beel_get_invoice_customization / beel_list_invoice_customization_options as the read or discovery counterpart, so the read-vs-write routing 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

Other Tools