mcp-fattura-elettronica-it

Validate Cessionario

validate_cessionario

Validate buyer data and build the CessionarioCommittente block for Italian FatturaPA e-invoices. Checks required tax identifiers and legal name fields, flagging errors that would cause rejection.

Instructions

Validate and build the CessionarioCommittente (buyer) block for FatturaPA.

Use this as step 5 in the invoice generation workflow, after validate_cedente_prestatore() and before build_dati_generali().

Validates: either denominazione or both nome+cognome must be provided (mutually exclusive); at least one tax identifier (id_codice with id_paese, or codice_fiscale) is required; id_codice requires id_paese to be set.

Italian B2C buyers with only a CodiceFiscale: set codice_fiscale and leave id_paese/id_codice empty. Foreign B2B buyers: set id_paese + id_codice. For B2G invoices (FPA12): routing to the Public Administration is via a 6-char IPA office CodiceDestinatario in build_transmission_header(), not via this tool — look up the code at https://www.indicepa.gov.it.

Gruppo IVA (VAT-group) buyers: when id_paese/id_codice are omitted and codice_fiscale is an 11-digit (company-format) code, this may be a VAT-group's own CF rather than a participating member's. SdI rejects that combination with scarto code 00327 (see mcp_fattura_elettronica_it.sdi.notifications. SCARTO_CODE_REFERENCE) — this tool cannot validate VAT-group membership offline, so it only warns on the detectable structural precondition (IdFiscaleIVA absent

11-digit codice_fiscale); the returned 'warnings' list flags this case. Confirm codice_fiscale identifies the specific member company, not the group itself.

On success returns {'CessionarioCommittente': {...}} ready for generate_fattura_xml(), plus 'warnings' (list[str]) when the 00327 structural precondition is detected. On failure returns {'error': ''} listing all issues joined by '; '.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cap`	No	Postal code of the buyer.
`nome`	No	First name of the buyer (natural person).
`comune`	No	City of the buyer.
`cognome`	No	Last name of the buyer (natural person).
`nazione`	No	ISO country code of the buyer.	IT
`id_paese`	No	ISO country code for IdFiscaleIVA. Required for VAT-registered buyers. Omit for Italian buyers identified only by CodiceFiscale.
`id_codice`	No	VAT number of the buyer. Required if id_paese is provided.
`indirizzo`	No	Street address of the buyer.
`denominazione`	No	Company name of the buyer. Mutually exclusive with nome+cognome.
`codice_fiscale`	No	Italian fiscal code (16-char alphanumeric for individuals, 11-digit numeric for companies). Alternative to IdFiscaleIVA.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.7.0Aug 21, 2026

removedInput schema / properties / codice_ufficio

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "IPA office code (CodiceUfficio) for B2G invoices (FPA12 format). Required for all invoices addressed to a Public Administration (PA). 6-character code from the IPA registry (https://www.indicepa.gov.it). Absence causes SdI routing rejection for FPA12 invoices."
-}

Changed1 schema field changedv0.2.4May 23, 2026

addedInput schema / properties / codice_ufficio

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "IPA office code (CodiceUfficio) for B2G invoices (FPA12 format). Required for all invoices addressed to a Public Administration (PA). 6-character code from the IPA registry (https://www.indicepa.gov.it). Absence causes SdI routing rejection for FPA12 invoices."
+}

First observedv0.2.0Apr 28, 2026

TDQS

A4.7/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, and it does a strong job. It discloses validation rules, success/failure outputs, and the specific limitation regarding VAT-group membership (only warns on structural precondition). It mentions the SdI scarto code 00327 and the warning list behavior. The only slight gap is that it doesn't explicitly state the tool is read-only or if it has side effects, but given it's a validator/builder, this is inferred. It also doesn't detail the 'warnings' list beyond the one case, which is acceptable given the output schema.

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 well-structured: it starts with a one-line summary, then provides workflow context, validation rules, specific use-case guidance, a VAT-group caveat, and finally output expectations. Each section is concise and front-loaded with the most important information. The use of bullet-like separation (though not formatted as bullets) makes it scannable. Every sentence adds value, and there is no redundancy with the schema, which is efficient.

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?

This tool has 10 parameters, no annotations, and is part of a complex workflow (FatturaPA generation). The description provides comprehensive context: when to invoke it, what it validates, how to handle different buyer types, the VAT-group caveat, and what output to expect. It also references related resources (like the IPA website and scarto code reference) that an agent might need. Given the output schema is present, the return values are explained. This is highly complete for the tool's complexity.

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 description coverage is 100%, so the schema already documents each parameter's format and constraints. The description adds value by explaining the mutual exclusivity of denominazione vs nome+cognome, the relationship between id_paese and id_codice, and when to use codice_fiscale. It also provides field-level usage guidance for specific scenarios (e.g., B2C vs B2B). This goes beyond the schema's per-field descriptions, which are more terse, but the schema already carries most of the meaning, so a 4 is appropriate rather than a 5.

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 states the tool's purpose: to validate and build the buyer block for FatturaPA. It identifies the specific resource (CessionarioCommittente) and the action (validate and build), which is distinct from sibling tools like validate_cedente_prestatore that handle the seller block. The description also mentions the output structure, further clarifying its role.

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?

The description explicitly positions this tool as step 5 in the workflow, naming the preceding and following sibling tools (validate_cedente_prestatore and build_dati_generali). It also provides detailed use-case scenarios: Italian B2C buyers, foreign B2B buyers, B2G (FPA12) routing to a different tool, and VAT-group edge cases with specific guidance. It clearly states what this tool does NOT handle (IPA code lookup) and directs to build_transmission_header instead.

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

Deploy Server