Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_validate_nif

Read-onlyIdempotent

Check Spanish NIF/CIF against AEAT VeriFactu to confirm register status, census standing, and name verification; the check is read-only and stores no customer.

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.

BeeL API endpoint: POST /v1/nif/validate (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": {
      "body": "<body>"
    },
    "name": "beel_validate_nif"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. 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
  3. First observedv0.3.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavior the annotations cannot: the asynchronous fallback when VeriFactu is unavailable (auto-validated once the service returns), the 200-with-INVALID convention for bad syntax, and the 422 FIELD_BLANK error with details.field for a missing NIF. It also discloses that a company name is never verified against the census, which materially changes how an agent should interpret a success.

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-sentence definition followed by scannable bullets keyed to response fields, an 'Invalid input' section, and a pre-call warning — every block has a job. It is on the long side and the legal_name/valid:true explanation overlaps with the schema text, so not quite maximally tight.

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?

There is no output schema, and the description fills that gap by naming the four salient response fields (status, valid, legal_name_verified, census_status) and what each means. Combined with the error-code behavior and the off-line fallback, an agent has everything needed to call and interpret this tool correctly.

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 measured coverage is reported as 0% (the schema's rich NIF/allOf descriptions sit behind $refs, so they may not be counted), and the description compensates by spelling out the consequence of legal_name: required in effect for individuals since a non-matching name yields INVALID, and explicitly meaningless for legal entities. It also clarifies that an absent or empty `nif` is an error rather than an INVALID result, which is a distinction the schema alone does not make.

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+resource+scope: checks a NIF/CIF against the AEAT register through VeriFactu and returns what the register says. It also immediately bounds the operation ('only reads the register: it creates nothing and stores no customer'), which no sibling tool claims, so an agent can distinguish it from beel_issue_invoice or listing tools without opening the 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?

Implies the primary use case explicitly — a pre-validation flow that never has to distinguish rejections by status code — and points at a guardrails resource to read before calling. It does not name an alternative or exclusion (no sibling performs this check, so there is little to route away from), which keeps it just short of 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