Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_validate_nif

Validate a Spanish NIF or CIF against the AEAT register via VeriFactu to confirm its status, census condition, and name verification for individuals, without storing any data.

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

⚠️ Read before calling:

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

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

A4.4/5.0
Behavior5/5

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

Goes well beyond annotations: it explains what each response field means (status distinctions including VeriFactu unavailability and automatic revalidation, the differing meaning of valid:true for individuals vs legal entities, legal_name_verified, census_status) and the 200/INVALID vs 422/FIELD_BLANK error contract. The readOnlyHint=false annotation reflects the POST transport, while the description clarifies no state is written — a clarification rather than a contradiction.

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 purpose, then tight bullets per response field, an explicit endpoint, and a short callout with a resource link. Slightly long but essentially every line carries information an agent needs.

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 full burden of explaining return values and does so field by field, plus the error semantics. An agent can interpret every possible outcome without consulting other artifacts.

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?

Only one body parameter, and the description adds useful meaning for legal_name (verified for individuals, ignored for legal entities). However, it does not restate the NIF syntax requirements, leaving most parameter semantics to the schema.

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?

States a specific verb and resource — checks a NIF/CIF against the AEAT register via VeriFactu — and scopes it precisely as a read-only lookup. No sibling tool validates tax IDs, so it is unmistakable among the beel_* set.

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 clear context for use (pre-validation flow before issuing invoices, with the guardrails resource linked for why a name mismatch blocks submission). It does not explicitly name an alternative tool or a when-not-to-use condition, but the usage scenario is unambiguous.

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