mcp-fattura-elettronica-it

Build Dati Generali

build_dati_generali

Create the mandatory DatiGenerali block for Italian e-invoices by validating document type, date, and number before XML generation.

Instructions

Build the DatiGenerali block required in every FatturaElettronicaBody.

Use this as step 6 in the invoice generation workflow, after validate_cessionario() and before add_linea_dettaglio(). Call get_tipo_documento_codes() first to select the correct TD code (most invoices use TD01; credit notes use TD04; professional fee invoices use TD06).

For credit notes (TD04) or debit notes (TD05), set id_documento_riferimento to the original invoice number and data_documento_riferimento to its issue date.

Validates: tipo_documento must be a valid TD01–TD28 code; data must be YYYY-MM-DD; numero must not exceed 20 characters.

On success returns {'DatiGenerali': {...}} ready for generate_fattura_xml(). On failure returns {'error': ''}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`data`	Yes	Invoice date in ISO 8601 format (YYYY-MM-DD), e.g. '2026-01-15'. Must not be a future date for ordinary invoices.
`divisa`	No	ISO 4217 currency code. Default 'EUR'. Other currencies for cross-border invoices.	EUR
`numero`	Yes	Invoice number (Numero), max 20 alphanumeric chars. Must be unique and sequential per fiscal year.
`causale`	No	Free-text description/reason for the invoice (Causale), max 200 chars each. Pass a single string or a list of strings for multiple Causale elements. The XSD allows maxOccurs='unbounded'.
`tipo_documento`	Yes	Document type code TD01–TD28. Use get_tipo_documento_codes() for the full list. Most invoices use TD01 (standard invoice).
`rif_numero_linea`	No	Line number reference for credit/debit notes linking back to the original invoice.
`id_documento_riferimento`	No	Number of the original invoice (for credit notes TD04, debit notes TD05, etc.).
`data_documento_riferimento`	No	Date of the original invoice (YYYY-MM-DD), for TD04/TD05.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.7.0Aug 21, 2026

changedInput schema / properties / causale / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / causale / description

Previous value: -"Optional free-text description/reason for the invoice (Causale), max 200 chars. Can appear multiple times — pass a single string here."New value: +"Free-text description/reason for the invoice (Causale), max 200 chars each. Pass a single string or a list of strings for multiple Causale elements. The XSD allows maxOccurs='unbounded'."

First observedv0.2.0Apr 28, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations, the description carries the full behavioral burden. It discloses validation rules (TD01–TD28, YYYY-MM-DD, 20-char limit), condition-specific behavior for TD04/TD05, and a precise success/error return contract. This goes well beyond the schema and gives the agent a clear model of what the tool will do.

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 longer than minimal, but every section earns its place: purpose, workflow step, TD-code selection, credit-note behavior, validation rules, and return contract. It is front-loaded with the core purpose and workflow context, though some validation details duplicate what the schema already states.

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?

Covers purpose, position in the larger workflow, prerequisite calls, conditional parameter behavior, validation constraints, and return values. Given the output schema exists and the schema describes all 8 parameters, nothing an agent needs to call this tool 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?

Input schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how to choose TD codes (TD01/TD04/TD06), when to populate id_documento_riferimento and data_documento_riferimento, and how the reference fields relate to credit/debit notes. This is meaningful semantic guidance, not just schema restatement.

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 action and resource: 'Build the DatiGenerali block required in every FatturaElettronicaBody.' It clearly differentiates this from sibling builders like build_dati_pagamento and build_transmission_header by naming the exact XML block it produces and its role in the invoice workflow.

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?

Gives explicit workflow placement: 'Use this as step 6... after validate_cessionario() and before add_linea_dettaglio().' It also instructs to call get_tipo_documento_codes() first. It does not explicitly state when NOT to use this tool or name an alternative builder, so it falls one step short of full exclusion guidance.

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

Deploy Server