mcp-fattura-elettronica-it

Generate Ubl Invoice

generate_ubl_invoice

Generate UBL 2.1 invoice XML from Italian invoice data for cross-border B2B or Peppol routing. Converts ItalianInvoice dict to standard UBL format, omitting FatturaPA-only fields.

Instructions

Generate a UBL 2.1 Invoice XML document from an ItalianInvoice dict.

Use this for cross-border B2B invoices or Peppol-routed documents. This tool does NOT produce FatturaPA XML; use generate_fattura_xml() for SdI submission.

Italian national fields (progressivo_invio, codice_destinatario, regime_fiscale) are accepted in the input dict but are not emitted in the UBL output — they belong in the FatturaPA DatiTrasmissione header.

profile (BT-24) should be the Peppol BIS Billing 3.0 customisation ID ('urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0') or the EN 16931 core profile ('urn:cen.eu:en16931:2017') for non-Peppol use. [Inference: FatturaPA-specific CIUS URN not yet standardised for UBL; verify with AdE if UBL submission to an IT-specific platform is intended.]

On success returns {'xml': str, 'length_bytes': int, 'format': 'UBL-2.1'}. On validation error returns {'error': str, 'details': list[str]}. On unexpected error returns {'error': str}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`invoice_data`	Yes	ItalianInvoice-compatible dict to serialise to UBL 2.1 XML. Required top-level fields: profile (str, BT-24 customisation ID), invoice_number (str), invoice_date (ISO 8601 date string), invoice_type_code (str, '380' invoice / '381' credit note), currency_code (str, 'EUR'), seller (dict with name, address), buyer (dict with name, address), line_items (list of line dicts), tax_lines (list of tax dicts), sum_of_line_net_amounts, tax_exclusive_amount, tax_total, tax_inclusive_amount, amount_due (all Decimal-compatible strings or numbers). Optional: note, buyer_reference, payment_means, due_date, progressivo_invio, codice_destinatario, regime_fiscale. address fields: line_one, city, postcode, country_code (2-char ISO). party fields: name (str), vat_id (optional, with country prefix, e.g. 'IT01234567890'). line fields: line_id, name, quantity, unit_code, unit_price, line_net_amount, tax_category (UNCL5305, e.g. 'S'), tax_rate (%, e.g. 22). tax fields: category, rate, taxable_amount, tax_amount.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.5Jun 7, 2026

TDQS

A4.5/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses what is not emitted (FatturaPA-specific fields are omitted), which is key behavioral context. It states that those fields are ignored in output, which is helpful. It also specifies the return structure for success and error cases, which is important. However, it does not mention any rate limits, idempotency, or whether the input is mutated (though unlikely, no explicit statement). Given the absence of annotations, it does a solid job but could add a note on side effects (none expected) and error handling details.

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?

The description is quite long but every sentence earns its place. It starts with the core purpose, then explains usage context, exclusions, profile details, and return structure. It is structured with clear paragraphs, front-loading the main action. A slight trimming could be done, but the length is justified by the complexity of the tool's domain. Not overly verbose.

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

Completeness4/5

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

Given the complexity of the tool (nested objects, many fields), the description covers the main aspects: input type, profile selection, field exclusions, and return structure. It does not explain the full schema of nested objects, but the schema already does that with 100% coverage. The output schema is not provided, but the description fills that gap. It could benefit from mentioning error scenarios like XSD validation failures, but overall it is adequate.

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 provides 100% parameter description coverage. The description adds value by clarifying the profile field's purpose and listing specific example values, and by explicitly noting which fields are ignored in UBL output. It also explains the structure of the return value, which is not in the schema since no output schema is given. This compensates beyond schema schema, so a 4 is justified.

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 precisely the action (generate a UBL 2.1 Invoice XML), the input type (ItalianInvoice dict), and the output format. It differentiates from siblings by explicitly noting it does not produce FatturaPA XML, pointing to generate_fattura_xml for SdI, and mentions CII as a sibling for comparison, though not explicitly. The verb+resource is specific, and the exclusion of FatturaPA clarifies its role in the tool family.

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?

Explicitly states when to use: for cross-border B2B invoices or Peppol-routed documents. Provides clear exclusion: does not produce FatturaPA XML, use generate_fattura_xml() for SdI submission. Also advises on profile selection for Peppol vs EN 16931, and even includes an inference note about FatturaPA-specific CIUS not being standardised, with a verification recommendation. This is exemplary guidance.

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

Deploy Server