mcp-fattura-elettronica-it

Lookup Codice Destinatario

lookup_codice_destinatario

Validate SDI recipient code or PEC address format to determine routing type (SDI_CODE or PEC) before building transmission headers.

Instructions

Validate the format of a CodiceDestinatario (SDI recipient code) or PEC address.

Call this before build_transmission_header() to confirm the recipient routing type and that the code or PEC address is correctly formatted. At least one of codice or pec must be provided.

Routing rules:

codice is 6 alphanumeric chars (e.g. 'A1B2C3') → routing_type: 'SDI_CODE' (PA/IPA, FPA12)
codice is 7 alphanumeric chars (e.g. 'X1Y2Z3W') → routing_type: 'SDI_CODE' (B2B intermediary, FPR12)
codice is '0000000' (7 zeros) → routing_type: 'PEC'; pec_destinatario is then mandatory in build_transmission_header()
pec only (no codice) → validates email format, routing_type: 'PEC'

IPA note: 6-char = IPA code (PA), 7-char = B2B intermediary code (FPR12 routing). PA office codes can be looked up at https://www.indicepa.gov.it. This tool performs format validation only, no live query against the SDI SOAP directory service or the IPA registry (planned for a future release).

Per-channel cap (reference only, not enforced here — this tool validates the format of a single code, not channel-wide allocation): per AdE Specifiche Tecniche 1.9.1 (in force 2026-05-15), an accredited reception channel (WS or SFTP) may request a maximum of 300 CodiceDestinatario codes via the Sistema di Accreditamento once it has passed to production. This cap is unrelated to, and does not change, the per-invoice 6/7-character format validated above.

On success returns a dict with 'routing_type', 'codice_destinatario' and/or 'pec_destinatario', and a 'note' with usage guidance. On invalid input returns {'error': ''}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`pec`	No	PEC address to validate format (user@domain.ext). When a PEC is provided, CodiceDestinatario must be '0000000'.
`codice`	No	SDI CodiceDestinatario to look up: 6-char alphanumeric for PA offices (IPA code, FPA12 B2G invoices), 7-char alphanumeric for B2B intermediaries (FPR12), or '0000000' (7 zeros) for PEC routing. IPA codes can be verified at https://www.indicepa.gov.it.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.2.4May 23, 2026

changedInput schema / properties / codice / description

Previous value: -"6-character alphanumeric SDI CodiceDestinatario to look up. Special value '0000000' (7 zeros) indicates PEC routing."New value: +"SDI CodiceDestinatario to look up: 6-char alphanumeric for PA offices (IPA code, FPA12 B2G invoices), 7-char alphanumeric for B2B intermediaries (FPR12), or '0000000' (7 zeros) for PEC routing. IPA codes can be verified at https://www.indicepa.gov.it."

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?

With no annotations provided, the description carries the full burden. It reveals it performs format validation only, not live queries, lists the return format on success and error, and even includes a disclaimer about the 300-code cap being unrelated. This level of detail is exemplary for a tool with no annotations.

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 section serves a purpose: validation scope, routing rules, IPA note, disclaimer, and return format. The core usage is front-loaded, and the Per-channel cap paragraph is clearly marked as reference-only, minimizing confusion. Slight over-length keeps it from a 5.

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 validation tool with complex routing logic and an output schema, the description covers all necessary bases: what it validates, how to decide between parameters, return structure, and caveats. Given the output schema exists and describes the return dict, no critical gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds critical meaning beyond the schema: it explains the two optional parameters are mutually exclusive in practice (codice or pec), details the 6 vs 7 character distinction, and adds the rule that '0000000' forces PEC. This goes beyond mere field documentation.

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 validates the format of a CodiceDestinatario or PEC address, distinguishing it from sibling validation tools like validate_partita_iva. It gives specific examples of valid inputs, making the purpose unambiguous.

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 states when to use the tool: 'Call this before build_transmission_header()'. It also provides routing rules that guide the agent on how codice/pec interact, and even mentions what is not covered (no live SDI lookup), proactively managing expectations.

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

Deploy Server