Skip to main content
Glama

Validate invoice

validate_invoice
Read-onlyIdempotent

Validate a European e-invoice against official rule sets and receive a pass/fail report with error details, without returning the invoice body.

Instructions

Validate one European e-invoice against the official rule sets (XSD, EN 16931, XRechnung, Peppol BIS, FatturaPA, KSeF, arithmetic) and return the verdict without the invoice body. Use it for pass/fail and the list of errors and warnings; use read_invoice when you also need lines, totals and payment data. Input: XML (UBL, CII, XRechnung, Peppol BIS 3, FatturaPA, KSeF FA(2)/FA(3)) or a ZUGFeRD/Factur-X hybrid PDF up to 25 MB; plain or scanned PDFs without embedded XML are rejected (no OCR). Returns the validation report (valid flag, counts, rule sets with versions, failed rules with rule id, severity, fix hint in lang, affected field and who must act), the detected source and the document header; an unreadable file returns ok=false with error.code/message/hint instead of raising. Costs one invoice credit per call; without an API key the anonymous quota is 20 invoices per day per IP. Nothing is stored.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
langNoLanguage of the fix hints in the validation report and of the labels in HTML output. Default en.en
pathNoAbsolute path of the invoice file on the machine running the server, used instead of file_base64. Only honoured over stdio (`python -m invoicein.mcp_server`); the hosted server at invoicein-api.peculiar.systems ignores it and answers with an error asking for file_base64.
file_base64NoInvoice file content, base64-encoded (standard alphabet). Accepted content: XML in UBL 2.1, CII D16B, XRechnung, Peppol BIS Billing 3, FatturaPA 1.2 or KSeF FA(2)/FA(3) syntax, or a ZUGFeRD 1.0/2.x or Factur-X hybrid PDF (the embedded XML is used). Max 25 MB decoded. Required unless `path` is given.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYesFalse when the file could not be read; then only `error` is set
errorNoPresent when ok is false: code, message, hint
sourceNoDetected syntax, format, profile and container
documentNoInvoice header: id, issue_date, type_code, currency, due_date …
validationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changedv0.1.1
    • addedInput schema / properties / file_base64 / default
      Added value: +""
    • addedInput schema / properties / file_base64 / description
      Added value: +"Invoice file content, base64-encoded (standard alphabet). Accepted content: XML in UBL 2.1, CII D16B, XRechnung, Peppol BIS Billing 3, FatturaPA 1.2 or KSeF FA(2)/FA(3) syntax, or a ZUGFeRD 1.0/2.x or Factur-X hybrid PDF (the embedded XML is used). Max 25 MB decoded. Required unless `path` is given."
    • addedInput schema / properties / lang / description
      Added value: +"Language of the fix hints in the validation report and of the labels in HTML output. Default en."
    • addedInput schema / properties / lang / enum
      Added value: +[
      +  "en",
      +  "de",
      +  "pl",
      +  "it",
      +  "fr"
      +]
    • addedInput schema / properties / path
      Added value: +{
      +  "default": "",
      +  "description": "Absolute path of the invoice file on the machine running the server, used instead of file_base64. Only honoured over stdio (`python -m invoicein.mcp_server`); the hosted server at invoicein-api.peculiar.systems ignores it and answers with an error asking for file_base64.",
      +  "title": "Path",
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "file_base64"
      -]
    • addedOutput schema / $defs
      Added value: +{
      +  "Issue": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "field": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Affected canonical field with its EN 16931 BT/BG number",
      +        "title": "Field"
      +      },
      +      "hint": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Plain-language explanation of what the sender must fix, in the requested language",
      +        "title": "Hint"
      +      },
      +      "id": {
      +        "description": "Rule id, e.g. BR-CO-15, BR-DE-2, PEPPOL-EN16931-R040, XSD-UNEXPECTED-ELEMENT",
      +        "title": "Id",
      +        "type": "string"
      +      },
      +      "message": {
      +        "description": "The rule's own message",
      +        "title": "Message",
      +        "type": "string"
      +      },
      +      "severity": {
      +        "description": "error, warning or info",
      +        "title": "Severity",
      +        "type": "string"
      +      },
      +      "who": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Who has to act: sender or receiver",
      +        "title": "Who"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "severity",
      +      "message"
      +    ],
      +    "title": "Issue",
      +    "type": "object"
      +  },
      +  "SourceInfo": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "container": {
      +        "description": "xml or pdf",
      +        "title": "Container",
      +        "type": "string"
      +      },
      +      "format": {
      +        "description": "Detected format: xrechnung-ubl, xrechnung-cii, ubl, cii, peppol-bis3, zugferd, facturx, fatturapa, ksef-fa3, ksef-fa2",
      +        "title": "Format",
      +        "type": "string"
      +      },
      +      "profile": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Profile or specification, e.g. 'EN 16931', 'XRechnung 3.0', 'FA (3)'",
      +        "title": "Profile"
      +      },
      +      "syntax": {
      +        "description": "UBL, CII, FatturaPA or FA3",
      +        "title": "Syntax",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "syntax",
      +      "format",
      +      "container"
      +    ],
      +    "title": "SourceInfo",
      +    "type": "object"
      +  },
      +  "Validation": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "errors": {
      +        "description": "Number of failed rules with severity error",
      +        "title": "Errors",
      +        "type": "integer"
      +      },
      +      "issues": {
      +        "description": "Failed rules, each with a fix hint",
      +        "items": {
      +          "$ref": "#/$defs/Issue"
      +        },
      +        "title": "Issues",
      +        "type": "array"
      +      },
      +      "notes": {
      +        "description": "Informational notes about the validation run",
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Notes",
      +        "type": "array"
      +      },
      +      "rule_sets": {
      +        "description": "Rule sets applied, with versions (XSD, EN 16931, XRechnung, Peppol, FatturaPA, KSeF, arithmetic)",
      +        "items": {
      +          "additionalProperties": true,
      +          "type": "object"
      +        },
      +        "title": "Rule Sets",
      +        "type": "array"
      +      },
      +      "valid": {
      +        "description": "True when no rule of severity error failed",
      +        "title": "Valid",
      +        "type": "boolean"
      +      },
      +      "warnings": {
      +        "description": "Number of failed rules with severity warning",
      +        "title": "Warnings",
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "valid",
      +      "errors",
      +      "warnings",
      +      "rule_sets",
      +      "issues"
      +    ],
      +    "title": "Validation",
      +    "type": "object"
      +  }
      +}
    • addedOutput schema / additionalProperties
      Added value: +true
    • addedOutput schema / properties / document
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Invoice header: id, issue_date, type_code, currency, due_date …",
      +  "title": "Document"
      +}
    • addedOutput schema / properties / error
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Present when ok is false: code, message, hint",
      +  "title": "Error"
      +}
    • addedOutput schema / properties / ok
      Added value: +{
      +  "description": "False when the file could not be read; then only `error` is set",
      +  "title": "Ok",
      +  "type": "boolean"
      +}
    • removedOutput schema / properties / result
      Removed value: -{
      -  "title": "Result",
      -  "type": "string"
      -}
    • addedOutput schema / properties / source
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/SourceInfo"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Detected syntax, format, profile and container"
      +}
    • addedOutput schema / properties / validation
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/Validation"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "result"
      -]New value: +[
      +  "ok"
      +]
    • changedOutput schema / title
      Previous value: -"validate_invoiceOutput"New value: +"ValidateResult"
  2. First observedv0.1.0

TDQS

A5/5.0
Behavior5/5

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

The annotations already indicate read-only, idempotent behavior, and the description complements them with concrete behavioral details: nothing is stored, unreadable files return an error object rather than throwing, and hybrid PDFs use embedded XML. No contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence adds necessary operational context—validation scope, input formats, output summary, error behavior, and cost. No filler or redundant phrasing is present.

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?

Given the tool's complexity, the description covers accepted input syntaxes, output report components, language parameter, file delivery methods, error handling, and resource implications. It is sufficiently complete for an agent to invoke and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters are fully described in the schema. lang has an enum and default, path explains its platform-specific usage, and file_base64 details accepted content, size limits, and the fallback relationship to path. Schema coverage is 100%.

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 identifies the action—validating a European e-invoice against named rule sets—and explicitly states that the result is the verdict without the invoice body. It also contrasts with read_invoice, making the tool's purpose unambiguous.

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?

It explicitly explains when to use this tool versus read_invoice, lists accepted input formats, notes path vs. base64 behavior, and provides cost, quota, and storage details. This gives an agent direct guidance for selection and invocation.

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