mcp-fattura-elettronica-it

Add Allegato

add_allegato

Adds a supporting document (PDF, XML, DDT, etc.) to an Italian e-invoice by converting base64 content into an Allegati entry. Use once per file and pass the results to generate_fattura_xml().

Instructions

Build an Allegati (attachment) entry to include in a FatturaPA document.

Use this when you need to attach supporting documents (e.g. DDT, contract, PDF) to the invoice. Call once per file, collect results in a list, and pass it to generate_fattura_xml() as the allegati parameter.

attachment_base64 must be valid standard base64 (RFC 4648); the tool verifies decodability. nome_allegato must include the file extension (e.g. 'contract.pdf'). formato_allegato (e.g. 'PDF', 'XML', 'ZIP') is optional but recommended for recipients to identify the content without decoding.

On success returns {'Allegati': {'NomeAllegato', 'Attachment', 'size_bytes', ...}}. On failure returns {'error': ''} (invalid base64 or name > 60 chars).

Input Schema

TableJSON Schema

Name	Required	Description
`nome_allegato`	Yes	Attachment file name (NomeAllegato), max 60 chars. Include the extension (e.g. 'contract.pdf', 'ddt_001.pdf').
`formato_allegato`	No	MIME type or format description (FormatoAllegato), max 10 chars. Examples: 'PDF', 'XML', 'ZIP'. Optional but recommended.
`attachment_base64`	Yes	Base64-encoded content of the attachment. Any binary file is accepted; common formats: PDF, XML, JPG, ZIP.
`descrizione_allegato`	No	Short description of the attachment content, max 100 chars. Optional.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Apr 28, 2026

TDQS

A4.9/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden. It discloses valid base64 verification, the name length constraint, the need for a file extension, and both success and failure return shapes. This is sufficient transparency for a build/transform tool.

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-organized into purpose, usage, parameter constraints, and return behavior. Every sentence contributes useful information, and the most important guidance appears first. No redundant filler exists.

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?

For a tool with four parameters and no annotations, the description covers the full lifecycle: why to use it, how to call it, what validation occurs, and what the success and error responses look like. An agent has enough information to invoke it correctly and integrate the result into generate_fattura_xml().

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 covers all four parameters, so the baseline is 3. The description adds useful semantics beyond the schema: base64 must be RFC 4648 and is verified, nome_allegato must include the extension, and formato_allegato is recommended for recipient identification. This pushes it above baseline.

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 plus resource: 'Build an Allegati (attachment) entry to include in a FatturaPA document.' This clearly identifies the tool's role and distinguishes it from sibling tools like add_linea_dettaglio or build_dati_generali, which serve different parts of the invoice.

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 says 'Use this when you need to attach supporting documents' and gives a precise call pattern: 'Call once per file, collect results in a list, and pass it to generate_fattura_xml() as the allegati parameter.' This gives an agent actionable guidance on exactly when and how to invoke it.

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

Deploy Server