mcp-fattura-elettronica-it
Server Quality Checklist
Latest release: v0.7.0
- Disambiguation4/5
Most tools are tied to a distinct workflow block or phase—build, validate, parse, generate, sign, submit, archive—so an agent can usually tell them apart. The main exception is validate_partita_iva and validate_partita_iva_format, which are essentially the same validation with different names and nearly identical descriptions. Looking across 43 tools, that is the only real boundary problem.
Naming Consistency4/5The server is largely snake_case verb_noun naming, and the `it__` prefix consistently groups signing, SDI submission, notification, and archival operations. The main inconsistency is the duplicate validate_partita_iva / validate_partita_iva_format pair, plus the use of several different general verbs like lookup_, check_, get_, build_, and generate_. These are minor deviations, not a chaotic mix.
Tool Count2/543 tools is far outside the typical well-scoped 3–15 range and also well above the 16–25 heavy range. The breadth is intentional and somewhat justifiable because the server covers ordinary FatturaPA, simplified invoices, UBL, CII, signing, SDI submission, notifications, and long-term archiving, but a single MCP server with this many entry points is an overloaded prompt surface. This is a strong candidate for splitting into separate servers.
Completeness5/5The tool surface covers essentially the full Italian e-invoicing lifecycle: lookup/validation codes, invoice block construction, XSD validation and parsing, simplified invoices, UBL/CII formats, digital signatures, SDI submission and notification handling, and conservazione archiving with integrity checks. The only notable limitation is that lookup_codice_destinatario only checks format and does not query live agency registries, but this is clearly documented as a planned future enhancement rather than a dead end. No significant workflow step is missing.
Average 4.5/5 across 43 of 43 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 39 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description is the only behavioral signal. It discloses what the tool creates, including the ZIP format and its contents, but it does not cover side effects, input validation behavior, error conditions, or whether the invoices must already be signed before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted content. The primary action and artifact composition are front-loaded, and the domain context is provided in a single supporting sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is enough for selecting the tool but not for invoking it correctly. Without parameter semantics, especially for `documents_json` and `producer_id`, an agent cannot know what input structure to provide. The existence of an output schema does not compensate for missing input guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the description does not explain either parameter. The agent cannot determine what `documents_json` should contain beyond what its name implies, and `producer_id` is completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Build a Pacchetto di Versamento (PdV) ZIP archive' and explicitly states what it contains — signed invoices and an XML index (IPdV). It distinguishes this from sibling tools like signing or archiving tools because it targets the AgID conservazione transfer artifact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the PdV is the unit of transfer to an AgID-accredited conservazione provider, implying this tool is used when preparing such a transfer. It does not explicitly mention exclusions or alternatives, but the use case is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the main behavior: returns base64-encoded content and archive metadata. However, it omits side effects, error behavior for missing IDs, or any authorization constraints — though for a read operation, the basic behavior is adequately stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no filler, front-loading the action and resource, then stating the return content. It is efficiently structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter retrieval tool, the description is essentially complete with the output schema and the clear mention of returned base64 and metadata. Minor gaps remain around possible failure cases and where document_id comes from, but the core usage context is adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, and the description only repeats the parameter name ('document_id') without explaining its format, origin, or how it relates to archive operations. It adds no meaning beyond the schema's property name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States the specific action 'Retrieve' and resource 'archived invoice', and the key qualifier 'by its document_id'. This clearly distinguishes it from sibling tools like it__list_archived_invoices, which lists invoices without retrieving an individual document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by 'by its document_id' — you should call this when you have a known archived document ID. However, it does not explicitly mention when not to use it, nor does it point to alternatives such as it__list_archived_invoices for discovery or it__verify_archive_integrity for validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It clearly states that the document is stored, that a SHA-256 hash and timestamp are generated per AgID circolare 65/2014, and that retention metadata is added. This goes beyond a vague 'archives this document' and gives the agent a concrete model of what happens. It does not mention errors, permissions, or idempotency, but still provides meaningful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, each offering clear value: what it archives, how it archives it, and what it returns. There is no repetition of the tool name, no boilerplate, and no wasteful phrasing. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description supplies the main system behavior and return metadata, which is aligned with the output schema being present. However, because the input schema has zero described fields and the description gives no parameter-level guidance, an agent is still uncertain how to populate document_base64, format_id, signer_id, and document_id correctly. That makes the definition functionally incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 0% description coverage, so the description must compensate, but it does not map any of the four parameters to the named purpose. It never mentions document_base64, format_id, signer_id, or that document_base64 is the signed invoice XML to be archived. The description's reference to 'the document' is plausibly that document, but it fails to make the connection explicit or explain how the optional parameters affect the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Archive'), a clear object ('a signed invoice'), and a precise domain ('conservazione sostitutiva', per AgID circolare 65/2014). It clearly distinguishes this tool from siblings like retrieve, verify, or list archived invoices, all of which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's usage is implied: it is for signed invoices and for formal legal preservation, so an agent can infer when in the workflow this should be called. However, it does not explicitly state when to use it versus alternatives like it__submit_to_sdi or it__build_pacchetto_versamento, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It meaningfully discloses that the operation is irreversible and requires confirmation, plus it specifies the required XML schema conformance. This is useful beyond the raw schema and gives an agent important safety-relevant context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the primary action, and contains no filler. Each sentence earns its place: the first states what the tool does, the second adds the schema constraint and the irreversible nature of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures the core action, the allowed outcome values, and the critical irreversibility, but it omits details needed for full confidence: what identificativo_sdi refers to, how to construct the XML file, and how the confirmation mechanism works. An output schema exists, which reduces the need to explain return values, but the input-side guidance is still incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no property descriptions, so the description must compensate. It adds value by explaining the valid esito values (EC01/EC02) and by linking esito_xml to a specific XML schema. However, it does not explain identificativo_sdi, nome_file, or the confirmation_token relationship, leaving significant parameter ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and identifies the exact resource and purpose: sending an acceptance or rejection notification to SDI for a received invoice. It also names the specific codes EC01/EC02, which makes the tool's function concrete and distinguishes it from other SDI-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context by saying this is for a received invoice, but it does not explicitly state when to use this tool instead of alternatives like it__submit_to_sdi or it__check_sdi_status. No when-not-to-use guidance or sibling comparisons are provided, so the usage context is clear but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It adds crucial context: it is irreversible, requires confirmation, needs mTLS, and returns the SDI identifier. However, it does not disclose the exact side effects of the confirmation flow, whether a valid confirmation token is mandatory, or what happens if the token is null. For a submission tool with no annotation coverage, a bit more behavioral detail would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each adding unique information. The first sentence states the action; the second adds the prerequisite; the third adds the security requirement and return value; the fourth is a clear warning. The phrase 'Requires confirmation (irreversible)' is slightly ambiguous—it could mean the user must confirm before the action proceeds, but in context with the confirmation_token parameter, it is understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema is present and the description mentions the main return value (IdentificativoSDI), the return contract is sufficiently covered. It clearly states inputs (signed invoice), prerequisites (signature type and mTLS), and side effects (irreversible). It does not describe the acceptance/rejection flow, but the existence of a sibling it__check_sdi_status suggests this tool focuses on submission. Might mention that the submission is asynchronous and status is checked via it__check_sdi_status, but that is extra.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 meaning to signed_file_base64 (the signed invoice) and filename implicitly, and directly ties the requirement of confirmation to the irreversible behavior. However, it does not explicitly state what the format of signed_file_base64 should be (e.g., base64 string encoding the signed XML), nor explicitly say the confirmation_token must be passed to proceed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Submit'), resource ('signed FatturaPA invoice'), target ('SDI via SDICoop'), and outcome ('Returns the IdentificativoSDI assigned by SDI'). It clearly distinguishes this from sibling tools like it__sign_fattura_xades (signing) and it__check_sdi_status (status checking), which cover different phases of the same workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states prerequisites ('must be signed (XAdES-BES or CAdES-BES) before submission', 'Requires mTLS certificate configuration') and mandates confirmation (irreversibility). It does not explicitly say 'use this when you have a signed invoice and want to transmit it, not before signing', but the context makes this inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does a good job by stating that the response is a local status snapshot rather than a live SDI response, which matters for trust and interpretation. It does not detail edge cases like missing/stale identifiers, but the core behavioral caveat is explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of exactly two high-signal sentences: the main purpose and the key asynchronous/local-status caveat. There is no padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-oriented tool with an output schema, the description covers the workflow context (recently submitted invoice, asynchronous SDI status) and the core semantic ('last known local status'). It does not mention error behavior if nothing is on file, or how to obtain the identifier earlier in the flow, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameter. It does say the identifier belongs to the previously submitted invoice and is used as the lookup key, which helps. However, it doesn't provide an example, required format, or where the identifier typically comes from, such as the response from submission.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states the action ('Check the status') and the resource ('a previously submitted invoice'), using the specific 'IdentificativoSDI' as the lookup key. It also clarifies what the tool actually returns: the last known local status, which distinguishes it from submission and notification parsing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is for invoices already submitted and warns that SDI status arrives asynchronously, so the value here is the last locally known state. It does not explicitly name sibling alternatives like it__parse_sdi_notification and when to prefer them, so the guidance is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It clearly communicates that the tool returns configuration details and intentionally does not expose sensitive values such as cert_password, which is useful cautionary context beyond the basic meaning. It does not mention failure modes or environment specifics, but for a zero-parameter read-only getter, the disclosure is reasonably complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense, front-loaded sentence that immediately states the tool's purpose, enumerates the returned fields, and adds the critical security caveat about cert_password. Every phrase earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity—no parameters, no annotations, an output schema present—the description provides enough context for a correct call. It covers what the tool does, what it returns, and what it deliberately withholds. It could additionally state when to call it in a workflow, but the tool is simple enough that this is not a serious gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the default baseline of 4 applies. The description does not need to elaborate on parameter behavior because nothing is required to invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and names a precise resource ('current SDI channel configuration'), then enumerates exactly which fields are returned. This leaves no ambiguity about what the tool does and separates it from the many build/validate/send siblings in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to call when you need current SDI channel configuration, and the read-only tone makes it unlikely the agent would confuse it with submission or validation tools. However, there is no explicit guidance about when to choose this over alternatives or any stated preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the operation is a parse into a structured dict and enumerates supported notification types, but it does not describe behavior for malformed XML, unknown notification types, or validation failures. This is adequate but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is intentionally succinct: two sentences. The supported-type list is compact yet valuable, and every sentence adds real selection and invocation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter parser with an output schema available, the description covers the input domain thoroughly by listing all notification types. The only notable omission is failure-mode behavior, which is not critical enough to make the description incomplete for normal usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter is 0%, but the parameter name notification_xml combined with the description's first sentence makes the intended input unambiguous. No complex formats, defaults, or enums require additional explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific: it names the verb 'Parse', the resource 'SDI notification XML', the output 'structured dict', and enumerates exactly which notification types are supported. This clearly differentiates 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context for when to use the tool: any SDI notification XML matching the listed types. It does not explicitly name alternatives or say when not to use it, but the supported-type list makes the usage boundary reasonably obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses fallback behavior, extension of output, certificate requirement, and that it requires confirmation because it is irreversible. This is reasonably rich behavioral context for a signing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying a distinct piece: what the signature is, input requirements/infrastructure, and safety confirmation. Front-loaded essential info and no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has an output schema (not shown but present), and the description already warns about irreversibility/confirmation, fallback behavior, and certificate requirement. It could mention whether xml is XML content or a file path, but the presence of output schema reduces the need for return-value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 PKCS#12 certificate, which maps to cert_path/cert_password, and the required confirmation maps to confirmation_token. It doesn't explain the xml parameter or the exact format, but the parameter names are self-explanatory. It adds semantic support for coverage zero by giving the meaning of the certificate and confirmation, but leaves xml's expected format (e.g., base64? path?) undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Apply'), resource ('XAdES-BES enveloped XML signature to a FatturaPA XML document'), and a distinguishing detail ('.xml extension retained'). It is clearly distinct from sibling it__sign_fattura_cades.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied context: used to sign FatturaPA XML before submission. Does not explicitly say when to prefer it__sign_fattura_cades over this one, but the format (XAdES-BES) is stated. It gives usage conditions: requires PKCS#12 certificate and confirmation. It does not name an alternative, but among the siblings only cades is a direct alternative, and the description identifies the signature format that selects this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of behavioral disclosure. It explains that only the EN 16931 core field set is extracted, and Italian national fields are returned with defaults. It also specifies the two possible return values (success dict or error dict). This provides sufficient transparency for an XML parser tool, though it could mention that the tool is read-only and has 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loaded with the core action. Each sentence adds distinct information: parsing action, field scope and defaults, and use cases plus output format. There is no redundant or extraneous content, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (single parameter, known output schema), the description covers the input, output format, and error handling. It also provides context about the standard (EN 16931) and Italian defaults. The mention of specific invoice formats (Factur-X/ZUGFeRD) and round-trip verification adds completeness. However, it could briefly note any limitations, such as silent ignoring of national extensions, already mentioned in schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'xml_string', with a description that already explains its purpose and behavior. The tool description does not add significant new semantic information beyond what the schema provides; it merely restates the parameter's role. Thus, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Parse a CII CrossIndustryInvoice XML string into an EN 16931 structured dict.' It specifies the resource (CII XML) and the output format (structured dict). The verb 'parse' and resource are unambiguous, and the mention of CII distinguishes it from sibling tools like parse_ubl_invoice or parse_fattura_xml.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides two use cases: 'inspect Factur-X / ZUGFeRD invoices' and 'round-trip the output of generate_cii_invoice() for verification.' This gives clear guidance on when to use the tool. However, it does not explicitly state when not to use it or list alternatives for other formats, which would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It discloses the flat structural behavior, the absence of DatiPagamento and per-line VAT breakdown, and the exact success/error return contracts. It stops short of stating whether any external submission, side effects, or XSD validation occur, which would make it fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The main verb and resource are front-loaded, and each sentence adds a distinct, decision-relevant fact: document types, amount threshold, structural differences, and return contract. There is no redundant or filler wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, nested XML-document tool with no annotations and no explicit sibling routing, the description gives enough context to select and call it correctly: which document types it supports, what format it produces, how it differs from the ordinary format, and exactly what a success or error response looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides rich descriptions for all 6 parameters and nested objects, and coverage is 100%, so the baseline is 3. The description adds useful context about the overall document but does not materially explain individual parameter semantics beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific action and artifact: 'Assemble a complete FatturaSemplificata VFSM10 XML document.' It then names the exact document types (TD07/TD08/TD09), which clearly distinguishes it from ordinary-FatturaPA siblings such as 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides direct selection criteria: 'Use this for simplified invoices (TD07), simplified credit notes (TD08), and simplified debit notes (TD09)' and limits applicability to transactions 'up to EUR 400.' It contrasts the simplified format with the ordinary FatturaPA, but it does not explicitly name the alternative tool to use when those conditions are not met.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does a reasonable job: it reveals that the operation is a read-only listing and that results are sorted by archive date. It could add sort direction or note about empty results, but for a zero-parameter listing tool this is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences contain no filler. The core operation is stated first, and useful behavioral information about the returned records, sorting, is added without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter listing tool with an output schema available, the description covers the essential behavior and output shape. It says what is returned and the ordering, which is enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is effectively 100%, so no parameter documentation is needed. The description correctly introduces no fake parameters and focuses on the result, which is appropriate for this input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('all archived invoices'), then adds what the result contains ('archive metadata records sorted by archive date'). This differentiates the tool from siblings such as it__retrieve_archived_invoice, which implies retrieving a single invoice rather than listing them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'List all archived invoices' clearly implies the tool is for bulk listing of archive metadata, so the basic usage context is present. However, it does not explicitly state when to choose this tool over alternatives like it__retrieve_archived_invoice, and it provides no exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 the extraction scope, the success return shape, and the error return shape, which is more transparent than most parsers. It does not explicitly state 'read-only' or discuss side effects, but for a pure parsing function the description is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: action, intended use cases, extraction summary, and return shape. It is front-loaded with the main purpose and every sentence contributes without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema and a single parameter already fully described, the description provides a complete picture: how to invoke it, what it extracts, and how it reports failures. It even references the related generator tool for a common use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is concise and already documents the single parameter xml_string and its accepted VFSM10 format. The description adds no additional parameter-level semantics beyond what the schema 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it parses a FatturaSemplificata XML string into a structured Python dict, specifically for simplified invoices (TD07/TD08/TD09). It names the resource and action unambiguously and distinguishes itself from related invoice parsers by focusing on the 'Semplificata' subset and referencing the generator output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: to inspect simplified invoices received from counterparties or to verify output of generate_fattura_semplificata(). It provides clear use context, though it does not name alternative parse tools like parse_fattura_xml or explain when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Always succeeds' and outlines the return format. Since no annotations are provided, the description carries the full burden and adequately discloses behavior, including the deprecation of parent codes, which is helpful for correct usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose, followed by usage guidance and examples. It is efficient but could be slightly more concise by merging the code list into a single line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description fully covers the return format and legal references. It is complete for the tool's intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description does not need to add parameter details, earning a baseline of 4 for no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the complete list of valid Natura exemption codes with legal references. It is specific and distinguishes from sibling tool get_regime_fiscale_codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to call this tool: when add_linea_dettaglio() requires a Natura code with aliquota_iva 0.0. It provides common codes and notes on deprecated parent codes, offering clear context although it doesn't state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the behavioral-disclosure burden. It discloses exactly what operation will be performed: recomputing a SHA-256 hash and comparing it to the stored hash. This is transparent about the verification mechanism, though it does not mention whether the operation is read-only or whether it produces any 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs the action, target, method, and comparison criterion into a compact, front-loaded statement. There is no wasted wording, no obscure jargon, and no repeated content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter operation with an output schema present, the description is nearly complete. It captures the input (document id), the action (hash recomputation), and the comparison logic (against stored hash). It does not mention any prerequisite condition, such as the document needing to be previously archived, but this is a minor gap in an otherwise sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only has one parameter, document_id, with no documentation. The description's 'archived document' wording directly maps to that identifier by semantic context. Since there is only one parameter and it self-evidently names the resource, the description adequately compensates for the missing schema-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise verb ('Verify the integrity') and a specific resource ('an archived document'), and explains the mechanism (recompute SHA-256, compare against stored hash). This clearly distinguishes it from archiving, retrieving, or listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you need to confirm an archived document has not been corrupted or altered, which is clear context. It does not explicitly name alternatives or say when not to use it, but with the archive-focused sibling set, the intended use is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fully discloses behavior without annotations: returns structured dict with versione/header/body, null for missing fields, and two distinct error formats for parse errors and missing lxml. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose. 8 sentences, each informative. Slight redundancy in listing fields twice (abstract and detail), but no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, inputs, outputs, error states, and interoperability. With high schema coverage and output schema present, no gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited value beyond restating the schema. The context about accepting FPR12/FPA12 is already in the schema description. The additional 'export_to_json' reference is not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool parses FatturaPA XML into a structured dict, lists specific use cases (inspect/process invoices, verify generate_fattura_xml), and enumerates extracted fields. Distinguishes from siblings by its specific parsing role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases (inspect/process invoices, verify generate_fattura_xml) and mentions downstream integration with export_to_json(). Lacks explicit when-not-to-use or alternatives, but sibling tools are distinct and no direct competition exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool 'Always succeeds' and describes the return format, which is good. It does not mention side effects because none exist, making it transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each valuable: action, usage guidance, success and return shape. No filler, perfectly sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema clearly described, the description is fully complete for this tool. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description adds no parameter semantics as none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the complete list of RegimeFiscale codes with descriptions, and distinguishes from siblings by mentioning its use as a preliminary step before validate_cedente_prestatore().
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this to look up the correct fiscal regime code before calling validate_cedente_prestatore()' and gives examples for RF01 and RF19. However, it does not explicitly mention when not to use it or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Always succeeds' and describes the return format. This is adequate for a read-only, parameterless tool, though it could note that it is safe and side-effect-free.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two short sentences and a bullet list. It front-loads the purpose and includes only essential information (common codes, return format). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no annotations, and an output schema (referenced in description), the description is complete. It explains what the tool does, why to use it, common codes, and the return structure. It mentions it always succeeds, covering error behavior sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline score is 4 per guidelines. The description does not need to add parameter info. Schema coverage is 100% (trivially).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a complete list of document type codes with descriptions and use cases. It specifies the purpose: to choose the correct TipoDocumento before calling build_dati_generali(). This is a specific verb+resource, and it distinguishes from sibling tools like get_natura_codes and get_regime_fiscale_codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call this before build_dati_generali() and lists common codes. However, it does not mention when not to use it or explicitly compare to other lookup tools, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It discloses the default behavior for Italian fields, the return format (JSON-serializable dict on success, error dict on failure), and the input scope. It could be improved by mentioning potential error types (e.g., invalid XML), but it's already quite transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three well-structured sentences. The first sentence states the core purpose, the second clarifies behavior for national fields, the third provides usage guidance, and a final line specifies return format. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, the presence of an output schema (stated in context), and the clear separation from 25+ sibling tools, the description fully covers the tool's behavior and usage. It explains the special handling of Italian fields and the round-trip verification use case, leaving no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'xml_string' already has a schema description (100% coverage). The main description adds context about the input being a UBL 2.1 invoice XML string and the output, but the schema text already provides the same information. Thus, the description adds minimal extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Parse a UBL 2.1 invoice XML string into an EN 16931 structured dict', specifying the format and target schema. It distinguishes from sibling parsers (parse_cii_invoice, parse_fattura_xml) by focusing on UBL and EN 16931, and mentions handling of Italian national fields, providing unique context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to inspect cross-border invoices received in UBL format, or to round-trip the output of generate_ubl_invoice() for verification.' This gives concrete when-to-use scenarios and implies when not to use (e.g., not for CII or FatturaPA), which are covered by sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that lxml is required, what gets validated (namespace, element structure, data types, cardinality), and all three return shapes: valid, invalid, and setup error. This exceeds typical coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: purpose first, then explicit call timing, then behavior, then return formats. Every sentence earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a single-parameter validation tool with no annotations, the description fully covers when to use it, what it requires, what it validates, and what the agent can expect in all outcome cases. 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema description coverage is 100%, and the schema already explains the required root element and namespace. The tool description adds little parameter-specific detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('validate'), a specific resource ('FatturaSemplificata XML string'), and a specific standard ('VFSM10 XSD v1.0.2'). It is immediately distinguishable from sibling validators such as validate_fattura_xsd, validate_ubl_invoice, and validate_cii_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this tool immediately after generate_fattura_semplificata() and to verify third-party simplified invoices. It does not explicitly name the alternative validate_fattura_xsd for non-simplified invoices, but the 'FatturaSemplificata' scope makes the boundary clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It details the steps: strips whitespace, checks for exactly 11 digits, applies the official algorithm, and specifies the exact return format for success and failure. It does not cover side effects or permissions, but for a pure validation function, the behavioral traits are sufficiently disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 9 lines, structured with clear sections for purpose, usage, steps, and output. Every sentence adds value; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema provided), the description is complete. It explains the validation algorithm, return format, and workflow placement. There are no gaps given the context of sibling tools and schemas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description reinforces the schema by repeating whitespace stripping and digit count. It adds the modulo-10 checksum algorithm detail, but the schema already covers formatting. The additional value is marginal, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 specifies the action and resource, and distinguishes itself from the sibling tool validate_partita_iva by noting it is a standalone version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this as step 1 in the invoice generation workflow before any other tool, and provides a when-not guideline by mentioning the equivalent validate_partita_iva() in header tools for when the validation result is needed without importing headers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description covers validation behavior, success/error return, and that the block is optional; no side effects or destructive actions. Lacks explicit mention of idempotency or concurrency impacts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points under parameter explanations; every sentence provides value without redundancy; front-loaded with purpose and workflow step.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers workflow position, parameter relationships, validation, and success/error response; given 6 params and no output schema needed, it is fully sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant context beyond schema: explains relationship between importo_pagamento and totale_fattura, IBAN requirement for MP05, data_scadenza omission for immediate payment, and validation rules for codes and formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it builds the DatiPagamento block for FatturaElettronicaBody, positions it as step 9 in the workflow, and distinguishes from siblings like build_dati_generali and compute_totali.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (step 9, after compute_totali, before generate_fattura_xml) and mentions optionality but recommendation for B2B. Does not explicitly list when not to use, but workflow context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it discloses the important behavioral boundary: 'This tool performs format validation only, no live query against the SDI SOAP directory service or the IPA registry.' It also describes the per-channel cap as 'reference only, not enforced here', which prevents agents from assuming channel-wide allocation behavior. Success/error return shapes are documented too.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with the core purpose and well-structured into paragraphs and a bulleted routing section. Every part adds context, though the per-channel cap detail is arguably tangential to validating a single code and could be trimmed or moved to a reference note without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers when to call it, what parameters to provide, the of flags, expected return values on success and error, and two important exceptions ('0000000' routing and PEC-only). An output schema exists, so full return-field enumeration is unnecessary; the description is complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage of both parameters, so the baseline is 3. The description adds valuable semantics by explaining the exact routing implications of 6-character, 7-character, and 7-zero codes, plus the PEC-only case. It also makes explicit the non-obvious 'at least one required' constraint despite no required parameters in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Validate the format of a CodiceDestinatario (SDI recipient code) or PEC address.' It goes on to specify the routing outcomes (SDI_CODE vs PEC) and clearly separates this tool from sibling validation or XML-building tools by tying it to build_transmission_header(). This makes the tool's purpose unambiguous and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this before build_transmission_header()' and covers the 'at least one of codice or pec must be provided' requirement. It also clarifies the tool does format validation only and does not perform live lookups, but it does not explicitly compare against sibling validation tools such as validate_cessionario or validate_partita_iva.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description comprehensively discloses behavior: automatic XSD selection based on versione attribute, environment variable override, requirement for lxml, validation scope (namespace, structure, types, cardinality), and detailed return value structures for success, failure, and setup errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, usage, automatic behavior, requirements, and return values. It is slightly verbose but every sentence adds 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is only one parameter with full schema coverage and an output schema exists, the description covers all necessary aspects: what it does, how it works, error handling, and prerequisites. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter xml_string has 100% schema coverage describing it as a complete FatturaPA XML string. The description adds a reminder about the root element and namespace, but does not provide significantly new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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. It specifies the exact resource and action, and distinguishes from sibling validation tools by focusing on full-document XSD validation rather than specific fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use as step 11 immediately after generate_fattura_xml() and also for verifying third-party invoices. This provides clear when-to-use guidance and also implies not to use it for partial validation, which is handled by sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the validation logic (checks core fields), three return states (success, failure, parse error), and limitations (no XSD). This is comprehensive 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one paragraph with clean sections for purpose, detail, note, and return format. Every sentence adds value, with no redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input and explicit output schema, the description covers validation logic, failure modes, and limitations. Missing minor details like what warnings contain, but still highly complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the xml_string parameter. The description adds context about what the tool does but does not elaborate further on the parameter itself beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it validates UBL 2.1 invoice XML for structural correctness, specifying the format and scope. It distinguishes from siblings like validate_fattura_xsd (XSD) and validate_cii_invoice (CII) by format and validation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes the tool does not do XSD validation and recommends alternative validators (Peppol Validator) for full schema validation, guiding the agent on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It reveals key behaviors: 'attachment_base64 must be valid standard base64 (RFC 4648); the tool verifies decodability,' constraints on nome_allegato (max 60 chars, include extension), and the success/error return format. This is comprehensive for a non-destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 120 words) and well-structured: first paragraph states purpose, second gives usage instructions, third details parameters, fourth describes return. Every sentence adds value without redundancy. It's front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters (2 required), an output schema, and moderate complexity. The description covers all essential aspects: what it does, how to use it (including integration with generate_fattura_xml), parameter constraints, and return format. No obvious gaps. The output schema existence reduces need for return details, but description still provides a summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 significant value beyond the schema: it clarifies that attachment_base64 must be valid base64 per RFC 4648, that nome_allegato must include file extension, and that formato_allegato is optional but recommended. It also gives examples. This extra context warrants a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'build an Allegati (attachment) entry to include in a FatturaPA document.' It specifies the verb 'build' and the resource 'Allegati entry', distinguishing it from sibling tools that handle other invoice components (e.g., add_linea_dettaglio, build_dati_generali). The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when you need to attach supporting documents...' and instructs to 'Call once per file, collect results in a list, and pass it to generate_fattura_xml().' It provides clear context for when to use. However, it doesn't explicitly mention when not to use or name alternatives, which would be a minor improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does so well. It reveals the exact TipoDato value, the legal verification basis, which Riferimento fields are or are not mandated, the caller's discretion in handling them, the success return shape, and the failure return shape when invalid riferimento_data is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Each sentence earns its place: the purpose, legal scope, coded value verification, parameter mandate context, how to pass the result, and the exact return/error shapes. It is detailed yet compact, and an agent can get what it needs without assembling requirements from other sources.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a specialized build tool with 2 optional parameters and a clearly scoped legal codifica, the description is complete. It explains the legal context, the returned structure, the one failure path relevant to its only risky parameter, and the correct way to further use the result with a sibling tool, so the agent can call it correctly without additional lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides strong descriptions for both parameters, so the baseline is 3. The description adds extra context beyond the schema: that RiferimentoNumero is not intrinsically mandated by the spec but exists as a caller convenience, and that RiferimentoTesto/RiferimentoNumero are both discretionary for this codifica. That is legal/domain dimension both impossible to get from the plain schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (Build the AltriDatiGestionali entry) tied to a precise legal domain (sport-worker IRPEF exemption under D.Lgs. 36/2021) and to a concrete output value (TipoDato 'ESENZSPORT'), which clearly distinguishes this from sibling builder tools. The legal constant, EUR 15,000/year threshold, and the verification reference all reinforce what the tool builds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states clear applicability: compensation under art. 36, comma 6, D.Lgs. 36/2021, exempt up to EUR 15,000/year. It also explains how to use the result with add_linea_dettaglio() and contrasts this codifica with 'ALI-COMP' where RiferimentoNumero is required. It stops short of an explicit 'use when X, do not use when Y' rule, but the conditions are clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It thoroughly discloses behavior: rate mapping per tipo_ritenuta, override semantics, precedence of importo_override over aliquota_override, validation rules (RT03-RT06 require an override), and both success and failure return shapes. Nothing material about the tool's behavior is hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is substantial but every sentence carries information: usage context, integration steps, rate behavior, override fields, validation, and return values. It is front-loaded with the primary action and then logically organized. No filler or tautology present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a compute-only tool that is pure function rather than a side-effecting operation, the description is complete: it defines input/output, error behavior, validation constraints, and downstrean integration. Even without annotations, an agent receives the necessary and ASU (as a result) to call, interpret, and chain this tool correctly in the larger invoice-building flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% parameter description coverage, so the baseline is 3. The description still adds value beyond the schema by explaining when aliquota_override is required, that overriding occurs for non-statutory cases, the precedence when both overrides are supplied, and the practical meaning of causale_pagamento with examples. It enriches the schema without merely repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Compute ritenuta d'acconto (withholding tax) for professional invoices.' It fully differentiates this from the many sibling build/validate/convert tools by defining its exact role in the invoicing workflow, including when it applies (TD01/TD06) and what it feeds into (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.
Usage Guidelines4/5Does 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' and explains the necessary downstream steps with add_linea_dettaglio() and generate_fattura_xml(). It stops short of explicitly stating when NOT to use it (e.g., no withholding tax applicable), but the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It is transparent about the non-validating behavior, the required top-level dict unwrapping convention, and the exact success and error return shapes, which is exactly the information an agent needs to handle this tool correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and workflow position, followed by a concise breakdown of required, optional, and validation behavior. It contains no filler: every sentence covers a decision-relevant aspect such as prerequisites, return values, or the next step.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers provenance of all inputs, required vs optional parameters, the non-validation caveat, the downstream validation step, and both success and error return contracts. The schema carries the remaining per-block constraints, including the FPA12 batching limitation, so nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all parameters, and the schema descriptions include the source builder/validator tool for each block. The description adds the key convention that the caller must pass the full dict returned by each tool and that the function unwraps the top-level key, though individual parameter format details still live mostly in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb and resource: it assembles a complete FatturaPA v1.2.3 XML document from prepared blocks. It also clearly differentiates this from the validation tool by stating that it does NOT validate against the XSD schema, so an agent can immediately tell assembly from validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions this as step 10 in the invoice generation workflow, requires inputs from the specific builder/validator tools, and tells the agent to call validate_fattura_xsd() as step 11. It lacks explicit routing away from sibling generators such as generate_fattura_semplificata or the UBL/CII tools, but the workflow framing still gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers the output format, encoding, certificate requirement, microservice fallback behavior, and irreversibility/confirmation requirement. This goes well beyond a generic 'sign this document' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences, each packed with useful detail: the signature format, the output format, the prerequisite/fallback behavior, and confirmation. There is 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and annotations are absent, the description supplies what an agent needs: what an input and output look like, when confirmation is expected, what certificate context is required, and how signing behavior can vary. For a signing tool with four parameters, this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 effectively maps to the parameters: 'xml' is the FatturaPA XML, 'requires a qualified PKCS#12 certificate' implies cert_path/cert_password, and 'requires confirmation (irreversible)' implies.confirmation_token. It does not explain exact path/content formats, but it gives enough semantic grounding for the otherwise bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('applies a CAdES-BES attached signature'), the exact target ('FatturaPA XML document'), and the concrete output format (DER-encoded .xml.p7m base64 in response). It clearly differentiates from sibling it__sign_fattura_xades by calling out CAdES-BES/CMS/PKCS#7 as the signature standard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear preconditions and conditions: requires a qualified PKCS#12 certificate, uses the signer microservice when available with fallback, and requires confirmation because the operation is irreversible. It does not explicitly say when to prefer this over it__sign_fattura_xades, but the CAdES/XAdES distinction is strong enough to imply the main routing decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description thoroughly explains internal parsing to EN16931Invoice, checks for required fields, and output structure with success/failure/parse error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise description with front-loaded purpose, followed by essential details. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no annotations, and an output schema in the description, the tool is fully specified. Covers behavior, limitations, and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear description for xml_string. Description could clarify the root element requirement but repeats schema info. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Validate a CII CrossIndustryInvoice XML string for structural correctness', specifying verb, resource, and scope. Distinguishes from sibling tools like 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes that the tool does NOT validate against the normative CII D16B XSD schema and recommends dedicated CII or ZUGFeRD validators for full schema validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the validation algorithm, whitespace stripping, and the exact return format for both success and failure cases. No annotations exist, so the description fully covers behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the main purpose first, then usage, algorithm, and return format. Slightly long due to algorithm details, but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, the description fully covers behavior, output, and usage context. The algorithm details ensure completeness, though it could mention the sibling validate_partita_iva_format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds algorithm details and return structure beyond the schema's format constraint, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool validates an Italian Partita IVA for format (11 digits) and modulo-10 checksum, distinguishing it from sibling tools like validate_cedente_prestatore and validate_partita_iva_format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises calling this as an early sanity check before using validate_cedente_prestatore(), providing clear when-to-use guidance and differentiation from a related tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses validation rules for parameters (e.g., formato_trasmissione must be FPA12/FPR12), and describes both success and failure return values. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the main purpose, then workflow placement, then validation details. Every sentence adds useful information, though slightly verbose for a simple block builder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (5 required), no annotations, but has output schema, the description fully explains validation rules, workflow integration, and error handling. It tells the agent what to do with the result (pass to generate_fattura_xml), making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), but description adds value by specifying that progressivo_invio should be obtained via generate_progressivo_invio() and that lookup_codice_destinatario() should be used to validate codice_destinatario. This extra guidance improves semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it builds the DatiTrasmissione block, a required header in FatturaPA, and specifies its exact position in the invoice generation workflow (step 3). It distinguishes itself from sibling tools by referencing its predecessors and successors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use: after generate_progressivo_invio and before validate_cedente_prestatore. Recommends using lookup_codice_destinatario first. Provides validation conditions and error handling guidance, making it clear when to proceed or stop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: 'Always succeeds', default omission of null fields, and return structure. It explains what the tool does and guarantees success, which is critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 7 sentences, each sentence adds necessary info without redundancy. Front-loaded with purpose and context, then parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and existence of output schema, the description is complete. It covers the tool's role in the pipeline, parameters, behavior, and return type, leaving no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema: for 'indent', it clarifies '0 = compact, 2 = standard readable, 4 = wide'; for 'include_empty', it elaborates on retaining keys; for 'parsed_fattura', it specifies origin from parse_fattura_xml().
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it serializes a parsed FatturaPA dict to a JSON string. It distinguishes from sibling tools like parse_fattura_xml, which parse XML, and generate_fattura_xml, which generates XML. The verb 'serialize' and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'call this after parse_fattura_xml() when you need a human-readable or machine-transferable representation', providing clear when-to-use context. It doesn't specify when not to use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It lists accepted fields policy, return formats for success/validation error/unexpected error, and mentions profile URN specifics. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured, with clear separation of purpose, usage, and return values. Slightly verbose but no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, return values are described in text. Parameter is well covered. Distinguishes from many siblings. Provides complete guidance for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for invoice_data, but description adds useful context about field requirements and profile URN for Factur-X/ZUGFeRD, going beyond schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a CII XML document from an ItalianInvoice dict, specifies the format (CII-D16B), and distinguishes from siblings like generate_fattura_xml for FatturaPA XML.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (for CII wire format, Factur-X, ZUGFeRD) and when not to use (not for FatturaPA), and mentions alternatives like generate_fattura_xml() and generate_ubl_invoice().
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly documents success return values, the warnings behavior for non-standard VAT rates, and the error contract {'error': '<reason>'}. It also exposes workflow-relevant behavior: prezzo_totale is not auto-computed and line numbers must be sequential and unique.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: starting with purpose, moving to workflow position, then conditional parameter rules, and finally return/error contracts. Every paragraph earns its place, and the structure allows an agent to quickly extract the most important call constraints without wading through filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no annotations, part of a larger workflow), the description covers calling order, per-line repeat usage, edge cases like exempt VAT and withholding tax, optional structured data, and both success and failure return shapes. There is no obvious missing information an agent would need to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is already 100%, so the baseline is 3. The description adds meaningful extra semantics beyond the schema: sequential numero_linea enforcement, explicit prezzo_totale requirement, negative values for credit notes, warning on non-standard aliquota_iva, and the XSD ordering of altri_dati_gestionali. This is more than redundant schema restatement, but some of the prose overlaps with existing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Build a single DettaglioLinee (line item) entry for the FatturaElettronicaBody.' It also positions the tool as step 7 in the invoice generation workflow, which makes its role unambiguous among the many sibling build_* helpers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit workflow guidance: call once per line item, after build_dati_generali(), and pass collected results to compute_totali() and generate_fattura_xml(). It also provides when-to-use conditions for natura, ritenuta, credit notes, and optional altri_dati_gestionali, so an agent knows exactly when each behavior applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It reveals that the tool validates input (TD01–TD28, YYYY-MM-DD data, 20-char numero), enforces a workflow precondition, sets reference fields for credit/debit notes, and returns either {'DatiGenerali': {...}} or {'error': '<reason>'}. This gives a clear picture of side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds a distinct piece of information: the purpose, the workflow position, how to select the TD code, credit/debit note required fields, validation rules, and return shapes. It is dense but not redundant, with critical instruction front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers all parameters and the output schema is declared, the description fills the remaining gaps: how the block fits into the larger generation workflow, relationship with get_tipo_documento_codes, special handling for credit/debit notes, validation rules, and success/error return shapes. Nothing an agent would need to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all 8 parameters with descriptions, so baseline is 3. The description adds meaningful conditional semantics beyond the schema: credit notes use TD04, professional fee invoices use TD06, and id_documento_riferimento/data_documento_riferimento must be used together for TD04/TD05. It also clarifies that divisa defaults to EUR for cross-border invoices, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Build' with the resource 'DatiGenerali block required in every FatturaElettronicaBody', making its purpose unambiguous and distinct from sibling tools that build other blocks or validate parts of an invoice. It also places the tool in a named workflow, further identifying its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly places the tool in step 6 of the workflow, identifies the previous (validate_cessionario) and next (add_linea_dettaglio) steps, and mandates calling get_tipo_documento_codes() first. It even gives conditional guidance for credit notes (TD04) and debit notes (TD05) regarding reference identifiers, so an agent knows 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output structure (success and error formats), notes that Italian fields are accepted but not emitted, and includes a caution about profile URN standardisation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and front-loaded, but slightly verbose with the inference note. Still every sentence adds value, and the structure is logical (purpose, usage, parameter details, return values).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (one parameter with many nested fields) and presence of an output schema, the description covers input structure, output format, error handling, and usage boundaries, making it fully self-contained for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% already, but the tool description and schema description add significant context: required vs optional fields, nested structures, example values for profile, address, party, line, and tax fields, and mentions of validation errors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a UBL 2.1 Invoice XML from an ItalianInvoice dict, specifies the use case (cross-border B2B or Peppol-routed), and explicitly distinguishes from the sibling generate_fattura_xml for SdI submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (cross-border/Peppol) and when-not-to-use (SdI, use generate_fattura_xml), describes the behavior for Italian national fields, and gives guidance on the profile parameter with specific examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It discloses what is validated (denominazione vs nome+cognome, RF codes, Partita IVA length, codice_fiscale format), the Gruppo IVA participant-CF requirement, and the exact success and failure 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the primary purpose, then workflow placement, then critical edge-case guidance, then return contract. Every major section serves a purpose, and the SdI reference adds real context without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter validation tool with no annotations, the description covers purpose, workflow order, validation rules, the trickiest Gruppo IVA behavior, return values, and error shape. The schema covers field-level details, and the output schema/description covers the response contract. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description adds cross-parameter meaning beyond individual field docs, especially the Gruppo IVA rule for codice_fiscale and the exact 11-digit Partita IVA requirement when id_paese='IT', which is more than the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb-resource pair: 'Validate and build the CedentePrestatore (seller) block for FatturaPA.' It is clearly distinguished from the sibling validate_cessionario by explicitly stating it is the seller-side block and positioning it in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit workflow placement: step 4, after build_transmission_header() and before validate_cessionario(). It also instructs when to call get_regime_fiscale_codes() and identifies the buyer-side counterpart implicitly via the sibling name and step ordering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes grouping, summation, rounding (HALF_UP to 2 decimals), default EsigibilitaIVA ('I'), and guarantees always succeeds (empty list produces empty DatiRiepilogo). Since no annotations are provided, the description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three paragraphs but each sentence serves a purpose: lead with action, usage guidance, behavioral details, and output format. It is well-structured and front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (grouping, rounding, workflow position) and the absence of an output schema in the input, the description fully covers inputs, behavior, output format, and integration context. It is complete for an AI agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage, but the description adds significant meaning: specifying required fields (prezzo_totale, aliquota_iva) and optional (natura), clarifying that values are raw, not DettaglioLinee dicts. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it computes DatiRiepilogo VAT summary totals grouped by AliquotaIVA and Natura, with a specific verb and resource. It distinguishes itself from sibling tools by positioning it as step 8 in the invoice generation workflow, after add_linea_dettaglio and before 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (step 8 in invoice generation, after add_linea_dettaglio calls, before generate_fattura_xml) and what inputs to pass (raw line values, not DettaglioLinee dicts), providing clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: input validation (invalid prefix returns error), output format, total length constraint, and that random generation is for testing only. It also explains the SDI uniqueness requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, with a clear front-loaded purpose, followed by workflow context, uniqueness note, parameter details, and output. No wasted words; efficient and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and presence of output schema, the description is complete: covers validation, workflow step, constraints, and return values. No gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds significant meaning: prefix example, total length constraint, explicit vs random sequence, and that callers should track their own sequence. It also explains return value structure, exceeding baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a ProgressivoInvio identifier for the DatiTrasmissione block, a specific verb and resource. It distinguishes itself among siblings by positioning as step 2 in the workflow, before build_transmission_header.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow context (step 2 before build_transmission_header) and usage recommendations (use explicit sequence for production, random default only for testing). Also mentions SDI uniqueness requirement, guiding proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavior: validation rules, zero-padding logic, and both success/error return formats. The agent knows exactly what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-structured sentences that front-load the purpose and usage. Every sentence adds value: purpose, when to use, format specification, validation rules, return format. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 2-param simplicity and presence of explicit return format in description, it is fully complete. Output schema is not provided but description covers return fields. Sibling tools are numerous, but this description clearly differentiates itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial context about zero-padding and validation (11 digits, alphanumeric constraints), which is not in the schema descriptions. It clarifies the format and edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Generate the canonical SDI filename for a FatturaPA document', clearly stating the verb and resource. It distinguishes itself from the sibling tool generate_fattura_xml() by noting it produces the filename independently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs when to use this tool: 'Use this when you need the official filename independently of generate_fattura_xml()'. It also provides validation constraints and examples, guiding correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full disclosure burden. It does so thoroughly: it explains the validation behavior, the scarto code 00327 risk, the fact that VAT-group membership cannot be validated offline, and what the function returns on both success and failure including the 'warnings' list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries real information: workflow position, validation rules, per-scenario guidance, the VAT-group warning, and the return contract. The most important usage-bearing content is front-loaded, and the edge-case caveats are deferred to the end where they belong.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no annotations, an output schema, and a large set of sibling tools, the description is remarkably complete. It covers when to call the tool, who the intended buyer types are, what validations happen, what cannot be validated, how warnings are produced, and the exact success/error return contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is already 100%, the description adds significant cross-parameter semantics not derivable from the schema: denominazione mutual exclusivity with nome+cognome, the conditional requirement for id_codice/id_paese, the 11-digit codice fiscale VAT-group caveat, and the specific recommendation to leave id_paese/id_codice empty for Italian B2C buyers with a CodiceFiscale.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Validate and build the CessionarioCommittente (buyer) block for FatturaPA.' It then lists concrete validation rules (denominazione vs nome+cognome, tax-identifier requirements, id_codice/id_paese coupling), which clearly differentiates it from sibling tools like validate_cedente_prestatore and build_dati_generali.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly slots the tool into the workflow: 'Use this as step 5 in the invoice generation workflow, after validate_cedente_prestatore() and before build_dati_generali().' It also gives concrete routing alternatives, such as B2G cases going through build_transmission_header() rather than this tool, and explains which parameter combinations apply to Italian B2C, foreign B2B, and VAT-group buyers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cmendezs/mcp-fattura-elettronica-it'
If you have feedback or need assistance with the MCP directory API, please join our Discord server