Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_create_customers_bulk

Idempotent

Create up to 500 customers in one atomic batch; use dry-run validation to check tax IDs, duplicates, and formats before persisting, with any invalid record rejecting the whole set.

Instructions

Creates up to 500 customers of this company in a single call.

  • Atomic: if any customer fails validation the whole batch is rejected with 422 BULK_VALIDATION_ERROR and nothing is persisted. This is not a partial operation.

  • dry_run: with dry_run=true the batch is only validated — tax identifiers against the AEAT register, duplicates inside the batch and against the existing customers, field formats — nothing is written and the answer is 200. With dry_run=false, the default, validation is followed by creation and the answer is 201.

  • Report: both modes return the same per-record report, so a dry run and a real run are read the same way.

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

⚠️ Read before calling:

  • Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation)

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

Input Schema

NameRequiredDescriptionDefault
bodyYes
dry_runNoValidate the batch without persisting it (`true`), or validate and create it (`false`, the default). Either way the batch is atomic.
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.
idempotency_keyNoOptional 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.

  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"
      +]
    • changedInput schema / $defs / AlternativeIdentifier / description
      Previous value: -"Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n"New value: +"Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n  That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is\n  rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer\n  is checked when it is saved; an invoice recipient, when the invoice is issued with\n  VeriFactu. If the census does not answer, the identifier is not rejected.\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n"
  2. Changed19 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 / AlternativeIdentifier / description
      Previous value: -"Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (enforced server-side, returns `422 ALTERNATIVE_ID_INVALID` on violation)\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | ✓                   |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n"New value: +"Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n"
    • changedInput schema / $defs / AlternativeIdentifier / properties / country_code / description
      Previous value: -"ISO 3166-1 alpha-2 country code. Constrains the allowed `type` values;\nsee the VeriFactu rules on the parent schema.\n"New value: +"ISO 3166-1 alpha-2 code of the country that issued the document. Required except for\n`PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed\n`type` values; see the VeriFactu rules on the parent schema.\n"
    • addedInput schema / $defs / AlternativeIdentifier / properties / number / description
      Added value: +"Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix\n(e.g. `FR40303265045`); see the VeriFactu rules on the parent schema.\n"
    • changedInput schema / $defs / AlternativeIdentifier / properties / type / description
      Previous value: -"Identifier type. Use descriptive names:\n- **NIF_IVA**: VAT-ID (intra-community EU) — *not allowed when `country_code = ES`*\n- **PASSPORT**: Passport — *allowed for any country*\n- **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`*\n- **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`*\n- **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`*\n- **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`*\n\n**⚠️ DEPRECATED numeric codes** (will be removed in v2):\n02, 03, 04, 05, 06, 07 — use the descriptive names above instead.\n"New value: +"Identifier type. Use descriptive names:\n- **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure*\n- **PASSPORT**: Passport — *allowed for any country*\n- **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`*\n- **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`*\n- **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`*\n- **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`*\n\n**⚠️ DEPRECATED numeric codes** (will be removed in v2):\n02, 03, 04, 05, 06, 07 — use the descriptive names above instead.\n"
    • changedInput schema / $defs / CreateCustomerRequest / properties / billing_emails / description
      Previous value: -"Additional emails for invoice delivery (optional)"New value: +"Addresses that receive the customer's invoice emails. When the send request names no\n`recipients` and the invoice has no `email_config` recipients, invoices go to these\naddresses, and not to `email`; `email` is used only when `billing_emails` is empty.\n"
    • changedInput schema / $defs / CreateCustomerRequest / properties / email / description
      Previous value: -"Email address (minimum valid email is 5 chars, e.g. a@b.co)"New value: +"Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go\nhere only when the customer has no `billing_emails`.\n"
    • changedInput schema / $defs / CreateCustomerRequest / properties / phone / $ref
      Previous value: -"#/$defs/Phone"New value: +"#/$defs/PhoneInput"
    • changedInput schema / $defs / PaymentMethod / description
      Previous value: -"Payment method for invoices and recurring invoices.\nNONE means no payment information will be shown.\n"New value: +"Payment method shown on invoices and recurring invoices.\n\n- `NONE`: no payment information is shown.\n- `BANK_TRANSFER`: bank transfer to the IBAN of the payment details; the only method\n  that requires an IBAN.\n- `CARD`: card payment.\n- `CASH`: cash payment.\n- `CHECK`: payment by cheque.\n- `DIRECT_DEBIT`: direct debit from the customer's bank account.\n- `BIZUM`: payment through Bizum.\n- `OTHER`: any other method.\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"
      +}
  3. Changed22 schema fields changedv0.5.0
    • addedInput schema / $defs / Address / additionalProperties
      Added value: +false
    • removedInput schema / $defs / Address / properties / city / example
      Removed value: -"Madrid"
    • removedInput schema / $defs / Address / properties / country / example
      Removed value: -"España"
    • removedInput schema / $defs / Address / properties / country_code / example
      Removed value: -"ES"
    • removedInput schema / $defs / Address / properties / door / example
      Removed value: -"A"
    • removedInput schema / $defs / Address / properties / floor / example
      Removed value: -"2º A"
    • removedInput schema / $defs / Address / properties / number / example
      Removed value: -"123"
    • removedInput schema / $defs / Address / properties / postal_code / example
      Removed value: -"28001"
    • removedInput schema / $defs / Address / properties / province / example
      Removed value: -"Madrid"
    • removedInput schema / $defs / Address / properties / street / example
      Removed value: -"Calle Mayor, 123"
    • addedInput schema / $defs / CreateCustomerRequest / additionalProperties
      Added value: +false
    • removedInput schema / $defs / Email / example
      Removed value: -"user@example.com"
    • removedInput schema / $defs / IBAN / example
      Removed value: -"ES1234567890123456789012"
    • removedInput schema / $defs / NIF / example
      Removed value: -"12345678A"
    • addedInput schema / $defs / PaymentInfo / additionalProperties
      Added value: +false
    • removedInput schema / $defs / PaymentInfo / properties / payment_term_days / example
      Removed value: -30
    • removedInput schema / $defs / PaymentMethod / example
      Removed value: -"BANK_TRANSFER"
    • removedInput schema / $defs / Phone / example
      Removed value: -"+34 612 345 678"
    • removedInput schema / $defs / SWIFT / example
      Removed value: -"ABCDESMMXXX"
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / body / 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

A3.9/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: full-batch atomicity with `422 BULK_VALIDATION_ERROR` and nothing persisted, the 200-vs-201 status distinction between dry run and real run, the scope of what validation covers (AEAT census, in-batch and existing duplicates, field formats), and that both modes return the same per-record report. This is exactly the failure-mode and side-effect context annotations cannot express.

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 one-line purpose followed by three tight, useful bullets; each earns its place by describing atomicity, mode semantics, and return consistency. Minor waste: the dry_run bullet partially duplicates the schema description, and the trailing guardrails warning plus endpoint line add bulk that could be trimmed.

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 tool with a deep nested payload and no output schema, the description covers the key risk surface (atomic rejection, validation scope, dry-run safety, response consistency). The remaining gap is that the per-record report's structure is only alluded to rather than described, but the extensive $defs and parameter docs carry most of the payload burden.

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 75% and the dry_run parameter already carries a near-identical description in the schema, so the bullet mostly restates structured data. company_id and idempotency_key are not touched in the description, though the schema documents them at length. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'Creates up to 500 customers of this company in a single call.' That clearly separates it from list/patch/delete operations. However it never names the single-record sibling beel_create_customer or beel_create_customer_import, so the agent must infer the bulk-vs-single choice from the tool name alone.

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

Usage Guidelines3/5

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

The dry-run bullet gives clear operational guidance (validate first, then create) and warns that the operation is all-or-nothing. But there is no explicit statement of when to prefer this tool over beel_create_customer for one record or beel_preview_customer_import for an import flow, which is the main routing decision an agent faces among these siblings.

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