BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_update_tax_configuration

Idempotent

Update a company's default tax settings—main tax, exemption reasons, surcharge, IRPF, payment terms—while leaving omitted fields unchanged.

Instructions

Updates the tax configuration of a company. Fields you omit keep their current value; default_main_tax, when sent, replaces the stored one wholesale.

Regime coherence: the main tax and its VeriFactu regime key must be coherent. Regime key 18 (equivalence surcharge) only exists for IVA, so pairing it with any other regime answers 422 INVALID_REGIME_KEY_FOR_TAX_TYPE, with details naming the rejected key, the tax type and the keys that type admits.
Surcharge: applying the surcharge without regime key 18 answers 422 RECARGO_REQUIRES_REGIME_RE.
Exemption reason: default_exemption_reason travels with default_main_tax — sending the tax without a reason clears the stored one, and sending only the reason applies it to the tax already stored.

Endpoint: PUT /v1/companies/{company_id}/tax-configuration

Input Schema

TableJSON Schema

Name	Required	Description	Default
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv0.5.0Aug 30, 2026

removedInput schema / $defs / EquivalenceSurchargePercentage / example
```
Removed value: -5.2
```
removedInput schema / $defs / ExemptionReason / example
```
Removed value: -"EXENTA_ART_20"
```
removedInput schema / $defs / IrpfPercentage / example
```
Removed value: -15
```
removedInput schema / $defs / PaymentMethod / example
```
Removed value: -"BANK_TRANSFER"
```
removedInput schema / $defs / RegimeKey / example
```
Removed value: -"01"
```
addedInput schema / $defs / TaxInfo / additionalProperties
```
Added value: +false
```

removedInput schema / $defs / TaxInfo / example

Removed value: -{
-  "percentage": 21,
-  "regime_key": "01",
-  "type": "IVA"
-}

removedInput schema / $defs / TaxInfo / properties / percentage / example
```
Removed value: -21
```
removedInput schema / $defs / TaxType / example
```
Removed value: -"IVA"
```
addedInput schema / $defs / UpdateTaxConfigurationRequest / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / UpdateTaxConfigurationRequest / properties / default_exemption_reason / $ref
```
Removed value: -"#/$defs/ExemptionReason"
```
addedInput schema / $defs / UpdateTaxConfigurationRequest / properties / default_exemption_reason / anyOf
```
Added value: +[
+  {
+    "$ref": "#/$defs/ExemptionReason"
+  },
+  {
+    "type": "null"
+  }
+]
```
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.6/5.0

Behavior5/5

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

The description goes well beyond the annotations by disclosing partial-update behavior, wholesale replacement of default_main_tax, coupling between default_exemption_reason and default_main_tax, regime-key coherence rules, and specific 422 error codes for incoherent inputs. This is exactly the hidden behavioral context an agent needs for a fiscal mutation endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core update semantics, then uses three bolded bullets for coherent, non-overlapping constraints. Every sentence carries useful information; there is no padding or repetition of schema 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?

For a complex fiscal update with no output schema, the description covers the endpoint, error behavior, replacement semantics, and parameter coupling well. It does not describe the response payload, which is a minor gap, but an agent can safely perform the operation armed with the provided detail plus the rich input schema.

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?

The description adds real meaning above the schema for the central parameters: default_main_tax replaces stored config, default_exemption_reason travels with it, and regime_key must be coherent with the tax type. It does not enumerate every parameter, but the remaining ones already have strong schema descriptions, and the schema coverage is partial rather than zero.

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 description opens with a specific verb and resource: 'Updates the tax configuration of a company.' It is immediately distinguishable from the read-only sibling beel_get_tax_configuration and from beel_update_verifactu_configuration, since the target is the company tax configuration, not VeriFactu configuration.

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 first sentence clearly establishes when to use this tool: when updating a company's tax configuration. It also communicates partial-update semantics ('Fields you omit keep their current value'), which guides the agent on how to formulate calls. It does not explicitly name alternatives or state when not to use it, but the context is clear and unambiguous.

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

Deploy Server

beel_update_tax_configuration

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools