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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries full burden. It discloses that prezzo_totale must be provided explicitly (not computed), that negative values are used for credit notes, that natura is required when aliquota_iva is 0.0, that warnings are returned for non-standard VAT rates, and that altri_dati_gestionali entries are emitted after Natura in XSD element order. It also specifies success and failure return shapes. No important behavioral trait is left hidden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but exceptionally dense and well-structured. It front-loads the purpose and workflow position, then sequences constraints (numero_linea, prezzo_totale, natura), then optional data, then return behavior. Every sentence conveys a directive or constraint; there is no filler or redundancy. The length is justified by the complexity of the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, 2-required tool with no annotations, this description is complete. It provides full workflow context, exact dependencies on sibling tools (get_natura_codes, check_ritenuta_acconto, build_sport_worker_exemption_dato_gestionale), instructions for handling the output (collect into a list for compute_totali), and details on error and warning returns. Nothing essential for correct invocation is missing.

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

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

Despite 100% schema description coverage, the description adds significant meaning beyond the schema: numero_linea must be sequential starting at 1 and not reused; prezzo_totale is not auto-computed; negative values indicate credit notes; the requirement to use get_natura_codes() for natura selection; and the detailed structure of altri_dati_gestionali with a pointer to build_sport_worker_exemption_dato_gestionale() for the 1.9.1 codifica. These are crucial semantic cues an agent cannot derive from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Build' and the resource 'a single DettaglioLinee (line item) entry for the FatturaElettronicaBody,' and immediately places it as step 7 in the invoice generation workflow. This distinguishes it from sibling build_* tools such as build_dati_generali and compute_totali. No ambiguity about what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs 'Use this as step 7' and gives the exact sequence: after build_dati_generali(), collect the returned dicts into a list, pass to compute_totali() (step 8) and then generate_fattura_xml() (step 10). It also specifies 'call once per line item' and directs when to invoke helper tools like get_natura_codes() and check_ritenuta_acconto() under specific conditions. This is textbook usage guidance.

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

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.

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.

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.

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.

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.

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.

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

No annotations exist, so the description carries the burden. It does well: states validation rules, success/error return shape, and the pure 'build' nature. It doesn't explicitly say there are no side effects or that it is idempotent, but the return-value description makes a pure-builder behavior clear enough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the workflow/validation/return details are organized in short paragraphs. Slightly long, but every sentence contributes semantic value; the validation list is dense but useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-param builder with no output schema warning, the description is complete: it states positioning in the workflow, conditional parameter semantics, validation rules, and both success/error return shapes. An agent has everything needed to invoke it correctly without external knowledge.

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

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

Schema only lists bare codes and types; the description adds real meaning: TP01/TP02/TP03 semantics, MP05 as the common B2B method, IBAN requirement for MP05, instalment usage per tranche, and the relationship between importo_pagamento and invoice total. This is exactly what an agent needs to fill the parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and object ('Build the DatiPagamento block for the FatturaElettronicaBody') and immediately anchors it in the workflow ('step 9... after compute_totali, before generate_fattura_xml'). No ambiguity about what this tool does or where it fits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear positional context in the pipelinecomputing and explicit when/why to use it: optional but recommended for B2B, call once per instalment tranche for TP01, and 'when to use' nuance for payment methods and IBAN. This is actionable guidance beyond the schema.

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

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 substantial work: it discloses the success return shape, the failure shape for invalid riferimento_data, that the value is verified against Specifiche Tecniche 1.9.1 effective 2026-05-15, and that certain fields are deliberately not mandated. It doesn't discuss side effects, idempotence, or permission requirements; acceptable for a pure builder with no side effects, it meets expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is ~150 words across three tightly organized paragraphs, and every sentence earns its place: the triggering legal condition, the exact TipoDato value with its specification reference, the non-mandated fields, integration instructions, and return contract. No filler or repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter, 0-required builder with a matching output schema, the description covers everything an agent needs to invoke and consume it correctly. It describes success/failure formats, the target parameter of a sibling tool, and the legal/regulatory trigger for correct selection.

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

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

Schema description coverage is 100%, giving a baseline of 3. The description reinforces that RiferimentoNumero is not mandated and a caller convenience, but the schema text already contains that. The ALI-COMP contrast adds some interpretive value but doesn't materially deepen the meaning of the two parameters beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb-resource pair ('Build the AltriDatiGestionali entry for the sport-worker IRPEF exemption codifica') and pins down the exact output value (ESENZSPORT) and legal basis (art. 36 comma 2, D.Lgs. 36/2021). It distinguishes itself from related codifiche by contrasting with 'ALI-COMP', which requires RiferimentoNumero.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context: compensation exempt up to EUR 15,000/year under the cited article, and explains the ALI-COMP contrast to help the caller decide whether RiferimentoNumero matters. It also gives concrete integration instructions on how to consume the result (via add_linea_dettaglio() or a manual list). It doesn't explicitly say 'use this instead of tool X', so it falls just short of the explicit when-not-to-use tier.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the validation rules (formato_trasmissione allowed values, progressivo_invio constraints, conditional pec_destinatario requirement) and the success/failure return shapes. Minor gap: it doesn't explicitly state that this is a pure in-memory builder with no persistence or external side effects, though 'Build' implies it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly organized: purpose, workflow placement, validation rules, and return behavior. Every sentence earns its place, and the critical workflow ordering is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter builder with an output schema, this fully equips the agent: workflow position, validation expectations, error handling, and return contract are all present. The output schema covers structured return details, while the description adds the behavioral context around when and how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by spelling out validation constraints (e.g., formato_trasmissione must be 'FPA12' or 'FPR12'; progressivo_invio 1–10 alphanumeric; pec_destinatario required when codice_destinatario is '0000000') and by linking parameters to sibling tools like generate_progressivo_invio and lookup_codice_destinatario.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Build') and resource ('DatiTrasmissione block required in every FatturaPA header'). Clearly distinguishes itself from siblings by naming its place in the workflow and its relationship to generate_progressivo_invio, validate_cedente_prestatore, and generate_fattura_xml.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions this tool as step 3 in the invoice generation workflow, with direct predecessor and successor tools named. Also instructs to call lookup_codice_destinatario() first and to stop on failure, giving concrete when-to-use and when-not-to-continue guidance.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden, and it delivers: discloses grouping logic, rounding method (HALF_UP to 2 decimals), default EsigibilitaIVA value, behavior on empty input (always succeeds), and the exact return structure. It also warns against passing DettaglioLinee dicts, adding important edge-case transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then logically covers usage, calculation, defaults, and return. Every sentence conveys necessary information without redundancy or filler. The structure flows naturally from what → when → how → what to expect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's algorithmic complexity and the presence of an output schema (not shown here but indicated by context), the description is thorough. It details the grouping, calculation, rounding, default value, empty-list behavior, and the exact return keys, plus how to feed the result into generate_fattura_xml(). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how each field is used (prezzo_totale, aliquota_iva, natura) beyond the schema's type declarations, and clarifies the expected input is raw values rather than dicts. This is helpful but not radically new information beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (compute) and resource (DatiRiepilogo VAT summary totals), and precisely defines the grouping keys (AliquotaIVA and Natura). It clearly distinguishes itself from sibling tools like add_linea_dettaglio and generate_fattura_xml by describing its specific role in the workflow and the transformation it performs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use the tool: step 8 in the invoice generation workflow, after add_linea_dettaglio() and before generate_fattura_xml(). It also clarifies the input format (raw line values, not DettaglioLinee dicts), leaving no ambiguity about when and how to call it.

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

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 default behaviors (null/empty fields omitted), the effect of include_empty, the meaning of indent values, and even guarantees 'Always succeeds.' It also states the exact return shape, giving the agent strong expectations beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet information-dense, with no filler. It front-loads the core purpose, then logically covers sequencing, parameter behavior, and return value. Every sentence adds useful operational detail, and the length is appropriate for a three-parameter serialization tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully covers what the agent needs to call the tool correctly: when to use it, what input it expects, how each parameter behaves, and what it returns. The explicit 'Always succeeds' note removes ambiguity about failure modes. Despite lacking annotations, the description is self-sufficient and complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: it explains why null/empty fields are omitted by default, gives concrete indent examples (0=compact, 2=standard, 4=wide), and clarifies how include_empty changes output. This enriches interpretation beyond the schema's short field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Serialize a parsed FatturaPA dict to a clean, indented JSON string.' This clearly distinguishes the tool from XML-generation and parsing siblings such as generate_fattura_xml and parse_fattura_xml. The purpose is unambiguous and immediately actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs when to call the tool: 'Call this after parse_fattura_xml() when you need a human-readable or machine-transferable representation of the invoice.' This provides clear sequencing and context, though it does not explicitly mention when-not-to-use it or name alternative serialization tools.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: Italian national fields are accepted but not emitted (with a reference to the same policy as generate_ubl_invoice), and it specifies the return structure on success, validation error, and unexpected error. This goes beyond a simple mutation indication, though it does not mention idempotency or any side effects, which are likely negligible for a generation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly structured with front-loaded purpose, then usage, exclusion, policy, and return values. Every sentence serves a distinct role, and there is no filler. It is as concise as possible while conveying necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generation tool with a nested object parameter and output schema, the description covers all essential aspects: the input format, the specific wire format, the exclusion of FatturaPA, the handling of Italian fields, and the return/error contract. It references generate_ubl_invoice for field requirements, which completes the picture without redundancy. Nothing an agent needs to correctly invoke this tool is missing.

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

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

The input schema already has a detailed description for invoice_data, covering field requirements and profile URNs, so schema_description_coverage is 100%. The tool description itself adds little beyond what the schema already states: it says 'from an ItalianInvoice dict' and 'same policy as generate_ubl_invoice', which largely duplicates the schema's text. The baseline for high coverage is 3, and the tool description does not meaningfully enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Generate a CII CrossIndustryInvoice XML document from an ItalianInvoice dict.' It distinguishes itself from generate_fattura_xml by explicitly noting it does NOT produce FatturaPA XML, and references generate_ubl_invoice for policy alignment. This makes the tool's purpose unambiguous even without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context: 'Use this when a CII (UN/CEFACT) wire format is required — for example, for Factur-X embedded XML or ZUGFeRD-compatible output.' It also states an explicit exclusion with an alternative: 'This tool does NOT produce FatturaPA XML; use generate_fattura_xml() for SdI submission.' This is an ideal when/when-not pair.

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

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

No annotations are provided, so the description carries the full burden. It discloses the output shape on success ({'xml': str, 'filename': str, 'length_bytes': int}) and on error ({'error': '<reason>'}), and it explains structural behaviors such as the absence of per-line VAT breakdown and DatiPagamento. It could add more about validation or side effects, but for a document-assembly tool the disclosed behavior is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: the main purpose is stated in the first sentence, followed by usage conditions, structural differences, and return values. Every sentence earns its place, and the format is scannable with clear paragraphs. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 params, nested objects, 5 required) and the rich schema descriptions, the description covers the key context: document types, legal basis, EUR 400 threshold, structural differences from FatturaPA, and return shape. It doesn't detail every optional field, but the schema already does that. The only minor gap is not mentioning validation or XSD compliance, but the output schema and sibling validate_fattura_semplificata_xsd cover that context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the simplified format's flat structure and clarifying that Importo is tax-inclusive and DatiIVA carries Imposta and/or Aliquota. It also notes FormatoTrasmissione is always FSM10, which is not obvious from the schema alone. This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Assemble a complete FatturaSemplificata VFSM10 XML document') and resource, and explicitly distinguishes the simplified format from the ordinary FatturaPA by listing structural differences. It also names the document types (TD07/TD08/TD09) and the legal basis, so an agent can clearly tell this tool apart from siblings like generate_fattura_xml or generate_ubl_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool: for simplified invoices, credit notes, and debit notes per art. 21-bis DPR 633/72, valid for transactions up to EUR 400 tax-inclusive. It also contrasts with the ordinary FatturaPA format, giving the agent a clear exclusion criterion. This is strong usage guidance without needing to name a specific sibling.

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

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

Since there are no annotations, the description carries the behavioral burden. It plainly discloses that the tool does NOT validate against the XSD schema, that it unwraps the top-level key of input dicts, and that it returns either a success dict or an unexpected-error dict. This is enough for an agent to call it correctly and know what to do afterward.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well organized: purpose, workflow placement, required/optional inputs, warning about lack of validation, and output/error shapes. Every sentence provides actionable information and there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter assembly function with no annotations, the description is nearly complete: it names inputs, output fields, errors, and the required next validation step. It loses one point because the main description does not mention the additional_bodies parameter explicitly; an agent would need to rely on the schema, but the schema does provide enough context.

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

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

Schema coverage is already 100%, so the schema carries the detailed parameter descriptions. The description still adds useful cross-tool context, such as which builder tools supply each block, which parameters are lists, and what must exist inside each block. It is not a 5 because the top-level description omits the additional_bodies parameter from its own optional list, though the schema covers it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific action and resource: 'Assemble a complete FatturaPA v1.2.3 XML document from all prepared blocks.' It also positions this as the final assembly step, which distinguishes it from the builder/validation siblings and from simplified/UBL/CII invoice formats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says this is step 10 in the invoice generation workflow and instructs the agent to call validate_fattura_xsd() as step 11 immediately after. It also states that all required blocks must come from the appropriate builder/validator tools, giving clear when-to-use and next-step guidance.

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

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

With no annotations, the description fully carries behavioral disclosure. It explains the uniqueness requirement per transmitter Partita IVA, the random default behavior for testing, the 10-character length constraint, and the exact success and failure return shapes. This is comprehensive for a pure identifier-generation tool with no side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: purpose first, then usage, then parameters, then return values. Every sentence contributes essential information, including the unique-per-transmitter constraint and production guidance. No filler or redundant restating of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool with two optional parameters and an output schema, the description is complete. It explains workflow positioning, uniqueness constraints, production vs. testing behavior, parameter constraints, and both success and error return formats. An agent has everything needed to call this tool correctly.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The tool description adds value beyond the schema by reinforcing the production/testing distinction for 'sequence' and giving the concrete example 'INV' → 'INV00001'. It does not fully replace the schema, but it enriches the parameter semantics usefully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Generate a ProgressivoInvio identifier for the DatiTrasmissione block.' It is clearly distinguished from siblings by naming the exact workflow step and its predecessor tool, build_transmission_header(). An agent can immediately understand what this tool produces and where it fits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Use this as step 2 in the invoice generation workflow, before build_transmission_header().' It also provides production vs. testing guidance, explaining that a monotonically increasing sequence should be passed in production and the random default should be used only for testing. This leaves no ambiguity about when to invoke the tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses what is not emitted (FatturaPA-specific fields are omitted), which is key behavioral context. It states that those fields are ignored in output, which is helpful. It also specifies the return structure for success and error cases, which is important. However, it does not mention any rate limits, idempotency, or whether the input is mutated (though unlikely, no explicit statement). Given the absence of annotations, it does a solid job but could add a note on side effects (none expected) and error handling details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is quite long but every sentence earns its place. It starts with the core purpose, then explains usage context, exclusions, profile details, and return structure. It is structured with clear paragraphs, front-loading the main action. A slight trimming could be done, but the length is justified by the complexity of the tool's domain. Not overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (nested objects, many fields), the description covers the main aspects: input type, profile selection, field exclusions, and return structure. It does not explain the full schema of nested objects, but the schema already does that with 100% coverage. The output schema is not provided, but the description fills that gap. It could benefit from mentioning error scenarios like XSD validation failures, but overall it is adequate.

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

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

The schema already provides 100% parameter description coverage. The description adds value by clarifying the profile field's purpose and listing specific example values, and by explicitly noting which fields are ignored in UBL output. It also explains the structure of the return value, which is not in the schema since no output schema is given. This compensates beyond schema schema, so a 4 is justified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States precisely the action (generate a UBL 2.1 Invoice XML), the input type (ItalianInvoice dict), and the output format. It differentiates from siblings by explicitly noting it does not produce FatturaPA XML, pointing to generate_fattura_xml for SdI, and mentions CII as a sibling for comparison, though not explicitly. The verb+resource is specific, and the exclusion of FatturaPA clarifies its role in the tool family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: for cross-border B2B invoices or Peppol-routed documents. Provides clear exclusion: does not produce FatturaPA XML, use generate_fattura_xml() for SdI submission. Also advises on profile selection for Peppol vs EN 16931, and even includes an inference note about FatturaPA-specific CIUS not being standardised, with a verification recommendation. This is exemplary guidance.

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

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

With no annotations, the description carries the full burden, and it delivers: 'Always succeeds' plus an explicit return contract {'codes': [...], 'total': int}. The note about parent codes N2/N3/N6 being removed from the FatturaPA XSD in 2021 is a non-obvious, valuable behavioral/domain detail that prevents agents from using obsolete codes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense without bloat: purpose, trigger condition, common-code examples, an important caveat, and return format are each covered in a compact, well-structured block. No sentence is redundant or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter lookup with an output schema, the description is complete: it gives the trigger context, expected output shape, success guarantee, and the legal/version constraints around valid codes. An agent has everything needed to decide to call it and interpret the result correctly.

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

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

The tool has zero parameters, so the schema coverage is trivially 100% and the baseline is 4. There are no parameter-level semantics to add, and the description appropriately focuses on when the tool should be invoked instead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('complete list of valid Natura exemption codes with legal references'), immediately telling the agent what the tool does. The trigger condition ('when add_linea_dettaglio() requires a Natura code') further pins down its purpose and distinguishes it from sibling code-list tools by subject matter.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Call this when add_linea_dettaglio() requires a Natura code (i.e. aliquota_iva is 0.0)' is an explicit, actionable condition for when to use the tool. However, it does not name when-not cases or alternative lookup tools, so it stops short of the full when/when-not/alternatives guidance required for a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds 'Always succeeds' and explicitly documents the return shape as {'codes': [{'code': str, 'description': str}, ...], 'total': int}. It also provides useful domain context about RF01 and RF19, exceeding what annotations would normally convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the main action, the code range, and the return type appear immediately. The explanatory sentences about RF01 and RF19 earn their place by helping an agent choose the correct code before validation. There is no fluff or repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and an existing output schema, the description is complete: it states purpose, when to use it, what it returns, and that it always succeeds. An agent has everything needed to invoke it correctly and integrate it into the invoice-building workflow.

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

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

The tool has zero parameters, so the description has no parameter semantics to explain. The 100% schema coverage and empty input schema mean nothing is missing. The description adds relevant detail about the return values, which is appropriate for this no-parameter lookup tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return the complete list of RegimeFiscale codes (RF01–RF19) with descriptions.' This clearly distinguishes it from sibling code-list tools like get_tipo_documento_codes and get_natura_codes by naming the exact code range and subject.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage context: 'Call this to look up the correct fiscal regime code before calling validate_cedente_prestatore().' It also explains why the lookup matters ('Every Italian seller must declare a regime'). It does not explicitly state when not to use it, but the workflow positioning is clear.

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

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

With no annotations provided, the description discloses the key behaviors itself: required validation rules for both parameters, the zero-padding behavior for short numeric progressivi, and the precise success/error return shapes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The most important facts (what it does, when to use it, format) lead, followed by validation rules and return shape. No filler or redundancy that adds noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage context, parameters, validation behavior, and both success/error return shapes. There is no ambiguity about inputs, outputs, or edge cases, and the sibling tool set offers no competing filename-format utility.

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

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

The schema already documents both parameters well (100% coverage), so the description mostly repeats that info. However, it adds the canonical filename template (IT{PartitaIVA}_{ProgressivoInvio}.xml) and a concrete example, which are useful beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('generate'), a specific resource (canonical SDI filename), and the exact format with an example. Clearly distinguishes from generate_fattura_xml() by noting this is for the filename alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('when you need the official filename independently of generate_fattura_xml()') and names the alternative. Also states the exact naming convention, so an agent knows exactly when this tool applies.

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

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

The description discloses that the tool 'Always succeeds', which is a useful behavioral guarantee beyond what annotations provide (none are present). It also specifies the return structure {'codes': [...], 'total': int}, which adds transparency about the output. However, it doesn't mention potential edge cases or failure modes, though 'Always succeeds' covers that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first sentence states the core purpose, the second gives usage guidance, the third lists common codes, and the fourth states the return format. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter lookup tool with an output schema, the description is complete. It tells the agent what the tool returns, when to use it, and what the data means. The output schema covers the return structure, and the description adds the semantic context (common codes and their use cases).

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

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

The tool has zero parameters, so the schema is trivially complete. The description adds value by explaining what the returned data contains (code, description, use_case) and how to use it, which is more than the empty schema provides. Baseline for 0 params is 4, and the description meets that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return') and resource ('complete list of document type codes'), and explicitly names the codes range (TD01–TD28) with descriptions and use cases. It clearly distinguishes itself from sibling tools like get_regime_fiscale_codes and get_natura_codes by focusing on TipoDocumento codes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Call this to choose the correct TipoDocumento before calling build_dati_generali()', providing a clear when-to-use directive and a specific alternative/related tool. It also lists common codes with their use cases, which helps the agent decide when this tool is relevant.

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

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

With no annotations, the description carries the full disclosure burden and largely meets it: it reveals the operation persists a document, computes a SHA-256 hash, adds a timestamp and retention metadata under AgID circolare 65/2014, and returns archive metadata. It stops short of edge behaviors like re-archiving an existing document_id or failure handling, but the core write and safety profile is honestly disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: purpose first, then storage behavior, then return value. Every sentence adds distinct information, and the legal reference (AgID circolare 65/2014) earns its place as meaningful context rather than boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema covers the return shape, and the description already previews document_id and retention_until, so return handling is addressed. What's missing is the pipeline position — a clear prerequisite that the invoice must be XAdES/CAdES-signed before archiving — and any statement on idempotency or overwrite behavior for document_id, which matters for a persistence tool in a compliance workflow.

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

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

Schema description coverage is 0%, so the description needed to compensate, but it only mentions `document_id` (as return metadata) and adds `retention_until` (which is not in the schema at all). The required `document_base64`, `format_id`, and `signer_id` are left unexplained, and describing document_id as returned when the schema lists it as an input with default '' creates real ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Archive') and resource ('signed invoice') plus the regulatory purpose (conservazione sostitutiva, AgID circolare 65/2014). The storage behavior ('Stores the document with SHA-256 hash, timestamp...') clearly distinguishes this from the sibling retrieval and verification tools (it__retrieve_archived_invoice, it__verify_archive_integrity, it__list_archived_invoices).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Archive a signed invoice' implies the workflow position — the invoice must already be signed, so it should follow it__sign_fattura_xades or it__sign_fattura_cades — and 'for conservazione sostitutiva' signals the regulatory context. However, it never names alternatives or states exclusions, so an agent must infer when to use this versus the retrieve/verify/list archive siblings or it__build_pacchetto_versamento.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool constructs a ZIP archive from signed invoices and an XML index, but does not cover prerequisites (e.g., invoices must already be signed), side effects, permissions, or output handling. This is acceptable but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first front-loads the core action and content, the second adds useful domain context. No filler words or repeated title text; this is efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, not explaining return values is acceptable. However, the tool has two parameters and no parameter guidance in the description, and there is no annotation coverage; an agent could miss the expected format and when it needs the producer_id, so the description is adequate but not complete.

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

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

Schema description coverage is 0%, so the description must compensate; it only describes the archive content but never explains what 'documents_json' or 'producer_id' mean or how they map to that content. An agent would have to guess the required JSON structure and the role of producer_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Build'), resource ('Pacchetto di Versamento (PdV) ZIP archive'), and content (signed invoices + XML index). It also positions the tool in the domain workflow by naming AgID-accredited conservazione providers, clearly distinguishing it from siblings like it__archive_invoice or it__sign_fattura_xades.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives the tool's usage context: building the unit of transfer to an AgID-accredited conservazione provider. It does not explicitly name alternatives or say when not to use it, but the clear transfer purpose implicitly routes the agent away from the plain archive and signature siblings.

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

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

No annotations are provided, so the description carries the burden. It discloses that the status is 'last known local status' and that SDI is asynchronous, which is useful behavioral context. However, it doesn't mention potential staleness, whether it polls, or what happens if no status is known yet. It's adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff, and the key information (what it does, the async caveat) is front-loaded. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only status check, the description is nearly complete. It explains the async nature and the local status limitation. It doesn't describe the output schema, but an output schema exists, so that's not required. Minor gap: no mention of error cases (e.g., unknown IdentificativoSDI), but overall sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that the parameter is the IdentificativoSDI of a previously submitted invoice, which adds meaning beyond the bare schema. However, it doesn't provide format details (e.g., length, pattern) or clarify that it's the same identifier returned by submission. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks the status of a previously submitted invoice by its IdentificativoSDI, using a specific verb ('Check') and resource ('status of a previously submitted invoice'). It distinguishes itself from siblings like it__submit_to_sdi and it__parse_sdi_notification by focusing on status retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that SDI communicates status asynchronously via notifications and that this tool returns the last known local status, giving clear context for when to use it (after submission, to check status). It doesn't explicitly name alternatives or exclusions, but the context is sufficient for an agent to understand its role among siblings.

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

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

No annotations exist, so the description carries the burden of behavioral disclosure. It signals a read-style operation ('Show current...') and explicitly discloses that the sensitive cert_password is not exposed, which prevents an agent from expecting it in the response. It could additionally state that it makes no changes, but the zero-parameter read-only wording makes that reasonably clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, and the second sentence adds an important non-obvious detail (cert_password is not exposed). No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only inspection tool with an output schema available, the description covers the key output fields and explicitly warns about an absent field. It does not describe when to use this instead of it__check_sdi_status, but the near-complete coverage of behavior and the simple no-parameter surface make it largely sufficient.

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

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

The tool has zero parameterschen, so there is nothing for the description to add about parameter semantics. Output fields are listed in the description, which is the relevant behavioral disclosure for a no-input getter. This exceeds the baseline for parameter count of 0.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Show') and a clear resource ('current SDI channel configuration'), then enumerates the exact fields returned (environment, channel type, endpoint URL, certificate status). This is immediately distinguishable from sibling tools like submit/check/parse operations, so the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this is a read-only inspection tool useful before configuring or submitting to the SDI, but it does not state explicit when-to-use conditions or name alternatives for related operations such as checking SDI status. The context is clear enough, but a 'use this when you need to verify current channel settings' statement would improve routing.

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

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

No annotations are provided, so the description carries the burden for behavior. It clearly says the operation lists and returns sorted metadata, which implies a read-only behavior. Still, it does not disclose potential limitations such as pagination, authorization needs, or whether the operation can be called repeatedly without side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is terse, with no filler or repetition, and front-loads the key action before the return details. Every clause adds useful information regarding what is listed and how the results are ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless list tool, the description is nearly complete. It clarifies that results are metadata records and sorted, and a provided output schema likely details the fields. It could still mention whether the list is global or could grow very large, but the core call semantics are well covered.

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

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

The tool has zero parameters and an empty input schema, so there is no parameter semantics the description needs to clarify. The baseline of 4 applies because there is no parameter information missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List all archived invoices'. It also specifies the return content and ordering ('archive metadata records sorted by archive date'), which differentiates it from siblings like it__retrieve_archived_invoice (single retrieval) and it__archive_invoice (write action).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The use case is implied by 'List all archived invoices' and the metadata-record return type, so an agent can infer this is for enumerating archived invoices rather than retrieving one. However, it never explicitly states when not to use it or names alternatives (e.g., it__retrieve_archived_invoice for invoice content).

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

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

With no annotations provided, the description must carry behavioral disclosure itself. It transparently states the input type and the output shape ('structured dict') and promises comprehensive coverage across all notification types. It does not disclose failure behavior on malformed XML or whether any normalization or validation occurs, but for a pure parse operation the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler; the core action and output are front-loaded and the notification type codes are compactly listed in parentheses. Every sentence contributes selection-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a one-parameter tool with an output schema, the description provides the essential input context and full type coverage. It leaves error handling unspecified, but the presence of an output schema and the simple, read-only nature of parsing make the description adequate for selection and invocation. It could add a note about invalid XML handling, but nothing critical is missing.

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

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

The sole parameter is 'notification_xml' and the schema gives no description (0% coverage), so the description must compensate. It does clarify that the expected payload is an SDI notification XML document, which is consistent with the parse behavior. But it does not explicitly state that the value should be the raw XML string as opposed to a path or reference, so the compensation is partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Parse'), the exact resource ('an SDI notification XML'), and the output ('a structured dict'). It also enumerates all supported notification type codes, which clearly distinguishes it from sibling invoice-parsing tools such as parse_fattura_xml or parse_ubl_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The first sentence establishes the use case: any time the agent has an SDI notification XML to convert. The list of notification type codes gives concrete selection criteria, and the word 'notification' implicitly separates this from the invoice-parsing siblings. However, it never names an alternative or states when not to use it, so it stops short of explicit exclusion guidance.

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

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

With no annotations, the description carries the burden of behavior disclosure. It does disclose the return shape: document content as base64-encoded data and archive metadata. It does not mention error behavior when the document is not found, access requirements, or side effects, but the read-only nature is conveyed by 'Retrieve' and the return description adds meaningful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The action is front-loaded ('Retrieve an archived invoice'), the key input is named, and the return value is summarized efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter retrieval tool with an output schema, the description is nearly complete. It states the input, the operation, and the general return content. It doesn't mention not-found behavior, but that is a minor gap given the simplicity and the presence of an output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It adds some meaning by clarifying that document_id identifies the archived invoice, but it doesn't provide format, length, or source expectations for the identifier. Since there is only one self-explanatory parameter, this is adequate but not rich.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Retrieve') and resource ('archived invoice') and identifies the required key ('document_id'). It clearly differentiates this tool from its siblings: it returns the document content and metadata for a single archived invoice, unlike it__list_archived_invoices (listing) or it__verify_archive_integrity (verification).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case: when you need to fetch a specific archived invoice's content and metadata by its document_id. It does not explicitly name alternatives or exclusions, but given the sibling set, the intended usage is reasonably clear.

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

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

No annotations are provided, so the description must carry the behavioral burden. It explicitly discloses that the action is irreversible and requires confirmation, and it warns that the XML must conform to a named schema. This gives an agent the key safety and format behaviors beyond the raw schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no filler: the first states the action and values, the second adds the schema constraint and confirmation requirement. It earns every word and is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-stakes irreversible tool with five parameters and no annotation or per-parameter schema descriptions, the description does not fully explain all required inputs. It covers the core operation, the XML schema, and irreversibility, but an agent is still under-specified on several parameters and on the operational context with sibling tools.

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

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

Schema description coverage is 0%, so the description should compensate, but it only meaningfully explains the esito values (EC01/EC02) and the esito_xml schema. It does not clarify the semantics or expected format of identificativo_sdi, nome_file, or how to obtain/use confirmation_token.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete verb and resource: 'Send an acceptance (EC01) or rejection (EC02) notification to SDI'. Adding 'for a received invoice' clarifies the scope and distinguishes this from tools like it__submit_to_sdi, which send invoices rather than esiti.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly scopes usage to received invoices and flags the prerequisite of confirmation plus irreversibility. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusion guidance, but the context is clear.

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

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

With no annotations provided, the description carries the full burden and does it well. It discloses the DER-encoded base64 output, the signer microservice fallback behavior, the qualified PKCS#12 requirement, and the irreversible/confirmation requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, all substantive, with the core action and output front-loaded. There is no filler, and each sentence adds a distinct piece of information: purpose, output, prerequisite, fallback behavior, and irreversibility.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema presumably covers the return contract, and the description covers output encoding, prerequisites, and the irreversible confirmation flow. The only notable gap is clarifying when the optional cert_path/cert_password parameters are actually needed, given the microservice fallback, but the description is otherwise complete for a signing tool.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions a qualified PKCS#12 certificate (mapping loosely to cert_path/cert_password) and confirmation (mapping to confirmation_token), but it does not explain parameter-level semantics such as when cert_path can be empty, how confirmation_token is obtained, or the format of the xml parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Apply a CAdES-BES (CMS/PKCS#7) attached signature to a FatturaPA XML document.' It also states the output format (.xml.p7m), which distinguishes it from the sibling XAdES signing tool even without naming it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus the sibling it__sign_fattura_xades. The mention of 'Uses the signer microservice when available, falls back to direct signing' describes runtime behavior, not when the agent should select this tool or what conditions make it the wrong choice.

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

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

With no annotations provided, the description carries full behavioral burden. It discloses that signing is irreversible and requires confirmation, that it uses a signer microservice with fallback, and that the certificate must be qualified PKCS#12. This is meaningful behavioral context beyond the bare action, though it omits details like error handling or side effects on the original file.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with the core action, and each sentence adds a distinct fact (extension retention, certificate requirement, fallback behavior, confirmation). No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description does not describe return values or expected result format. Combined with 0% schema coverage and unexplained parameters, the agent is left without enough information to invoke the tool reliably. The complexity of the tool (4 params, security-sensitive) demands more than this.

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

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

Schema coverage is 0%, so the description must explain parameters. It implies cert_path and cert_password via the PKCS#12 certificate requirement, but never explicitly names or describes any of the four parameters. confirmation_token is not mentioned at all, and xml is only referenced as the document being signed. This is insufficient for an agent to correctly fill the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action (apply XAdES-BES enveloped XML signature) and the target resource (FatturaPA XML document). It also notes the output retains the .xml extension, which distinguishes it from other signature types like CADES. This is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions prerequisites (qualified PKCS#12 certificate, confirmation for irreversibility) and a behavioral nuance (microservice fallback), but does not explicitly state when to prefer this over the sibling tool it__sign_fattura_cades or any other alternative. It gives some context but lacks explicit when-not guidance.

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

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

With no annotations provided, the description carries the behavioral burden and does disclose important traits: the submission is irreversible, requires confirmation, requires mTLS, and returns the IdentificativoSDI. It does not explain the confirmation mechanism or failure/rejection behavior, but the core safety-critical information is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences with no filler. The core action is front-loaded, followed by prerequisites, return value, and the irreversibility warning. Every sentence adds necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an irreversible submission tool with no annotations and no schema parameter descriptions, the description covers prerequisites, outcome, and confirmation requirement but leaves gaps: how confirmation_token is obtained and used, whether it is actually required given the schema default null, and expected filename constraints. The ambiguity between 'Requires confirmation' and an optional/nullable confirmation_token prevents full completeness.

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

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

Schema description coverage is 0%, yet the description never names the parameters or explains their exact semantics. It vaguely relates to signed_file_base64 by saying the invoice must be signed, and hints at confirmation_token via 'Requires confirmation,' but filename and confirmation_token usage are left unexplained. The description does not compensate for the schema's lack of parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: 'Submit a signed FatturaPA invoice to SDI via SDICoop.' This clearly differentiates the tool from signing, checking status, or parsing SDI notifications among the siblings. It is not a tautology and names the exact submission action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly tells when the tool is appropriate: the invoice must already be signed with XAdES-BES or CAdES-BES, and mTLS certificate configuration must be in place. It implies this is the actual submission step versus validation or signing tools, but it does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description clearly states the core behavior: recomputing SHA-256 and comparing against the stored hash. However, it does not disclose what happens on mismatch (e.g., error vs. boolean result), whether the operation is read-only, or any side effects. The output schema exists but the description doesn't explain the return value semantics beyond the hash comparison.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that front-loads the action and method. Every word earns its place: 'Verify', 'integrity', 'archived document', 'recomputing SHA-256', 'comparing against stored hash'. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a single parameter, an output schema, and no annotations. The description explains the core verification logic but doesn't cover the return value semantics (e.g., what the output schema contains, how success/failure is signaled). Given the output schema exists, the description needn't fully explain return values, but it should at least hint at the outcome representation. The description is adequate for a simple verification tool but leaves some gaps around error handling and result interpretation.

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

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

Schema description coverage is 0%, so the description must compensate. The description mentions 'an archived document' and the hash comparison, which implies document_id identifies the archived document. However, it doesn't add detail about the format of document_id (e.g., UUID, internal ID, or archive reference) or any constraints. The parameter name is self-explanatory, but the description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Verify'), a specific resource ('an archived document'), and the exact method ('recomputing its SHA-256 hash and comparing against the stored hash'). This clearly distinguishes it from sibling tools like it__archive_invoice, it__retrieve_archived_invoice, and it__list_archived_invoices, which perform different operations on archived documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used to check the integrity of an archived document, which is a clear context. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites (e.g., the document must already be archived, or the document_id must reference an existing archive entry). It also doesn't state what to do if the hash comparison fails.

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

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that Italian national fields are returned with defaults, that national extensions are silently ignored, and that failure returns {'error': str}. This is meaningful behavioral context beyond the schema. It could add more about side effects (none expected) or exact error conditions, but the disclosed behaviors are valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core action and output format appear in the first sentence, followed by the Italian-field caveat, use cases, and return behavior. Every sentence earns its place, and there is no redundant restating of the tool name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter parse tool with an output schema, the description is nearly complete. It covers input, output shape, failure mode, and a key behavioral caveat (Italian defaults). It does not explicitly state that the operation is read-only, but parsing is inherently non-mutating and no annotations suggest otherwise. The only minor gap is not describing the output schema's structure, but the output schema exists and the description says it returns a JSON-serialisable dict.

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

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 the single parameter. The description adds context about the parameter's purpose ('CII CrossIndustryInvoice XML string to parse') and the fact that national extensions are ignored, but it does not add format details (e.g., encoding, size limits). Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Parse'), a precise resource ('CII CrossIndustryInvoice XML string'), and the output format ('EN 16931 structured dict'). It also distinguishes itself from siblings by naming the Factur-X / ZUGFeRD use case and explicitly referencing generate_cii_invoice() for round-trip verification, which separates it from parse_fattura_xml and parse_ubl_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: 'Use this to inspect Factur-X / ZUGFeRD invoices, or to round-trip the output of generate_cii_invoice() for verification.' It does not explicitly name alternatives to avoid, but the use cases are specific enough that an agent can infer when this tool is appropriate versus sibling parsers.

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

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

With no annotations, the description carries the behavioral disclosure burden and does so well: it documents the success return shape ('{'versione': str, 'header': {...}, 'body': {...}}') and the error shape ('{'error': '<reason>'}' ). It also discloses the scope of extraction, including optional DatiFatturaRettificata, but does not elaborate on edge cases such as malformed XML beyond returning an error dict or namespace handling beyond the schema note.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized and front-loaded: purpose, usage context, extraction details, and return contract are each covered without redundancy. Every sentence adds useful information, and the list of extracted fields is concise yet informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter parsing tool, the description is substantially complete: it explains what input is accepted, what will be extracted, and what success and error responses look like. The output schema is also present, and the description references a relevant sibling for verification. Minor gaps exist around explicit non-use cases and detailed malformed-input behavior, but these do not hinder correct invocation.

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

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

Schema description coverage is 100%, and the xml_string parameter description already includes format and version details ('Accepts VFSM10 format (namespace v1.0)'). The tool description itself does not add further parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: 'Parse a FatturaSemplificata XML string into a structured Python dict.' It further distinguishes the tool by naming the simplified invoice types (TD07/TD08/TD09) and listing the exact data extracted, so an agent can differentiate it from siblings like parse_fattura_xml or parse_ubl_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete usage guidance: 'Use this to inspect simplified invoices (TD07/TD08/TD09) received from counterparties or to verify output of generate_fattura_semplificata().' This clearly indicates when the tool is appropriate and even references a sibling generation tool for verification, though it does not explicitly state when to avoid it or name a direct alternative for full FatturaPA XML parsing.

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

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

No annotations are provided, so the description fully discloses behavior. It lists exact extracted fields, states that missing fields become null, and documents both success and error return formats—more than typical.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a purpose sentence, usage context, extracted fields list, and return format—all in under 150 words. It is front-loaded with the main verb and resource. Minor redundancy with ''Parse'' in both name and first line.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, it need not explain return values, but it still documents error cases. With only one parameter fully documented, the description thoroughly covers what the tool does, extracted fields, and error handling. It could mention limits on XML size or complexity, but not critical for a parse tool.

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

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

Schema covers 100% of the single parameter, so baseline is 3. The description adds that it accepts two formats and that the string is 'FatturaPA XML', which slightly extends but doesn't add syntax details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb ('Parse') and resource (FatturaPA XML into Python dict). Distinguishes between FPR12 and FPA12 formats, and references related sibling tools (generate_fattura_xml, export_to_json). It does not explicitly name a sibling like parse_fattura_semplificata_xml for differentiation, but the specificity is high.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: to inspect/process invoices and verify generated output. It does not state when NOT to use (e.g., for simplified invoices) or mention alternatives like parse_fattura_semplificata_xml. Provides context but lacks exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses that Italian national fields are returned with defaults because UBL 2.1 does not carry them, and that national extensions are silently ignored. It also states the failure return shape ({'error': str}). This is meaningful behavioral context beyond the schema. It doesn't mention side effects, but parsing is inherently read-only, so the gap is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: a one-sentence core definition, a short paragraph on field behavior, a clear usage sentence, and a two-line return contract. Every sentence earns its place, and the most important information (what it parses and what it returns) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a single parameter, a rich output schema, and no annotations. The description covers the input format, the output format, the handling of Italian fields, the failure mode, and the use case. It doesn't explicitly describe the output schema structure, but the output schema exists and the description says it returns 'the ItalianInvoice fields as a JSON-serialisable dict', which is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the input is a UBL 2.1 Invoice or CreditNote XML string, that national extensions are silently ignored, and that the output is an EN 16931 field dict. This goes beyond the schema's terse 'UBL 2.1 Invoice or CreditNote XML string to parse' and clarifies the behavior for the single parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Parse'), a precise resource ('UBL 2.1 invoice XML string'), and a clear output ('EN 16931 structured dict'). It also distinguishes itself from siblings like parse_fattura_xml and parse_cii_invoice by naming the UBL format and the EN 16931 target. The mention of round-tripping with generate_ubl_invoice() further clarifies its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool: 'Use this to inspect cross-border invoices received in UBL format, or to round-trip the output of generate_ubl_invoice() for verification.' It also implicitly contrasts with parse_fattura_xml (Italian format) and parse_cii_invoice (CII format) by specifying UBL. This is clear, actionable guidance.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses validation rules, the Gruppo IVA special handling rule, the exact success/error return contract, and relevant SdI domain context. This goes well beyond what the schema or annotations would imply on their own.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but densely informative and well structured. It front-loads the purpose, then adds workflow placement, the critical Gruppo IVA exception, validation rules, and the return contract in logical order. Every paragraph earns its place given the domain complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter validation/build tool with no annotations, the description is complete: it explains the workflow position, the special VAT-group behavior, all key validation invariants, and the return shape. The schema already documents individual parameters, and the output schema covers the return structure, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantics beyond the schema by specifying validation constraints: Italian Partita IVA must be exactly 11 digits, codice_fiscale must be 16 alphanumeric characters or 11 digits, and denominazione is mutually exclusive with nome+cognome. This is valuable extra meaning beyond the individual property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Validate and build the CedentePrestatore (seller) block for FatturaPA.' This clearly distinguishes it from sibling validate_cessionario, which is explicitly the buyer-side counterpart, and grounds it in the invoice generation workflow as step 4.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit workflow placement: 'Use this as step 4 in the invoice generation workflow, after build_transmission_header() and before validate_cessionario().' It also names get_regime_fiscale_codes() as the sibling to call for RF code lookup, giving the agent actionable routing between related tools.

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

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden and does it well. It explains how validation happens (parse into EN16931Invoice, check required fields), what it does not do (XSD validation), and enumerates the three possible return shapes including the parse-error case. It lacks explicit statements about side effects, but the pure-validate operation makes them unlikely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded, clearly separating purpose, limitations, and return values. The return-format explanation is somewhat redundant given that an output schema exists, but it does not clutter the description enough to lose more than one point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a single-parameter validation tool with an output schema, and the description covers the operation, its limitations, and all return cases. Even without annotations, an agent can invoke it correctly without needing additional information.

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

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

Schema description coverage is 100%, so the input schema already documents the parameter thoroughly. The description adds context about the structural parsing behavior, but it does not meaningfully expand the parameter's semantic beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: validate a CII CrossIndustryInvoice XML string. It further clarifies the validation scope (structural correctness, required core fields), which clearly distinguishes it from schema-level validation tools like validate_fattura_xsd or validate_ubl_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states what the tool is not for (normative CII D16B XSD validation) and recommends a dedicated CII/ZUGFeRD validator for that, giving clear when-not guidance. It does not explicitly name sibling tools as alternatives, but the distinction is clear enough to allow an agent to choose correctly.

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

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

With no annotations, the description carries full behavioral burden. It discloses the lxml dependency, the specific validation aspects (namespace, element structure, data types, cardinality), and the exact return formats for success, failure, and setup errors. It's thorough for a validation tool, though it doesn't explicitly state there are no side effects (but validation is inherently read-only).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it opens with the core purpose, then usage guidance, dependency, validation scope, and return formats. Each sentence contributes meaning, with no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and an output schema, the description covers all essential context: what it validates, when to use it, the required dependency, and the three possible return structures. Nothing needed to call it correctly is missing.

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

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

The input schema already covers the single parameter xml_string with 100% coverage, including the namespace requirement. The description adds no additional semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Validate'), the specific resource ('FatturaSemplificata XML string'), and the exact schema version (VFSM10 XSD v1.0.2). This distinguishes it from sibling validation tools like validate_fattura_xsd, which targets standard invoices, and leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to 'Call this immediately after generate_fattura_semplificata()' and also mentions use for third-party simplified invoices. This gives precise timing and use cases, effectively guiding the agent on when to select this tool over alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains automatic XSD selection based on the 'versione' attribute, the FATTURA_XSD_PATH override, the lxml dependency, validation scope (namespace, structure, data types, cardinality), and all three return shapes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense without being bloated: it front-loads the purpose, immediately gives workflow placement, then covers XSD selection, dependencies, validation scope, and return values. Every sentence contributes actionable information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers when to invoke, what the input must include, how XSD selection works, failure modes, and exact return structures for success, validation failure, and setup errors. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The input schema already documents xml_string fully, including the root element and namespace, so schema coverage is 100%. The description adds useful meaning beyond the schema by explaining how the document's 'versione' attribute drives XSD selection, which gives the agent a clearer expectation of what the XML string must contain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates a FatturaPA XML string against the official Agenzia delle Entrate XSD v1.2.3, using a specific verb ('Validate') and a specific resource. It also references the official XSD and the XML format, distinguishing it from siblings like validate_fattura_semplificata_xsd or validate_ubl_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit workflow guidance: 'always call immediately after generate_fattura_xml() before storing or transmitting the document' and also covers verifying third-party supplier invoices. This clearly indicates when to use the tool relative to the broader invoice-generation pipeline.

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

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

No annotations are provided, so the description carries the full burden. It discloses that whitespace is stripped, describes the official Agenzia delle Entrate algorithm in detail, and specifies the exact return format for success and failure. This goes beyond the schema and provides substantial behavioral transparency for a validation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured, front-loading the purpose, then usage, algorithm, and return format. It is moderately sized; the algorithm explanation is detailed but necessary for transparency. No redundant content; each sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (a validation algorithm) and the presence of a full input schema, the description is complete: it covers the algorithm, return format, and usage guidance. The output schema is not shown but the return format is explicitly described, so the agent knows what to expect. It also references the follow-up sibling, completing the workflow context.

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

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

The input schema already provides full coverage of the parameter (100%), describing it as an Italian Partita IVA that must be exactly 11 digits and that whitespace is stripped. The description repeats the whitespace note but adds no new parameter-specific information beyond what the schema already states, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates an Italian Partita IVA for format (11 digits) and modulo-10 checksum. It explicitly names the sibling validate_cedente_prestatore as the follow-up, distinguishing its role as an early sanity check. This differentiates it from validate_partita_iva_format (which likely only checks format) and other siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to call this as an early sanity check before passing to validate_cedente_prestatore(), providing a clear when-to-use directive and naming the alternative. It doesn't explicitly compare with validate_partita_iva_format, but the usage context is clear enough.

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

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

With no annotations provided, the description carries the full responsibility for behavioral disclosure, and it excels. It details the processing steps (strips whitespace, checks exactly 11 digits, applies the official algorithm) and explicitly states the return object for both success and failure, including the error key. This fully reveals behavior without contradicting any metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: a first sentence stating the core purpose, a second providing usage context and alternatives, and a third with processing details, followed by a precise return-format specification. Every sentence contributes value, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter validation tool, the description is comprehensive. It covers why to use it (step 1 in workflow), how it behaves (stripping, check algorithm), and what it returns (valid/value/error). No information needed for an agent to call it correctly is missing, even given the output schema is present.

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

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

Schema description coverage is 100%, and the schema's description of the partita_iva parameter already includes 'Italian Partita IVA (VAT number) to validate. Must be exactly 11 digits. Whitespace is stripped before validation.' The tool description does not add meaning beyond this for the parameter itself—it repeats the same facts. Thus, a baseline of 3 is appropriate per the calibration guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('validate'), a clear resource ('Italian Partita IVA'), and the exact criteria (11 digits and modulo-10 checksum). It explicitly distinguishes itself from the sibling validate_partita_iva by naming the alternative and the condition to choose it, leaving no ambiguity about what the tool does or how it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: 'Use this as step 1 in the invoice generation workflow before any other tool.' It also gives a clear when-to-use vs. when-not-to-use by contrasting with validate_partita_iva: 'use this standalone version when you only need the validation result without importing header tools.' This is direct, actionable guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the exact return values for three outcomes (success, failure, parse error), which is critical for agent understanding. It also explains the limitation of not validating against the XSD and the reason (XSD files not bundled). This is solid behavior disclosure, but could be enriched with more detail on the parsing behavior or the nature of warnings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured into clear segments: what it does, what it doesn't do, and return values. It is concise but covers all necessary points. The return value section is separated clearly. It's slightly longer than necessary but every part serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a single-parameter validation function, the description covers the input requirements, the limitations, and the output structure. An output schema exists, so return values are not expected in detail in the description, but they are provided anyway. This is nearly complete; it could mention that it only validates certain invoice types or specify the namespace coverage more, but these are minor.

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

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

The schema description coverage is 100% and the parameter is simple (xml_string with a clear description). The tool description does not add much beyond the schema, but that is acceptable given the schema is already descriptive. The tool description does clarify the input should be an XML string, but this is also in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates a UBL 2.1 invoice XML string for structural correctness, specifying the key fields checked. It distinctly differentiates from siblings like validate_fattura_xsd (XSD validation) and validate_cii_invoice (different format).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes what it does NOT do (XSD validation) and points the user to alternatives: 'For full XSD validation use a dedicated UBL validator or the Peppol Validator tool.' This provides clear guidance on when to use this tool versus others.

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