Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_validate_nif

Checks a Spanish NIF or CIF against the AEAT tax register via VeriFactu and returns its census status, validity, and legal name verification.

Instructions

Checks a NIF or CIF against the AEAT register through VeriFactu and returns what the register says about it. It only reads the register: it creates nothing and stores no customer.

  • status: distinguishes a NIF found in the register from one that is syntactically correct but absent, and from a check that could not be completed because VeriFactu was unavailable — in which case the NIF is validated automatically once the service is back.

  • valid: true: means different things by holder. For an individual, AEAT matched NIF and name together. For a legal entity the name you sent is not verified at all — AEAT identifies a company by its CIF alone — so it says nothing about your name.

  • legal_name_verified: tells those two cases apart.

  • census_status: says whether an identified NIF is also deregistered or revoked.

Invalid input

  • Bad syntax is an answer, not an error: it comes back 200 with status: INVALID, so a pre-validation flow never has to tell rejections apart by status code.

  • A missing NIF is an error: an absent or empty nif answers 422 FIELD_BLANK, with details.field naming it.

Endpoint: POST /v1/nif/validate

⚠️ Fiscal guardrails — read before calling:

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

For the exhaustive rules and worked examples, call beel_docs_search.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.5.0
    • removedInput schema / $defs / NIF / example
      Removed value: -"12345678A"
    • addedInput schema / $defs / ValidateNifRequest / additionalProperties
      Added value: +false
    • removedInput schema / $defs / ValidateNifRequest / properties / legal_name / example
      Removed value: -"JUAN PEREZ GARCIA"
    • addedInput schema / additionalProperties
      Added value: +false
  2. First observedv0.3.1

TDQS

A3.7/5.0
Behavior1/5

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

The description is behaviorally rich, covering status values, valid semantics, legal_name_verified, census_status, and 200/422 error behavior. However, it explicitly claims 'only reads the register: it creates nothing and stores no customer' while the annotations set readOnlyHint to false, which is a direct annotation contradiction. Per the rubric, this forces a score of 1.

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?

The description is front-loaded with the core behavior and safety clarification, then uses bolded field names, an 'Invalid input' section, and a clear endpoint line. It is long, but nearly every sentence carries distinct behavioral information, and the structure makes it scannable.

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?

There is no output schema, so the description correctly takes responsibility for explaining the main response concepts: status, valid, legal_name_verified, and census_status. It also covers both normal and error paths and points to guardrails and docs for deeper rules. It omits a complete response-shape listing, but the described fields are sufficient for safe invocation.

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 schema description coverage reported at 0%, the description compensates by explaining key input behaviors: a missing nif triggers 422 FIELD_BLANK, bad syntax returns 200 with status INVALID, and legal_name has different semantic weight for individuals vs legal entities. It does not explicitly state the required/optional distinction for legal_name, but the description goes well beyond a bare schema listing.

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 clearly states a specific verb and resource: it checks a NIF or CIF against the AEAT register through VeriFactu. It also explicitly scopes the action as read-only, saying it creates nothing and stores no customer, making it distinct from the many create/invoice-focused sibling tools.

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 description clearly establishes when to call this tool: for NIF/CIF validation against the Spanish AEAT register, including in a pre-validation flow. It does not name an operational alternative because none evidently exists among siblings, but it does point to beel_docs_search for exhaustive rules, which is a useful routing cue.

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