Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_patch_company

Destructive

Update a company's editable fields, including legal name, address, bank details, and invoice settings; NIF, entity type, and legal form remain immutable once set.

Instructions

Updates the editable fields of a company; the set is the one UpdateCompanyRequest declares.

  • Immutable fields: nif, entity_type and legal_form, once set. Sending one of them with a different value answers 422 with a code that names the field; sending the value it already has is not a change.

  • legal_name: changing it requires the NIF to pass an AEAT census re-validation. For a legal entity (LEGAL_ENTITY) the census identifies the company by its NIF alone: the name is not verified, so the name sent cannot make it fail. For an INDIVIDUAL the name must match the one the census holds for that NIF.

  • Census not answering: if the AEAT census cannot be reached, the change is not rejected. The response is 200 with the new legal_name stored, and BeeL repeats the census check in the background. The outcome of that check is not part of this resource: no field of CompanyData carries it. To know what the census says about a NIF and a name, ask POST /v1/nif/validate.

  • Addresses: a Spanish postal code (country_code omitted or ES) must have 5 digits, in address and in legal_representative.address; otherwise 422 POSTAL_CODE_INVALID_ES. Other countries' postal codes are free-form.

Test credentials on a Live company

Once the company is activated in Live, a test credential may only write the fields that affect how the invoice looks: logo_url, invoice_accent_color, invoice_template_type, invoice_language, email_language and additional_info. Any other field describes the real business — fiscal address, legal representative, bank details, contact data, IAE, activity start date, payment term — and answers 422 FISCAL_IDENTITY_LIVE_ONLY from Test, since the company is a single record shared by both modes. A company not activated in Live accepts the whole body from Test, and sending a field its current value is never a change.

What comes back

The 200 returns CompanyData with every field this request accepts, under the same name and the same type — so the response is the confirmation of what was stored, and a later GET says the same. A field you never set comes back absent, which means "nothing stored", not "hidden".

Two things live outside this body and keep their own reads: the invoice series (GET /v1/companies/{company_id}/series) and the rendering block, which is also served on its own by GET /v1/companies/{company_id}/invoice-customization.

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

⚠️ Read before calling:

  • Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

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

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. Changed4 schema fields changedv0.10.0
    • changedInput schema / $defs / Address / description
      Previous value: -"Address you send when you create or update a company, a customer or an onboarding.\n\nAddresses you read back are described by their own schema.\n"New value: +"Address you send when you create or update a company, a customer or an onboarding.\n\nA required field made only of whitespace passes the length checks below but leaves the\naddress without that part, so it is rejected with `422`: `STREET_EMPTY`,\n`POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`.\n\nAddresses you read back are described by their own schema.\n"
    • changedInput schema / $defs / Address / properties / province / description
      Previous value: -"Province or state - Latin characters only"New value: +"Province or state - Latin characters only. Required for an address in Spain\n(`country_code` `ES`, or no country at all); optional elsewhere, where many addresses\nhave none. A Spanish address without it is rejected with a `422`.\n"
    • changedInput schema / $defs / Address / required
      Previous value: -[
      -  "street",
      -  "postal_code",
      -  "city",
      -  "province"
      -]New value: +[
      +  "street",
      +  "postal_code",
      +  "city"
      +]
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. Changed14 schema fields changedv0.9.0
    • changedInput schema / $defs / Address / description
      Previous value: -"Address you send when you create or update a company, a customer or an onboarding.\nThe street number is mandatory here: an address without it is rejected with `422`.\n\nAddresses you read back are described by their own schema, and do not guarantee the\nstreet number: records registered before it was collected have none.\n"New value: +"Address you send when you create or update a company, a customer or an onboarding.\n\nAddresses you read back are described by their own schema.\n"
    • changedInput schema / $defs / Address / properties / city / pattern
      Previous value: -"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª()]+$"New value: +"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$"
    • changedInput schema / $defs / Address / properties / country / description
      Previous value: -"Country - Latin characters only.\nOmitted, the address is stored as `España`.\n"New value: +"Country of the address, as its ISO 3166-1 alpha-2 code (`GB`) or its official name\nin Spanish, English or Catalan (`Reino Unido`, `United Kingdom`, `Regne Unit`;\ncase and accents are ignored). Anything else, such as `UK`, is rejected with\n`422 COUNTRY_CODE_REQUIRED`: send `country_code` instead. If it names a different\ncountry than `country_code`, `422 COUNTRY_CODE_MISMATCH` (`España` alone yields to\na foreign `country_code`: it was the old default). What is stored and\nreturned is always the Spanish name derived from the resulting code, never the\ntext sent. With neither field present, the address is Spanish (`España`).\n"
    • changedInput schema / $defs / Address / properties / country / pattern
      Previous value: -"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª]+$"New value: +"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$"
    • changedInput schema / $defs / Address / properties / country_code / description
      Previous value: -"ISO 3166-1 alpha-2 country code.\nOmitted, the address is stored as `ES`.\n"New value: +"ISO 3166-1 alpha-2 country code: the canonical field that decides the country of\nthe address. It must be a real country code (`GB`, not `UK`); otherwise\n`422 COUNTRY_CODE_REQUIRED`. When it is omitted, the code comes from `country`\n(see there). With neither field present, the address is stored as `ES`.\n"
    • changedInput schema / $defs / Address / properties / number / description
      Previous value: -"Street number"New value: +"Street number. Optional: omit it when the address has none, or when `street` already\ncarries the address in full.\n"
    • changedInput schema / $defs / Address / properties / province / pattern
      Previous value: -"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª]+$"New value: +"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$"
    • changedInput schema / $defs / Address / properties / street / pattern
      Previous value: -"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\s\\.,\\-\\/'ºª°:;\"()&#]+$"New value: +"^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$"
    • changedInput schema / $defs / Address / required
      Previous value: -[
      -  "street",
      -  "number",
      -  "postal_code",
      -  "city",
      -  "province"
      -]New value: +[
      +  "street",
      +  "postal_code",
      +  "city",
      +  "province"
      +]
    • changedInput schema / $defs / Language / description
      Previous value: -"Supported languages"New value: +"Supported languages: `es` Spanish, `en` English, `ca` Catalan.\n"
    • removedInput schema / $defs / Phone
      Removed value: -{
      -  "description": "Phone number. Allows digits, spaces, dashes, parentheses, and optional leading +",
      -  "maxLength": 20,
      -  "minLength": 9,
      -  "pattern": "^[+]?[0-9\\s\\-\\(\\)]+$",
      -  "type": "string"
      -}
    • addedInput schema / $defs / PhoneInput
      Added value: +{
      +  "description": "A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces,\ndashes, parentheses and an optional leading `+`. Every request that takes a phone number\nuses this schema.\n\nIt is `Phone` plus the rules enforced on input. A value this schema accepts always\nsatisfies `Phone`, so anything you send here is something a response can return.\n",
      +  "maxLength": 20,
      +  "minLength": 9,
      +  "pattern": "^[+]?[0-9\\s\\-\\(\\)]+$",
      +  "type": "string"
      +}
    • removedInput schema / $defs / UpdateCompanyRequest / properties / phone / allOf
      Removed value: -[
      -  {
      -    "$ref": "#/$defs/Phone"
      -  },
      -  {
      -    "anyOf": [
      -      {},
      -      {
      -        "type": "null"
      -      }
      -    ]
      -  }
      -]
    • addedInput schema / $defs / UpdateCompanyRequest / properties / phone / anyOf
      Added value: +[
      +  {
      +    "allOf": [
      +      {
      +        "$ref": "#/$defs/PhoneInput"
      +      }
      +    ]
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  3. Addedv0.5.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes far beyond the annotations, which only say destructive/idempotent/not-read-only. It discloses the 422 codes and which field they name, the census re-validation behavior including the non-rejection fallback on census outage, the ES 5-digit postal code rule with 422 POSTAL_CODE_INVALID_ES, and the Test-vs-Live writable field restriction with 422 FISCAL_IDENTITY_LIVE_ONLY.

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?

Purpose is front-loaded and the bolded headings plus bullets make a long description scannable. There is some redundancy: the legal_name census rule is stated both in the tool description and again inside the UpdateCompanyRequest schema, and the 'everything reads back' point is repeated in both places.

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?

With no output schema, the description carries the return-value burden itself and does it well: the 200 returns CompanyData with every accepted field under the same name/type, absent means 'nothing stored', and the series/rendering blocks live outside this body. Combined with the guardrail pointer on company selection, nothing needed to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds cross-field meaning the schema cannot express: nif/entity_type/legal_form are immutable once set and sending the existing value is not a change, legal_name triggers a census check whose strictness depends on entity_type, and the Test credential can only write six presentation fields. The company_id 403-vs-404 collapsing behavior is also explained.

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?

Opens with a specific verb and resource ('Updates the editable fields of a company') scoped to the exact request schema, and names the backing endpoint PATCH /v1/companies/{company_id}. It separates this tool from adjacent ones by calling out that the invoice series and rendering block have their own reads (GET /series, GET /invoice-customization), so the agent knows what this call does not cover.

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 strong conditional guidance: which fields are immutable, when a legal_name change is safe (LEGAL_ENTITY vs INDIVIDUAL), and explicitly routes census questions to POST /v1/nif/validate when the background check outcome is unknown. It does not explicitly say when to prefer this over the sibling beel_update_invoice_customization for the rendering fields, which keeps it below a 5.

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