Skip to main content
Glama

Validate an e-invoice

validate_invoice
Read-onlyIdempotent

Checks an e-invoice XML or Factur-X/ZUGFeRD PDF against official XSD, EN 16931 Schematron and XRechnung or Peppol rules offline, reporting each failed rule before you send or accept it.

Instructions

Checks an e-invoice against the official rule sets on this machine: the XSD, the EN 16931 Schematron from CEN, and the KoSIT XRechnung or Peppol BIS rules when the document declares them. Use it before sending an invoice you created and when you receive one. To read the invoice's data use parse_invoice; to explain one failed rule in depth use explain_validation_rule. Accepts XML or a Factur-X / ZUGFeRD PDF, whose embedded XML is checked; syntax and profile are detected from the document. A valid result means the listed ruleSets passed, not that a tax authority or buyer will accept the invoice, so report which rule sets ran and never claim more. Each failure carries the publisher's message and, for common rules, a plain-language fix. Input that is not an invoice comes back as an error result, not as invalid. The check runs offline; nothing is uploaded.

Input Schema

NameRequiredDescriptionDefault
xmlNoThe invoice as XML text (CII, UBL Invoice/CreditNote, XRechnung, Peppol BIS). Provide this OR pdfBase64.
xsdNoRun XSD validation too. Default true.
countryNoAdd a country layer: "FR" runs the French CTC rules (CII only); "DE" reports whether the profile is acceptable for German B2B (MINIMUM and BASIC WL are not).
profileNoForce the rule set instead of reading it from BT-24.
pdfBase64NoA Factur-X / ZUGFeRD PDF/A-3 as base64; the embedded XML is used. Provide this OR xml.

Output Schema

NameRequiredDescriptionDefault
xsdYesXML Schema check.
validYesTrue only when no error-level rule failed, the XSD did not fail, and no error-level notice was raised.
originYesWhether the input was XML or a PDF.
noticesYesFindings about the document that are not Schematron rules, e.g. an unrecognised profile, or (with country DE) a profile not acceptable for German B2B. An error-level notice makes valid false.
detectedYesWhat the document declares about itself.
failuresYesError-level rules that failed; any entry makes valid false.
ruleSetsYesExactly the rule sets that ran. Report these; do not claim checks that are not listed.
advisoriesYesWarning or info rules that fired; they do not make the invoice invalid.
firedCountYesSchematron rules that fired across all rule sets.
embeddedFilenameNoPDF only: name of the embedded XML that was checked.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedOutput schema / properties / failures / items / properties / element
      Added value: +{
      +  "description": "The offending element without namespaces, e.g. LineTotalAmount.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / failures / items / properties / line
      Added value: +{
      +  "description": "1-based invoice line number when the node is inside an invoice line.",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / failures / items / properties / path
      Added value: +{
      +  "description": "A short readable path, e.g. \"line 1 > NetPriceProductTradePrice > ChargeAmount\". xpath is the exact location.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / failures / items / properties / plainLanguage / description
      Previous value: -"Plain-language explanation and fix, present for common rules."New value: +"Plain-language explanation and fix, present for common rules and for the syntax rules (CII-DT, CII-SR, UBL-CR, UBL-DT, UBL-SR)."
  2. Changed36 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"Add a country layer on top of EN 16931."New value: +"Add a country layer: \"FR\" runs the French CTC rules (CII only); \"DE\" reports whether the profile is acceptable for German B2B (MINIMUM and BASIC WL are not)."
    • addedOutput schema / properties / advisories / description
      Added value: +"Warning or info rules that fired; they do not make the invoice invalid."
    • addedOutput schema / properties / detected / description
      Added value: +"What the document declares about itself."
    • addedOutput schema / properties / detected / properties / businessProcess / description
      Added value: +"BT-23 business process, when present."
    • addedOutput schema / properties / detected / properties / customizationId / description
      Added value: +"The BT-24 specification identifier as written in the document."
    • addedOutput schema / properties / detected / properties / profile / description
      Added value: +"Profile read from BT-24: en16931, xrechnung, peppol, extended, minimum, basicwl or unknown."
    • addedOutput schema / properties / detected / properties / syntax / description
      Added value: +"cii, ubl-invoice or ubl-credit-note."
    • addedOutput schema / properties / detected / properties / variant / description
      Added value: +"XRechnung only: standard, extension or cvd."
    • addedOutput schema / properties / embeddedFilename / description
      Added value: +"PDF only: name of the embedded XML that was checked."
    • addedOutput schema / properties / failures / description
      Added value: +"Error-level rules that failed; any entry makes valid false."
    • addedOutput schema / properties / failures / items / properties / fields / description
      Added value: +"BT and BG ids named in the official message, in order."
    • addedOutput schema / properties / failures / items / properties / message / description
      Added value: +"The publisher's own message for this rule."
    • addedOutput schema / properties / failures / items / properties / plainLanguage / description
      Added value: +"Plain-language explanation and fix, present for common rules."
    • addedOutput schema / properties / failures / items / properties / plainLanguage / properties / fix / description
      Added value: +"How to change the invoice so the rule passes."
    • addedOutput schema / properties / failures / items / properties / plainLanguage / properties / summary / description
      Added value: +"What the rule requires, in plain language."
    • addedOutput schema / properties / failures / items / properties / plainLanguage / properties / why / description
      Added value: +"Why the rule exists or why it typically fires."
    • addedOutput schema / properties / failures / items / properties / ruleId / description
      Added value: +"Rule id from the publisher, e.g. BR-CO-15 or BR-DE-15."
    • addedOutput schema / properties / failures / items / properties / ruleSet / description
      Added value: +"Id of the rule set the rule belongs to (see ruleSets)."
    • addedOutput schema / properties / failures / items / properties / severity / description
      Added value: +"error and fatal fail the invoice; warning and info do not. Effective level after the publisher's own re-levelling."
    • addedOutput schema / properties / failures / items / properties / xpath / description
      Added value: +"Where in the XML the rule fired."
    • addedOutput schema / properties / notices / description
      Added value: +"Findings about the document that are not Schematron rules, e.g. an unrecognised profile, or (with country DE) a profile not acceptable for German B2B. An error-level notice makes valid false."
    • addedOutput schema / properties / origin / description
      Added value: +"Whether the input was XML or a PDF."
    • addedOutput schema / properties / ruleSets / description
      Added value: +"Exactly the rule sets that ran. Report these; do not claim checks that are not listed."
    • addedOutput schema / properties / ruleSets / items / properties / advisory / description
      Added value: +"Warning or info rules that fired without failing the invoice."
    • addedOutput schema / properties / ruleSets / items / properties / failed / description
      Added value: +"Error-level rules that failed."
    • addedOutput schema / properties / ruleSets / items / properties / fired / description
      Added value: +"Rules of this set that applied to the document."
    • addedOutput schema / properties / ruleSets / items / properties / id / description
      Added value: +"Rule set id, e.g. en16931-cii or xrechnung-cii."
    • addedOutput schema / properties / ruleSets / items / properties / label / description
      Added value: +"Human-readable name."
    • addedOutput schema / properties / ruleSets / items / properties / source / description
      Added value: +"Publisher and version of the official artefact that ran."
    • addedOutput schema / properties / valid / description
      Added value: +"True only when no error-level rule failed, the XSD did not fail, and no error-level notice was raised."
    • addedOutput schema / properties / xsd / description
      Added value: +"XML Schema check."
    • addedOutput schema / properties / xsd / properties / errors / description
      Added value: +"XSD errors, empty when valid."
    • addedOutput schema / properties / xsd / properties / ran / description
      Added value: +"Whether XSD validation ran."
    • addedOutput schema / properties / xsd / properties / schema / description
      Added value: +"The XSD used."
    • addedOutput schema / properties / xsd / properties / skippedReason / description
      Added value: +"Why XSD did not run, when it did not."
    • addedOutput schema / properties / xsd / properties / valid / description
      Added value: +"XSD verdict, when it ran."
  3. First observedv0.2.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, and the description still adds substantial context: rule-set detection from the document, that `valid` only means the listed `ruleSets` passed and implies no tax-authority acceptance, that non-invoice input yields an error rather than an invalid verdict, and that the check is offline with no upload. This is exactly the kind of scope-limiting detail annotations cannot convey.

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?

Purpose is front-loaded and each sentence carries information — the valid/ruleSets caveat and the error-vs-invalid distinction are high-value. It is somewhat dense and the accepted-input sentence sits mid-paragraph rather than next to the purpose, but nothing is filler.

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?

An output schema exists, so return values needn't be explained, yet the description still pre-empts the main misinterpretation risk (over-claiming acceptance) and notes that failures carry the publisher's message plus plain-language fixes. Nothing an agent needs in order to call it and report results correctly is missing.

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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it clarifies that syntax and profile are auto-detected unless overridden, and that for a Factur-X/ZUGFeRD PDF the embedded XML is what gets checked. The remaining parameters (xsd, country) are left entirely 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 — checking an e-invoice against named rule sets (XSD, EN 16931 Schematron, KoSIT XRechnung/Peppol BIS) — and explicitly distinguishes itself from parse_invoice and explain_validation_rule. An agent can identify the tool 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 Guidelines5/5

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

Gives explicit when-to-use guidance (before sending an invoice you created, and when receiving one) and names both alternatives with the condition that selects them. No inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.