Skip to main content
Glama

Attestwire

by com.attestwire
OverviewDiscussionsAdmin

Validate an invoice file: UBL or CII XML, or a Factur-X / ZUGFeRD PDF

validate_invoice_xml
Read-onlyIdempotent

Validate an e-invoice FILE the user already has: a UBL 2.1 Invoice, a UBL 2.1 CreditNote, a UN/CEFACT CII CrossIndustryInvoice (invoices and credit notes alike), or a Factur-X or ZUGFeRD PDF. The file is read into the invoice model and EN 16931 plus the CIUS rules (XRechnung UBL and CII, Peppol BIS 3) run over it, returning the same teaching errors as validate_invoice, plus which syntax it read, the document's BT-24/BT-23 and unmapped: everything in the file that did not reach the model. Use it when someone says "this invoice was rejected, why?" and hands you a file. Send the file as-is; do not work out the syntax or the document type first, because the tool decides both and reports them. XML goes in xml, as text. A PDF goes in pdf_base64, as the file's bytes base64-encoded, never pasted as text (the whole call is capped at 1 MB, so about 750 KB of PDF; larger files go to POST /v1/validate as application/pdf). The XML attached to the PDF is judged the same way, and the attachment and XMP metadata are checked too, as AW-PDF-* warnings and information that do not change valid; PDF/A conformance and whether the page agrees with the XML are not checked. Keyless, with no upload: npx @attestwire/en16931 validate invoice.pdf. A credit note is NOT refused — send it exactly like an invoice. It is a pre-flight, not an authority: a file that passes here can still be rejected by KoSIT or by a receiving platform, so say so, and pass on the unmapped list, where an entry of kind "unknown" is content the rules never saw. REQUIRES AN API KEY and costs 1 document.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
xmlNoAn XML file: the complete document, as text — the file contents, not a path. Its root element must be <Invoice> in the UBL Invoice-2 namespace, <CreditNote> in the UBL CreditNote-2 namespace, or <CrossIndustryInvoice> in the UN/CEFACT CII namespace. Exactly one of xml or pdf_base64.
pdf_base64NoA Factur-X or ZUGFeRD PDF: the file's bytes, base64-encoded (a data: URL prefix and line breaks are fine). Exactly one of xml or pdf_base64.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / pdf_base64
      Added value: +{
+  "description": "A Factur-X or ZUGFeRD PDF: the file's bytes, base64-encoded (a data: URL prefix and line breaks are fine). Exactly one of xml or pdf_base64.",
+  "type": "string"
+}
    • changedInput schema / properties / xml / description
      Previous value: -"The complete document, as text — the file contents, not a path. Its root element must be <Invoice> in the UBL Invoice-2 namespace, <CreditNote> in the UBL CreditNote-2 namespace, or <CrossIndustryInvoice> in the UN/CEFACT CII namespace. Not the bytes of a PDF."New value: +"An XML file: the complete document, as text — the file contents, not a path. Its root element must be <Invoice> in the UBL Invoice-2 namespace, <CreditNote> in the UBL CreditNote-2 namespace, or <CrossIndustryInvoice> in the UN/CEFACT CII namespace. Exactly one of xml or pdf_base64."
    • removedInput schema / properties / xml / minLength
      Removed value: -1
    • removedInput schema / required
      Removed value: -[
-  "xml"
-]
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already mark readOnly/idempotent, and the description adds substantial behavior beyond that: it is a 'pre-flight, not an authority', it returns an `unmapped` list, it does not check PDF/A or page agreement, credit notes are accepted, AW-PDF warnings do not affect `valid`, and it requires an API key and costs 1 document. This gives the agent a clear operational model.

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

Conciseness3/5

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

The description is rich but crowded into one long paragraph. Most details earn their place, but the mid-description 'Keyless, with no upload: npx @attestwire/en16931 validate invoice.pdf' interjection is off-topic for an API tool and clashes with the later 'REQUIRES AN API KEY', which weakens clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining what the agent will get back: teaching errors, detected syntax, BT-24/BT-23, and unmapped content. It also covers input constraints, caveats about rejection by KoSIT/platforms, exclusions, and credit-note handling. Nothing essential 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?

The schema already documents both parameters fully at 100% coverage, including root namespaces and base64 encoding. The description adds actionable constraints not in the schema: the whole call is capped at 1 MB, a PDF is limited to about 750 KB, XML must be sent as text, and PDF bytes must never be pasted as text.

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 opens with a specific verb and resource: 'Validate an e-invoice FILE the user already has' and enumerates the accepted formats (UBL 2.1 Invoice/CreditNote, CII, Factur-X/ZUGFeRD). It also distinguishes itself from the sibling by name, saying it returns 'the same teaching errors as validate_invoice' plus syntax, BT-24/BT-23, and unmapped data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

It gives an explicit trigger: use it when someone says 'this invoice was rejected, why?' and hands you a file. It also tells the agent not to pre-detect syntax or document type and routes larger PDFs to POST /v1/validate. It does not fully contrast with the sibling validate_invoice or diagnose_invoice, so it stops 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.

All Attestwire toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources