mcp-fattura-elettronica-it

Check Ritenuta Acconto

check_ritenuta_acconto

Calculate ritenuta d'acconto withholding tax for professional service invoices, returning DatiRitenuta, amount, rate, and legal reference for Italian e-invoicing.

Instructions

Compute ritenuta d'acconto (withholding tax) for professional invoices.

Use this when issuing professional service invoices (TD01 or TD06) that are subject to withholding tax — typically for self-employed professionals, agents, or freelancers. Also mark the relevant line items with ritenuta='SI' in add_linea_dettaglio(), and pass the returned 'DatiRitenuta' dict to generate_fattura_xml() as dati_ritenuta.

tipo_ritenuta determines the rate: RT01/RT02 = 20% (ritenuta d'acconto, statutory default). RT03 (INPS), RT04 (ENASARCO), RT05 (ENPAM), RT06 (other) have variable rates: aliquota_override or importo_override is required for all of them. causale_pagamento: income category code for Mod. 770 (e.g. 'A' professional fees, 'O' occasional). aliquota_override: supply the actual rate (%) for RT03-RT06, or to override the 20% default for RT01/RT02. importo_override: supply the exact withholding amount when rate-based computation is imprecise.

Validates: tipo_ritenuta must be in RT01-RT06. RT03-RT06 require aliquota_override or importo_override.

On success returns {'DatiRitenuta': {...}, 'importo_ritenuta': str, 'aliquota_applicata': str, 'imponibile_ritenuta': str, 'description': str, 'legal_ref': str}. On failure returns {'error': ''}.

Input Schema

TableJSON Schema

Name	Required	Description
`imponibile`	Yes	Taxable base amount subject to withholding tax (imponibile della ritenuta). Usually equals the net invoice total for professional services.
`tipo_ritenuta`	Yes	Ritenuta/contributo type code: RT01 (persone fisiche, 20% default), RT02 (persone giuridiche, 20% default), RT03 (contributo INPS, variable rate, override required), RT04 (contributo ENASARCO, variable rate, override required), RT05 (contributo ENPAM, variable rate, override required), RT06 (altro contributo previdenziale, override required).
`importo_override`	No	Override the withholding amount directly (e.g. 200.00). Use when the exact amount is known rather than computing from the rate. When both aliquota_override and importo_override are provided, importo_override takes precedence for the amount; aliquota_override is used for the AliquotaRitenuta field.
`aliquota_override`	No	Override the withholding rate as a percentage (e.g. 4.0 for 4%). Required for RT06 (variable rate). Optional override for RT01–RT05 when the statutory rate differs from the indicative table value. When provided, the table rate is ignored.
`causale_pagamento`	Yes	Income category code for withholding tax (CausalePagamento). Common values: A (professional fees), B (agent commissions), L (employment), O (occasional work), Q (commissions). See Agenzia delle Entrate Mod. 770 for the complete list.

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

changedInput schema / properties / tipo_ritenuta / description

Previous value: -"Ritenuta/contributo type code: RT01 (persone fisiche, 20%), RT02 (persone giuridiche, 20%), RT03 (contributo INPS gestione separata, ~26.23%), RT04 (contributo ENASARCO, ~8.50% seller portion), RT05 (contributo ENPAM, ~10% indicative), RT06 (altro contributo previdenziale, rate=0 — compute amount directly)."New value: +"Ritenuta/contributo type code: RT01 (persone fisiche, 20% default), RT02 (persone giuridiche, 20% default), RT03 (contributo INPS, variable rate, override required), RT04 (contributo ENASARCO, variable rate, override required), RT05 (contributo ENPAM, variable rate, override required), RT06 (altro contributo previdenziale, override required)."

Changed3 schema fields changedv0.2.4May 23, 2026

addedInput schema / properties / aliquota_override

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 100,
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Override the withholding rate as a percentage (e.g. 4.0 for 4%). Required for RT06 (variable rate). Optional override for RT01–RT05 when the statutory rate differs from the indicative table value. When provided, the table rate is ignored."
+}

addedInput schema / properties / importo_override

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Override the withholding amount directly (e.g. 200.00). Use when the exact amount is known rather than computing from the rate. When both aliquota_override and importo_override are provided, importo_override takes precedence for the amount; aliquota_override is used for the AliquotaRitenuta field."
+}

changedInput schema / properties / tipo_ritenuta / description

Previous value: -"Withholding tax type code: RT01 (natural person, occasional work, 20%), RT02 (natural person, professional, 20%), RT03 (legal entity, agent commissions, 23.20%), RT04 (natural person, agent commissions, 23.20%), RT05 (condominium, 4%), RT06 (employment income, 30%)."New value: +"Ritenuta/contributo type code: RT01 (persone fisiche, 20%), RT02 (persone giuridiche, 20%), RT03 (contributo INPS gestione separata, ~26.23%), RT04 (contributo ENASARCO, ~8.50% seller portion), RT05 (contributo ENPAM, ~10% indicative), RT06 (altro contributo previdenziale, rate=0 — compute amount directly)."

First observedv0.2.0Apr 28, 2026

TDQS

A4.6/5.0

Behavior4/5

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

No annotations are provided, so the description must shoulder the entire behavioral burden. It does well here: it explains the validation rules (tipo_ritenuta must be RT01-RT06, RT03-RT06 require overrides), the precedence logic (importo_override over aliquota_override for amount), and the exact return contract (success returns a dict with specified keys, failure returns {'error': '<reason>'}). The only minor gap is that it does not explicitly say the operation is non-mutating (e.g., 'this only computes and does not modify any data'), but the nature of a 'check' plus the clear return format makes that implicit.

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 well-organized and front-loaded: it starts with the purpose, then moves through usage context, parameter semantics, validation, and return format. Each section is clearly separated, and the parameter explanations are grouped logically. It is somewhat long, but every sentence earns its place—there is no filler or redundancy. The only reason it is not a 5 is that it could be trimmed slightly without losing information (e.g., the phrase 'typically for...' could be merged).

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?

Given that the tool is a pure computation function with an output schema (which the description enumerates) and no annotations, the description is remarkably complete. It covers when to use, how to use (including the required partner calls), all parameter semantics, validation logic, and the exact success/failure return shape. An agent has everything it needs to decide whether to call this tool and how to interpret the result, even without inspecting the sibling tools or reading tax code.

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?

While the input schema already has 100% coverage of parameter descriptions, the description adds substantive semantic value beyond the schema. For example, it explains the rate implications of each tipo_ritenuta (RT01/RT02 = 20%, RT03-RT06 variable and require overrides), clarifies the interplay between aliquota_override and importo_override (precedence rules), and gives concrete examples for causale_pagamento (A, B, L, O, Q). These details help the agent choose correct values without needing to look up tax regulations, exceeding the minimum baseline of 3.

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 concise, definitive purpose: 'Compute ritenuta d'acconto (withholding tax) for professional invoices.' It names the specific verbs (compute, issue), the resource (professional invoices), and the tax type, leaving no ambiguity about what the tool does. It also ties the action to specific document types (TD01/TD06) and professional categories, making it easy to distinguish from sibling tools like generate_fattura_xml or compute_totali.

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 gives explicit usage context: 'Use this when issuing professional service invoices (TD01 or TD06) that are subject to withholding tax — typically for self-employed professionals, agents, or freelancers.' It also provides a clear integration workflow: 'Also mark the relevant line items with ritenuta='SI' in add_linea_dettaglio(), and pass the returned 'DatiRitenuta' dict to generate_fattura_xml() as dati_ritenuta.' This tells the agent exactly when and how to use the tool, even naming the sister tools to chain with, which is far more than most descriptions.

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

Deploy Server