An MCP server that gives an AI agent read-only Mexican tax and banking tooling — validate RFC/CURP/CLABE/NSS, read CFDI 4.0 invoices, check an invoice's live status at the SAT, and search the SAT's code tables — with no API keys, CSD certificate or PAC contract.
Validate identifiers — validate_rfc (12/13 chars, modulus-11 check digit, parts, birth/incorporation date, flags the SAT generics like XAXX010101000), validate_curp (base-37 check digit, decodes birth date, sex, RENAPO state key and century marker), validate_clabe (18 digits, correct 3-7-1 control digit, names the Banxico bank), validate_nss (IMSS Luhn digit, split into its fields).
Generate coherent test data — generate_test_data produces 1–100 fake people or companies whose RFC, CURP, CLABE and NSS all derive from the same identity and satisfy their check digits; useful for seeds, fixtures and demos.
Read a CFDI 4.0 invoice — parse_cfdi turns the XML into JSON: header, issuer, receiver, line items with transferred/withheld taxes, tax totals and the Timbre Fiscal Digital; it labels catalogue codes, validates both RFCs and checks the totals arithmetic. It works regardless of namespace prefixes, but does not verify the digital signature.
Ask the SAT whether an invoice is live — cfdi_status queries the public ConsultaCFDIService SOAP endpoint (the QR-code service) using either the four key fields or the whole XML, returning Estado, EsCancelable, EstatusCancelación and ValidacionEFOS (69-B list) with plain-language meanings. Fail-soft: 10 s timeout, one retry, available: false on failure, never an exception.
Look up SAT catalogues offline — sat_catalog_lookup searches nine bundled tables (regimen_fiscal, uso_cfdi, forma_pago, metodo_pago, tipo_comprobante, objeto_imp, impuestos, bancos_clabe, estados_curp) by exact code or accent-insensitive text.
Every tool is read-only, declares an outputSchema and returns structuredContent plus Markdown (default) or JSON (response_format="json"). Only cfdi_status touches the network — one hardcoded host — and runs over stdio or stateless Streamable HTTP (2026-07-28 revision, still serving 2025-era clients). Results are structural checks, not proof of registration with the SAT, RENAPO, IMSS or Banxico.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mx-fiscal-mcp-server is RFC XAXX010101000 valid? it looks off to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives an AI agent Mexican tax and banking capabilities — validate RFC, CURP, CLABE and NSS with real check digits, read a CFDI 4.0 invoice, ask the SAT whether it is still live, and look up the SAT's code tables. No API keys, no CSD certificate, no PAC contract.
Ask Claude "read this invoice and tell me whether it's still valid" and it parses the XML, labels every SAT code, checks both RFCs and the arithmetic, and queries the SAT's public status service — instead of you opening three web tools.
> Read this CFDI and check it at the SAT
parse_cfdi(xml="<cfdi:Comprobante …>")
CFDI A-1042 — 1160.00 MXN
✅ Stamped · version 4.0 · Ingreso
Emisor: TES150312DX2 ✅ 601 — General de Ley Personas Morales
Receptor: PELJ900521DK2 ✅ G03 — Gastos en general
✅ Totals add up: subtotal − discount + transferred − withheld = total
cfdi_status(xml="<cfdi:Comprobante …>")
CFDI status — Vigente
✅ The invoice exists in the SAT's records and has not been cancelled.
Es cancelable: Cancelable con aceptación
EFOS: returned 200 — the issuer is NOT on the SAT's definitive 69-B list.Mexican electronic invoicing has two halves, and only one of them was served.
Building and stamping a CFDI needs a CSD certificate and a contract with a PAC.
That half already has tooling — mcp-cfdi-mx
(Python) does it, and this server deliberately does not compete with it.
Reading is the other half, and it needs nothing: the check-digit algorithms are
public, the SAT's catalogues are public, and the invoice status service behind the QR
code on every printed invoice is public and unauthenticated. Yet an agent asked to
validate an RFC will happily invent a regex that rejects XAXX010101000 — the RFC of
every invoice issued to the general public — because that one does not satisfy its own
check digit. This server is the read half, done carefully.
The arithmetic comes from mx-identifiers
(MIT, zero dependencies, 101 tests against public vectors); the CFDI reader is ported
from the tool running at ortamarco.me;
the SOAP envelope was read out of nodecfdi/sat-estado-cfdi
rather than guessed. It is the third of three read-only, key-free MCP servers alongside
domain-security-mcp-server
and seo-geo-mcp-server.
Related MCP server: Mexico Invoice MCP
Tool | What it does |
| RFC for individuals (13 chars) and companies (12), full modulus-11 check digit, parsed fields, birth/incorporation date. Flags the SAT generics and says which of them satisfies the arithmetic |
| 18-character CURP with the base-37 check digit; decodes birth date, sex, state (RENAPO keys, not INEGI/ISO) and the century marker |
| 18-digit CLABE with the correct 3-7-1 control digit — each weighted product counts only its last digit ( |
| 11-digit IMSS number with its Luhn digit, split into subdelegación / registration year / birth year / serial |
| 1-100 coherent fake people or companies: the RFC and CURP derive from the same name and birth date, the CLABE's bank is a real participant, every check digit holds |
Tool | What it does |
| CFDI 4.0 XML → JSON: header, issuer, receiver, every line item with transferred and withheld taxes, tax totals, and the Timbre Fiscal Digital (or |
| Queries the SAT's public |
Tool | What it does |
| Nine bundled code tables — |
Every tool is read-only, declares an outputSchema and returns structuredContent
(validated by the SDK) alongside human-readable Markdown (default) or JSON
(response_format="json").
These are surfaced in the tool output, not buried here:
Structurally valid is not registered. A check digit that adds up says the string is well-formed and nothing more. Only the SAT can say an RFC is registered; only RENAPO that a CURP belongs to a person. This server never asks either, and its wording never implies it did.
XAXX010101000 does not satisfy its own check digit. The SAT assigned the
general-public RFC by decree and the modulus-11 algorithm asks for a 4 where the
SAT wrote a 0. XEXX010101000 (foreign residents) does satisfy it. The tools
report is_generic and check_digit_satisfied as separate fields rather than
collapsing both into "valid".
Reading a CFDI is not verifying it. parse_cfdi does not check the digital
signature. A perfectly parseable invoice can be cancelled, or fabricated wholesale.
An unreachable SAT is not an invalid invoice. The status endpoint publishes no
SLA and no status page, and it goes down. Its documentation states capacity for up to
2 million queries per hour and asks callers not to raise their query volume, since
every query reads the SAT's transactional databases. cfdi_status degrades to
available: false with the reason — a statement about the SAT, never about the
document.
The bank list is a subset. bancos_clabe carries the main Banxico participants,
not the full catalogue; an unknown code is reported as unknown rather than given an
invented name. The plaza catalogue is not bundled at all, so the plaza code is
returned verbatim.
EFOS codes are read from the SAT's own table. The SAT documents ValidacionEFOS
in its Documentación del Servicio de Consulta de CFDI v1.4,
section 3: 100, 101 and 104 put the issuer on the definitive 69-B list;
102 and 103 mean the issuer is not on it but a third-party RFC the invoice was
issued on behalf of (a cuenta de terceros) is; 200 and 201 mean the issuer is not
on it (201: nor any third party). efos_state speaks of the issuer only, and
efos_third_party_state (listed / not_listed / not_reported / unknown) of the
third parties. An empty field or an undocumented code is reported as unknown with
the raw code kept in validacion_efos, never as "listed". Versions up to 1.0.1
reported 102 and 103 as an issuer on the list; 1.0.2 fixes it.
Built on the v2 MCP SDK, so it speaks the 2026-07-28 revision (server/discover,
no initialize, per-request _meta envelope) and still serves 2025-era clients —
Claude Desktop, Claude Code and Cursor — from the same server factory. The entry points
own the era decision: serveStdio(factory) on stdio, createMcpHandler(factory) over
HTTP with the default legacy: 'stateless'. There is no session state and no
Mcp-Session-Id in either direction. npm run smoke exercises every tool on both
eras and asserts the negotiated era of each connection.
Because the tool list is a compile-time constant, tools/list and server/discover
advertise a real one-hour ttlMs with cacheScope: 'public' on 2026-era connections
instead of the SDK's conservative ttlMs: 0.
Requires Node.js 20+. Nothing to clone — every MCP client can run it with npx.
claude mcp add mx-fiscal -- npx -y mx-fiscal-mcp-serverAdd to claude_desktop_config.json (or ~/.cursor/mcp.json) — see examples/:
{
"mcpServers": {
"mx-fiscal": {
"command": "npx",
"args": ["-y", "mx-fiscal-mcp-server"]
}
}
}On Windows use "command": "cmd" with "args": ["/c", "npx", "-y", "mx-fiscal-mcp-server"].
Restart the client, then ask: "Generate 10 Mexican customers with valid RFC and CURP for my seed file."
The same server speaks stateless Streamable HTTP for remote or multi-client use.
TRANSPORT=http npx -y mx-fiscal-mcp-server
# POST JSON-RPC to http://127.0.0.1:3000/mcp · health at /healthzIt is safe by default: it binds to 127.0.0.1 and only accepts localhost
Host and Origin headers, which blocks DNS-rebinding attacks from a web page.
To expose it — for example behind Coolify or Traefik — opt in explicitly:
Variable | Default | Purpose |
|
|
|
|
| Listening port |
|
| Bind address; |
| — | Comma-separated hostnames the |
| — | Comma-separated origins allowed to call from a browser |
| — | If set, every request needs |
|
| Largest CFDI accepted, in characters |
|
|
|
A self-hosted instance makes requests to the SAT on its callers' behalf, so do
not expose it without MCP_AUTH_TOKEN: an open one is a free relay that can get
your IP rate-limited. With Docker (the image sets HOST=0.0.0.0):
docker build -t mx-fiscal-mcp .
docker run -p 3000:3000 -e ALLOWED_HOSTS=mcp.example.com -e MCP_AUTH_TOKEN=change-me mx-fiscal-mcpnpm run dev # tsx watch (stdio)
npm run typecheck # tsc --noEmit
npm test # deterministic offline unit tests, HTTP transport defaults included
npm run smoke # every tool over the real protocol, on BOTH eras
npm run inspect # MCP Inspector against the built server
npm run build # type-check + emit dist/src/
├── index.ts # transport selection: serveStdio | createMcpHandler + Express
├── server.ts # the server FACTORY — registers every tool, holds the instructions
├── schemas.ts # Zod 4 outputSchema for each tool
├── constants.ts # the single external host, timeouts, limits
├── format.ts # markdown/JSON response shaping, findings
├── core/ # pure logic, no MCP coupling — reusable & testable
│ ├── identifiers.ts # reporting layer over mx-identifiers (errors, labels, findings)
│ ├── cfdi.ts # the CFDI 4.0 reader, ported 1:1 from the web tool
│ ├── sat.ts # SOAP envelope, expression builder, response interpretation
│ ├── catalogs.ts # the nine code tables + lookup
│ └── testdata.ts # fixture generation
└── tools/ # thin MCP wrappers (Zod schemas, descriptions, formatting)The core/ layer carries no MCP types, so the same logic backs both this server and a
web UI. All the check-digit arithmetic lives in mx-identifiers and is not
reimplemented here.
Network surface: exactly one host, consultaqr.facturaelectronica.sat.gob.mx,
hardcoded in constants.ts. No tool accepts a URL from the caller, so there is no
SSRF surface to guard. The other seven tools make no network calls at all.
Untrusted XML: a document that declares a DOCTYPE is refused before parsing (a
CFDI never has one), and size and element-count caps bound the memory one parse can
take. cfdi_status screens the RFCs, total and UUID before spending a request on
them. Found a problem? Please open a private security advisory.
Un servidor MCP que le da a un agente de IA las capacidades fiscales mexicanas que todo el mundo acaba reimplementando mal: validar RFC, CURP, CLABE y NSS con sus dígitos verificadores de verdad, leer un CFDI 4.0 en XML, consultar su estado en el SAT y buscar en los catálogos del SAT. Sin API keys, sin CSD y sin PAC.
Esto es la mitad de LECTURA. Para construir y sellar un CFDI hace falta un
certificado de sello digital y un PAC, y eso ya lo cubre
mcp-cfdi-mx (Python). Este servidor no
compite con él: lo complementa.
Lo que sí hace bien y casi nadie:
XAXX010101000 no satisface su propio dígito verificador. El SAT lo asignó por
decreto y el módulo 11 pide un 4 donde el SAT puso un 0. XEXX010101000 (residentes
en el extranjero) sí lo satisface. Por eso tantos formularios rechazan las facturas al
público en general. Las tools devuelven is_generic y check_digit_satisfied por
separado.
El dígito de control de la CLABE se queda con la última cifra de cada producto
ponderado 3-7-1, no con la suma de sus cifras. De 9 × 7 = 63 cuenta el 3; las
implementaciones que copian a Luhn suman 6 + 3 = 9 y sacan otro dígito: para la base
09000000000000000 el algoritmo da 7 y el estilo Luhn da 1. Reducir módulo 10 antes
o después de sumar da lo mismo; el error no está ahí.
Las claves de entidad de la CURP son de RENAPO, no de INEGI ni ISO 3166-2:MX.
DF es Ciudad de México, MC es Estado de México, NE es nacido en el extranjero.
El servicio del SAT se cae y no publica SLA. Su documentación declara capacidad
para hasta 2 millones de consultas por hora y pide no aumentar el volumen de consultas,
porque cada una toca sus bases de datos transaccionales. cfdi_status degrada a
available: false con el motivo; nunca lanza una excepción, y nunca hay que leer un
fallo del SAT como "la factura es inválida".
Estructuralmente válido no es dado de alta. Que el dígito cuadre dice que la cadena está bien formada, nada más.
Se instala sin clonar nada: claude mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server.
El motor aritmético es mx-identifiers
(MIT, cero dependencias); el lector de CFDI viene de la herramienta que corre en
ortamarco.me; el sobre SOAP se leyó
del código de nodecfdi/sat-estado-cfdi,
no se inventó.
Habla la revisión 2026-07-28 del protocolo y sigue atendiendo a los clientes de 2025 (Claude Desktop, Claude Code, Cursor) desde la misma factoría de servidor.
MIT © Marco Orta
Ask the SAT whether an invoice actually exists and is still live. This queries the public ConsultaCFDIService SOAP endpoint — the same service the QR code printed on every Mexican invoice points at — so it needs no credentials, no CSD and no PAC contract.
Pass either the four values the SAT keys on (issuer RFC, receiver RFC, total, UUID) or the whole xml, in which case they are derived from it with the same reader parse_cfdi uses. Deriving them from the XML is the more reliable route: the total must be formatted exactly the way the printed-representation spec demands (six decimals, trailing zeros trimmed), and a total written in another format can come back as a spurious 'No Encontrado'.
What comes back, each with its meaning spelled out:
Estado — Vigente / Cancelado / No Encontrado.
EsCancelable — whether the issuer can cancel it unilaterally, needs the receiver's approval, or cannot cancel it at all.
EstatusCancelacion — whether a cancellation is in progress, was accepted, was rejected, or lapsed.
ValidacionEFOS — whether the issuer, and any third-party RFC the invoice was issued on behalf of (a cuenta de terceros), appears on the SAT's definitive 69-B list of companies that invoice simulated operations. Read with the code table the SAT documents (service documentation v1.4, section 3): 100, 101 and 104 put the issuer on the list; 102 and 103 mean the issuer is NOT on it but a third-party RFC is; 200 and 201 mean the issuer is not on it (201: nor any third party). efos_state speaks of the issuer only and efos_third_party_state of the third parties; an empty field or an undocumented code is unknown, with the raw code kept in validacion_efos.
CodigoEstatus — the service's own result code.
Fail-soft by design. The SAT publishes no SLA and no status page, and the endpoint does go down; its documentation states capacity for up to 2 million queries per hour and asks callers not to raise their query volume, so query once per invoice and cache the answer. On timeout, refusal or a malformed answer this returns available: false with the reason instead of raising — a failed lookup is a statement about the SAT, never about the invoice. Never report a document as invalid on the strength of an unreachable service. One retry, 10-second timeout.
Args (either shape):
xml (string), OR rfc_emisor + rfc_receptor + total + uuid (all strings).
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { available, unavailable_reason, endpoint, expression, attempts, elapsed_ms, source, status{codigo_estatus, query_outcome, estado, document_state, document_meaning, es_cancelable, cancellable_state, cancellable_meaning, estatus_cancelacion, cancellation_state, cancellation_meaning, validacion_efos, efos_state, efos_third_party_state, efos_meaning, raw} | null, findings[] }.
Example: "Is this invoice still valid?" -> cfdi_status(xml="<cfdi:Comprobante …>").
| Name | Required | Description | Default |
|---|---|---|---|
| xml | No | The complete CFDI XML. When given, the four query fields are derived from it and any values passed alongside are ignored. | |
| uuid | No | The fiscal folio (UUID) from the Timbre Fiscal Digital. Required unless `xml` is given. | |
| total | No | Invoice total exactly as written in the XML, e.g. '1160.00'. Required unless `xml` is given. | |
| rfc_emisor | No | Issuer's RFC. Required unless `xml` is given. | |
| rfc_receptor | No | Receiver's RFC. Required unless `xml` is given. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| status | Yes | |
| attempts | Yes | |
| endpoint | Yes | |
| findings | Yes | |
| available | Yes | |
| elapsed_ms | Yes | |
| expression | Yes | |
| unavailable_reason | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, idempotent and non-destructive. The description goes well beyond: no credentials needed, fail-soft design returning available:false instead of raising, one retry with a 10-second timeout, the SAT's 2M queries-per-hour capacity and no-SLA context, and the total-formatting pitfall that produces a spurious 'No Encontrado'. It even warns that a failed lookup is a statement about the SAT, never about the invoice. Nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and structured with headers, bullets and emphasis. It is long, but the semantic complexity (EFOS code table, cancellation states, fail-soft behavior) justifies the length. Minor redundancy: the raw return-shape literal is spelled out even though an output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, externally-dependent tool, everything needed is present: purpose, endpoint, credential requirements, input modes and precedence, formatting gotchas, per-field return interpretation, failure semantics, retry/timeout, rate-limit etiquette, and a usage example. The output schema covers the return structure while the description covers interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: the total must follow the printed-representation spec (six decimals, trailing zeros trimmed) and a mis-format causes a false 'No Encontrado', plus guidance that XML derivation is more reliable than hand-passing the four values. These are interpretations that affect correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource — 'Ask the SAT whether an invoice actually exists and is still live' — then names the exact endpoint (ConsultaCFDIService SOAP). This distinguishes it from parse_cfdi (local XML parsing) and the other sibling validators, so an agent can route correctly 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on the two input shapes, states which route is more reliable ('Deriving them from the XML is the more reliable route'), and adds operational rules (query once, cache, one retry, never declare invalid on an unreachable service). It does not explicitly name when to prefer this over siblings like parse_cfdi or sat_catalog_lookup, but the purpose statement plus sibling names make the boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate structurally valid Mexican identifiers for fixtures, database seeds and demos — generated, not taken from any real record.
For a person each record carries a coherent set: the RFC and the CURP are derived from the same name, sex, birth date and state, the CLABE's bank code is a real Banxico participant, and the NSS satisfies its Luhn digit. For a company, a razón social with a matching persona-moral RFC and a CLABE.
Why generated instead of hand-written: an RFC or CURP typed by hand almost never satisfies its check digit, so it fails the first validation your own code runs, and a seed file full of 'AAAA010101AAA' teaches your tests nothing.
These pass validation but are nobody's on purpose. They are generated from common names, so a CURP or phone number can coincide with a real person's by chance; they are not looked up at the SAT, RENAPO, IMSS or Banxico — do not send them to the SAT's status service or to a PAC.
Args:
kind ('person' | 'company'): what to generate (default 'person').
count (integer 1-100): how many records (default 1).
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { kind, count, people[{nombre, apellido_paterno, apellido_materno, sexo, fecha_nacimiento, entidad, entidad_nombre, rfc, curp, clabe, banco, nss, codigo_postal, telefono, email}], companies[{razon_social, rfc, clabe, banco, codigo_postal, fecha_constitucion}], findings[] }.
Example: "Give me 5 fake Mexican customers with valid RFC and CURP" -> generate_test_data(kind="person", count=5).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | 'person' for individuals (RFC + CURP + CLABE + NSS), 'company' for personas morales. | person |
| count | No | How many records to generate, 1-100. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| count | Yes | |
| people | Yes | |
| findings | Yes | |
| companies | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Well beyond the readOnly/idempotent/non-destructive annotations, it discloses that records are synthetic, that CURPs or phone numbers can coincide with a real person by chance, and that values are not checked against SAT, RENAPO, IMSS or Banxico. It also guarantees internal coherence (RFC and CURP derived from the same name/sex/date/state, real Banxico bank code, NSS passing Luhn), which materially affects how an agent should trust the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then a rationale paragraph, Args, Returns and an example — a logical structure. The Args list duplicates a fully-covered schema and the Returns block restates an existing output schema, so a few sentences do not earn their place, but the disclaimers and example do.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generation tool with an output schema, zero required parameters and simple enums, the description is complete: it covers what is produced, per-kind composition, non-realism caveats and a worked example. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the Args section largely restates what the schema already documents (kind, count bounds, format defaults). The description adds only marginal semantics — e.g. that a person record bundles RFC+CURP+CLABE+NSS — while the enum meanings remain schema-owned, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb (generate) with a precise resource (structurally valid Mexican identifiers) and immediately scopes it to fixtures, seeds and demos. It distinguishes itself from the validate_* siblings by stressing that output is generated, not looked up or verified against real registries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the use cases (fixtures, database seeds, demos) and gives a clear negative condition — do not send the results to the SAT status service or a PAC. It does not explicitly route the agent to validate_rfc/validate_curp/validate_clabe for verification, so the alternative-selection guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn the XML of a Mexican electronic invoice (CFDI 4.0) into structured JSON: header, issuer, receiver, every line item with its transferred and withheld taxes, the tax totals, and the Timbre Fiscal Digital (UUID, stamp date, SAT certificate number, PAC's RFC) — or timbre: null when the document was never stamped.
Three things this does beyond reading attributes:
It labels the catalogue codes. '601' becomes 'General de Ley Personas Morales', 'G03' becomes 'Gastos en general', 'PPD' becomes 'Pago en parcialidades o diferido'. An unknown code is reported as unknown rather than guessed at.
It validates both RFCs (issuer and receiver) with the full modulus-11 check, and flags the SAT generics.
It checks the arithmetic: subtotal − discount + transferred − withheld should equal the declared total. A mismatch is a warning, not a verdict — rounding at the line level is allowed within a centavo.
It walks the document by local element name, so it does not care whether the PAC used the cfdi: and tfd: prefixes, different ones, or none.
What this does NOT do: it does not verify the digital signature, and it does not ask the SAT anything. A document that parses cleanly can still be cancelled, or have been fabricated wholesale. Use cfdi_status for the SAT's own answer.
Args:
xml (string): the CFDI XML.
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { version, serie, folio, fecha, tipo(+label), forma_pago(+label), metodo_pago(+label), moneda, tipo_cambio, sub_total, descuento, total, lugar_expedicion, exportacion, condiciones_de_pago, no_certificado, emisor{rfc, nombre, regimen(+label), rfc_valid, rfc_kind, rfc_errors}, receptor{… domicilio, uso(+label)}, conceptos[{descripcion, clave_prod_serv, cantidad, clave_unidad, unidad, valor_unitario, importe, descuento, objeto_imp(+label), traslados[], retenciones[]}], concepto_count, total_trasladados, total_retenidos, stamped, timbre{uuid, fecha_timbrado, no_certificado_sat, rfc_prov_certif} | null, arithmetic{…}, findings[] }.
Example: "Read this invoice and tell me who issued it and for how much" -> parse_cfdi(xml="<cfdi:Comprobante …>").
| Name | Required | Description | Default |
|---|---|---|---|
| xml | Yes | The complete CFDI XML as a string, from '<cfdi:Comprobante' (or '<?xml') to the closing tag. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| tipo | Yes | |
| fecha | Yes | |
| folio | Yes | |
| serie | Yes | |
| total | Yes | |
| emisor | Yes | |
| moneda | Yes | |
| timbre | Yes | |
| stamped | Yes | |
| version | Yes | |
| findings | Yes | |
| receptor | Yes | |
| conceptos | Yes | |
| descuento | Yes | |
| sub_total | Yes | |
| arithmetic | Yes | |
| forma_pago | Yes | |
| tipo_label | Yes | |
| exportacion | Yes | |
| metodo_pago | Yes | |
| tipo_cambio | Yes | |
| concepto_count | Yes | |
| no_certificado | Yes | |
| total_retenidos | Yes | |
| forma_pago_label | Yes | |
| lugar_expedicion | Yes | |
| metodo_pago_label | Yes | |
| total_trasladados | Yes | |
| conceptos_truncated | Yes | |
| condiciones_de_pago | Yes | |
| total_traslados_locales | Yes | |
| total_retenciones_locales | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description still adds real substance: code labeling, modulus-11 RFC validation, arithmetic checking with a stated tolerance, namespace-agnostic walking, and the explicit limits (no signature verification, no SAT contact). It stops short of describing pagination/size limits or failure modes on malformed XML, so not quite a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded and organized with a numbered list, a negative-scope callout, and an example. However, the lengthy 'Returns' block largely re-enumerates a field list that already exists as an output schema, which is redundant padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, fully-annotated tool with an output schema, the description covers purpose, scope limits, validation behavior, and routing to the sibling SAT-check tool. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are fully documented in the schema, so baseline 3 applies. The Args section merely restates the schema definitions without adding format or edge-case detail beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Turn the XML of a Mexican electronic invoice (CFDI 4.0) into structured JSON') and enumerates exactly what is extracted (header, issuer, receiver, line items, taxes, timbre). An agent can immediately distinguish this parsing tool from cfdi_status without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this versus the alternative: it does not ask the SAT, and 'Use cfdi_status for the SAT's own answer.' It also pre-empts a major misuse case by clarifying that a clean parse does not mean the document is valid or uncancelled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up the code tables a CFDI is written in, without downloading the SAT's spreadsheet. Nine catalogues, all bundled — this tool never touches the network.
regimen_fiscal (c_RegimenFiscal) — tax regime of issuer and receiver
uso_cfdi (c_UsoCFDI) — what the receiver does with the invoice
forma_pago (c_FormaPago) — cash, transfer, card, …
metodo_pago (c_MetodoPago) — PUE vs PPD
tipo_comprobante (c_TipoDeComprobante) — I/E/T/N/P
objeto_imp (c_ObjetoImp) — whether a line item is subject to tax (CFDI 4.0)
impuestos (c_Impuesto) — ISR / IVA / IEPS
bancos_clabe — Banxico participants by the first three CLABE digits
estados_curp — RENAPO's state keys for CURP positions 12-13
With no query you get the whole catalogue. With one, an exact code match wins (leading zeros are ignored, so '1' finds '01'); failing that it falls back to a case- and accent-insensitive substring search over both code and label, so 'confianza' finds 626 and 'oaxaca' finds OC.
Two honesty notes carried in the output: the bank list is a curated subset of Banxico's participant catalogue rather than the whole thing, and the CURP state keys are RENAPO's own — they do not match INEGI or ISO 3166-2:MX codes.
Args:
catalog (enum): one of regimen_fiscal, uso_cfdi, forma_pago, metodo_pago, tipo_comprobante, objeto_imp, impuestos, bancos_clabe, estados_curp.
query (string, optional): an exact code, or text to search for.
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { catalog, official_name, authority, description, used_in, query, match_type, total_entries, match_count, entries[{code, label}], truncated, notes[] }.
Example: "What does UsoCFDI G03 mean?" -> sat_catalog_lookup(catalog="uso_cfdi", query="G03").
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | An exact code ('626', 'G03', '012') or free text to search ('confianza', 'BBVA', 'Oaxaca'). Omit for the whole catalogue. | |
| catalog | Yes | Which catalogue to read. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| query | Yes | |
| catalog | Yes | |
| entries | Yes | |
| used_in | Yes | |
| authority | Yes | |
| truncated | Yes | |
| match_type | Yes | |
| description | Yes | |
| match_count | Yes | |
| official_name | Yes | |
| total_entries | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read-only, offline, idempotent profile, and the description reinforces it ('never touches the network'). It then adds genuinely valuable data-provenance caveats beyond the structured fields: the bank list is a curated Banxico subset, and CURP state keys deliberately do not match INEGI or ISO 3166-2:MX codes — exactly the kind of trap an agent needs warned about.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose, then uses a scannable bulleted list for the catalogues and a compact paragraph for query behavior. The catalogue glossary is long but each line earns its place; only the 'Two honesty notes carried in the output' framing is slightly padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bounded, offline lookup with a declared output schema, the description covers everything an agent needs: the enum of catalogues, query resolution rules, output format choice, provenance caveats, and a concrete example call. Nothing required to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds matching semantics the schema omits: leading zeros are ignored ('1' finds '01') and the fallback is case- and accent-insensitive substring over both code and label. The match_type output field ties these rules to observable behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('look up') and resource ('the code tables a CFDI is written in'), then enumerates all nine catalogues with a one-line gloss of each. This distinguishes it from siblings like validate_rfc or parse_cfdi, which validate or parse rather than resolve reference codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly explains the two usage modes: no `query` returns the whole catalogue, a `query` does exact-then-substring matching, and it contrasts itself with 'downloading the SAT's spreadsheet' and 'never touches the network'. It stops short of explicitly naming when to reach for this over the validate_* siblings, so it is clear context rather than full alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate an 18-digit CLABE (Clave Bancaria Estandarizada, Banxico Circular 3/2012) — the account number every SPEI transfer in Mexico is addressed to — and name the bank behind it.
Structure: 3 digits of bank + 3 of plaza (city/branch) + 11 of account + 1 control digit.
The control digit is the part everybody gets wrong. The weights cycle 3-7-1, and each weighted product counts only its last digit (the product modulo 10): 9 × 7 = 63 counts as 3. Implementations that borrow the Luhn habit of adding the product's digits (6 + 3 = 9) compute a different control digit — for the base 09000000000000000 the algorithm gives 7 and the Luhn-style sum gives 1. (Reducing modulo 10 before or after summing gives the same result; that is not where they go wrong.) This uses the correct algorithm.
The bank code is resolved against a curated subset of Banxico's participant catalogue. A code that is not in the subset is reported as unknown rather than given an invented name. The plaza code is reported verbatim: the full plaza catalogue is not bundled, so no city is guessed.
Args:
value (string): the CLABE. Spaces and dashes are normalised away.
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { input, normalized, formatted, valid, parts{banco, plaza, cuenta, digito}, bank_code, bank_name, plaza_code, plaza_note, expected_check_digit, errors[{code, message}], findings[] }.
Example: "Which bank is CLABE 012180012345678903?" -> validate_clabe(value="012180012345678903").
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The CLABE to validate, e.g. '012180012345678903'. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| input | Yes | |
| parts | Yes | |
| valid | Yes | |
| errors | Yes | |
| findings | Yes | |
| bank_code | Yes | |
| bank_name | Yes | |
| formatted | Yes | |
| normalized | Yes | |
| plaza_code | Yes | |
| plaza_note | Yes | |
| expected_check_digit | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint, idempotentHint, and destructiveHint already declaring a safe read operation, the description goes further by disclosing the exact check-digit algorithm, the common Luhn-style error, the curated bank-catalogue limitation, and the decision not to guess plaza cities. This prevents false expectations and is strong behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured and front-loaded, with the purpose in the first sentence followed by clearly labeled Args, Returns, and an Example. The detailed control-digit explanation earns its place because it clarifies a common source of incorrect validation and explicitly states that this tool uses the correct algorithm.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations, full schema coverage, and an output schema, the description is complete for correct invocation. It covers edge-case behavior (unknown bank codes reported as unknown, plaza codes reported verbatim without guessing), normalization, and output-format selection, leaving no critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds meaningful parameter behavior: spaces and dashes are normalized away from `value`, and `response_format` is clarified as 'markdown' for a human-readable summary versus 'json' for the full structured payload. This goes beyond the bare schema definitions for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Validate an 18-digit CLABE' and extends the purpose to 'name the bank behind it.' It also gives domain context (Banxico Circular 3/2012, SPEI transfers) that clearly distinguishes this tool from the sibling validators like validate_rfc, validate_curp, and validate_nss.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual triggers: a CLABE is the account number for every SPEI transfer in Mexico, and the tool also resolves the bank, so an agent can infer appropriate use cases. It does not explicitly provide when-not-to-use guidance or name sibling alternatives, but the resource type is unique enough that the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a Mexican CURP (Clave Única de Registro de Población) — the 18-character population ID issued by RENAPO — and decode everything it encodes: birth date, sex, state of birth and the century marker.
The 18th character is a base-37 modulus-10 check digit over the first 17, and this checks it. Two details it gets right that a regex does not:
The state keys are RENAPO's own. 'DF' is Ciudad de México, 'MC' is Estado de México, 'NE' means born abroad. They do not match the INEGI or ISO 3166-2:MX codes, so a lookup against those tables silently mislabels people.
The homoclave character carries the century. A digit (position 17) means born before 2000; a letter means from 2000 onwards. Without it, positions 5-10 ('99' as a year) are ambiguous.
Names that would spell one of RENAPO's inconvenient words are flagged: a real CURP carries an X in the second position instead.
Structural validity is not registration. Only RENAPO can confirm a CURP belongs to a real person, and this server never asks it.
Args:
value (string): the CURP. Spaces, dashes and lower case are normalised away.
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { input, normalized, valid, parts{...}, birth_date, sex, sex_label, state_key, state_name, century_marker, expected_check_digit, errors[{code, message}], findings[] }.
Example: "Decode BOXW310820HNERXN09" -> validate_curp(value="BOXW310820HNERXN09").
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The CURP to validate, e.g. 'BOXW310820HNERXN09'. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| sex | Yes | |
| input | Yes | |
| parts | Yes | |
| valid | Yes | |
| errors | Yes | |
| findings | Yes | |
| sex_label | Yes | |
| state_key | Yes | |
| birth_date | Yes | |
| normalized | Yes | |
| state_name | Yes | |
| century_marker | Yes | |
| expected_check_digit | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe, idempotent, closed-world read, so the description correctly focuses on behavior beyond that: input normalization (spaces, dashes, lowercase stripped), the base-37 modulus-10 check-digit algorithm, and the explicit limitation that it never contacts RENAPO to confirm registration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then structured with bullets and an example. It is on the long side and the RENAPO-table trivia is dense, but every element (state keys, century marker, exclusion word X rule) aids correct interpretation, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained, yet the description still gives the decoded shape and an end-to-end example call. Nothing an agent needs to select or invoke this validator correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks — that the CURP value is normalised (spaces, dashes, case-insensitivity) before validation — plus a worked example input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (validate) and resource (Mexican CURP, defined as the 18-character RENAPO population ID) plus the secondary decode behavior. An agent can distinguish this from validate_clabe, validate_nss and validate_rfc purely from the resource named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the context clearly, including the crucial 'structural validity is not registration' caveat and the cases (state keys, century marker) where a naive regex approach fails. It does not explicitly name a sibling or state when-not-to-use, so it falls 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.
Validate an 11-digit NSS (Número de Seguridad Social) issued by the IMSS, and split it into its fields: 2 digits of subdelegación, 2 of the year the holder was registered, 2 of the year of birth, 4 of serial, and a Luhn check digit over the first ten.
The two year fields are informational only. The IMSS has issued numbers whose years do not line up with the holder's records, so a mismatch is not grounds to reject a number — only the check digit is.
Args:
value (string): the NSS. Spaces and dashes are normalised away.
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { input, normalized, valid, parts{subdelegacion, anioAlta, anioNacimiento, folio, digito}, expected_check_digit, errors[{code, message}], findings[] }.
Example: "Is 12345678903 a valid NSS?" -> validate_nss(value="12345678903").
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The NSS to validate, e.g. '92119624722'. | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| input | Yes | |
| parts | Yes | |
| valid | Yes | |
| errors | Yes | |
| findings | Yes | |
| normalized | Yes | |
| expected_check_digit | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (read-only, idempotent, non-destructive), but the description adds real behavioral context beyond them: spaces and dashes are normalized away before validation, and the two year fields are informational because IMSS-issued numbers can mismatch holder records — so only the check digit justifies rejection. That is the kind of edge-case semantics an agent could not infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded: purpose first, then field breakdown, then the rejection caveat, then args/returns/example. The explicit Returns block is partly redundant given a full output schema exists, but the overall structure is scannable and every other sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter validator with an output schema, nothing material is missing: it covers input normalization, output shape, the informational-field caveat, and a concrete invocation example. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a 3 is the baseline, but the description exceeds it by disclosing normalization of spaces and dashes in `value` and confirming the default of `response_format` to markdown. These details add meaning beyond the schema's terse parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — validate an 11-digit NSS issued by the IMSS — and distinguishes itself from the sibling validators (validate_curp, validate_rfc, validate_clabe) by document type. It further explains the internal structure of the identifier, making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the document type being validated, and the description gives genuinely useful domain guidance that only the check digit can invalidate a number. However, it never states when to reach for this tool versus a sibling validator or when a caller would already have a normalized value, so routing guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a Mexican RFC (Registro Federal de Contribuyentes) — the SAT taxpayer ID — and break it into its parts. Works for both shapes: 13 characters for a persona física (individual) and 12 for a persona moral (company).
The last character is a modulus-11 check digit over the preceding ones, and this checks it. Two SAT-issued generics are special-cased and reported as such:
XAXX010101000 (público en general) does NOT satisfy the check-digit algorithm — the arithmetic asks for a '4' where the SAT wrote a '0'. It is valid by decree, not by maths, which is exactly why so many home-grown validators wrongly reject invoices to the general public.
XEXX010101000 (residentes en el extranjero) DOES satisfy it on its own.
The tool reports is_generic and check_digit_satisfied separately so you never have to conflate the two.
Structural validity is not registration. A well-formed RFC may belong to nobody. Only the SAT can say whether one is registered and active, and this server never asks.
Args:
value (string): the RFC. Spaces, dashes and lower case are normalised away.
response_format ('markdown' | 'json'): output format (default 'markdown').
Returns: { input, normalized, valid, kind, is_generic, generic_note, parts{iniciales, fecha, homoclave, digito}, birth_date, expected_check_digit, check_digit_satisfied, errors[{code, message}], findings[] }.
Example: "Is GODE561231GR8 a valid RFC?" -> validate_rfc(value="GODE561231GR8").
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The RFC to validate, e.g. 'GODE561231GR8' (individual) or 'MAB9307148T4' (company). | |
| response_format | No | Output format: 'markdown' for a human-readable summary (default) or 'json' for the full structured payload. | markdown |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| input | Yes | |
| parts | Yes | |
| valid | Yes | |
| errors | Yes | |
| findings | Yes | |
| birth_date | Yes | |
| is_generic | Yes | |
| normalized | Yes | |
| generic_note | Yes | |
| expected_check_digit | Yes | |
| check_digit_satisfied | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavioral detail beyond them: modulus-11 check-digit verification, the two SAT generic special cases and why XAXX010101000 fails the arithmetic, input normalization, and the deliberate separation of is_generic from check_digit_satisfied. This is real disclosure an agent could not infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core operation, then bulletted special cases, then args and returns — well organized and scannable. Slightly long: the aside about home-grown validators wrongly rejecting invoices is editorial rather than operational.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, yet the description still gives the return shape and the meanings of the two easily-confused flags. Combined with the scope caveat and normalization note, an agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: spaces, dashes and lower case in `value` are normalised away, and the response_format default is restated with intent. The added normalization rule is not visible in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (validate) and resource (Mexican RFC / SAT taxpayer ID), and immediately disambiguates from sibling validators by naming the two RFC shapes (13-char persona física, 12-char persona moral). An agent can distinguish it from validate_curp/validate_clabe/validate_nss without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the scope boundary — 'Structural validity is not registration. Only the SAT can say whether one is registered and active' — which tells the agent this tool answers well-formedness, not status. It does not explicitly name a sibling to use instead for registration checks, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.2cfdi_status1 field changedOutput schema / properties / status / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "cancellable_meaning": {
- "type": "string"
- },
- "cancellable_state": {
- "enum": [
- "sin_aceptacion",
- "con_aceptacion",
- "no_cancelable",
- "unknown"
- ],
- "type": "string"
- },
- "cancellation_meaning": {
- "type": "string"
- },
- "cancellation_state": {
- "enum": [
- "cancelado_sin_aceptacion",
- "cancelado_con_aceptacion",
- "plazo_vencido",
- "en_proceso",
- "solicitud_rechazada",
- "ninguno"
- ],
- "type": "string"
- },
- "codigo_estatus": {
- "type": "string"
- },
- "document_meaning": {
- "type": "string"
- },
- "document_state": {
- "enum": [
- "vigente",
- "cancelado",
- "no_encontrado"
- ],
- "type": "string"
- },
- "efos_meaning": {
- "type": "string"
- },
- "efos_state": {
- "enum": [
- "not_listed",
- "listed",
- "unknown"
- ],
- "type": "string"
- },
- "es_cancelable": {
- "type": "string"
- },
- "estado": {
- "type": "string"
- },
- "estatus_cancelacion": {
- "type": "string"
- },
- "query_outcome": {
- "enum": [
- "found",
- "not_found"
- ],
- "type": "string"
- },
- "raw": {
- "additionalProperties": {
- "type": "string"
- },
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- },
- "validacion_efos": {
- "type": "string"
- }
- },
- "required": [
- "codigo_estatus",
- "query_outcome",
- "estado",
- "document_state",
- "document_meaning",
- "es_cancelable",
- "cancellable_state",
- "cancellable_meaning",
- "estatus_cancelacion",
- "cancellation_state",
- "cancellation_meaning",
- "validacion_efos",
- "efos_state",
- "efos_meaning",
- "raw"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "cancellable_meaning": {
+ "type": "string"
+ },
+ "cancellable_state": {
+ "enum": [
+ "sin_aceptacion",
+ "con_aceptacion",
+ "no_cancelable",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "cancellation_meaning": {
+ "type": "string"
+ },
+ "cancellation_state": {
+ "enum": [
+ "cancelado_sin_aceptacion",
+ "cancelado_con_aceptacion",
+ "plazo_vencido",
+ "en_proceso",
+ "solicitud_rechazada",
+ "ninguno"
+ ],
+ "type": "string"
+ },
+ "codigo_estatus": {
+ "type": "string"
+ },
+ "document_meaning": {
+ "type": "string"
+ },
+ "document_state": {
+ "enum": [
+ "vigente",
+ "cancelado",
+ "no_encontrado"
+ ],
+ "type": "string"
+ },
+ "efos_meaning": {
+ "type": "string"
+ },
+ "efos_state": {
+ "enum": [
+ "not_listed",
+ "listed",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "efos_third_party_state": {
+ "enum": [
+ "listed",
+ "not_listed",
+ "not_reported",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "es_cancelable": {
+ "type": "string"
+ },
+ "estado": {
+ "type": "string"
+ },
+ "estatus_cancelacion": {
+ "type": "string"
+ },
+ "query_outcome": {
+ "enum": [
+ "found",
+ "not_found"
+ ],
+ "type": "string"
+ },
+ "raw": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "validacion_efos": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "codigo_estatus",
+ "query_outcome",
+ "estado",
+ "document_state",
+ "document_meaning",
+ "es_cancelable",
+ "cancellable_state",
+ "cancellable_meaning",
+ "estatus_cancelacion",
+ "cancellation_state",
+ "cancellation_meaning",
+ "validacion_efos",
+ "efos_state",
+ "efos_third_party_state",
+ "efos_meaning",
+ "raw"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+]v1.0.0cfdi_statusgenerate_test_dataparse_cfdisat_catalog_lookupvalidate_clabevalidate_curpvalidate_nssvalidate_rfcScored across 8 tools
Each tool targets a distinct resource and action: validators are split by identifier type (CLABE, CURP, NSS, RFC), and the CFDI tools cleanly separate parsing, SAT status lookup, and catalogue lookup. Even the two CFDI tools are unambiguous because one explicitly parses XML while the other explicitly queries the SAT.
The four validators follow a consistent validate_<identifier> pattern, and parse_cfdi and generate_test_data also use verb_noun naming. However, cfdi_status and sat_catalog_lookup deviate from the pattern with noun-based or suffix-based names, creating minor inconsistency across the set.
Eight tools is a well-scoped count for a Mexican fiscal and identifier validation server. Each tool covers a meaningful operation, and none feel redundant or extraneous.
The server covers the core lifecycle for Mexican fiscal identifiers and CFDI invoices: validation, decoding, parsing, SAT status lookup, catalogue reference, and test data generation. Minor gaps exist, such as no digital signature verification for CFDI XML, but the primary validation use cases are well covered.
Official Mexican data for AI agents: CURP, RFC, CFDI, postal codes, phone, SPEI/CEP, DOF, geocoding.
Deterministic Mexican/LatAm verification + sanctions & PEP screening for AI agents. Pay via x402.
Mexico CFDI 4.0 invoices for AI agents - issue, query, cancel facturas via Facturapi.
Emite CFDIs 4.0 y resuelve claves del SAT para agentes de IA (México), con permisos por API key.
