Imperio — Italian Tax & Compliance Tools

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool is 'Gratis (€0), deterministico, nessun login richiesto', which provides extra behavioral context beyond the annotations. However, it does not describe output format or edge-case behavior, so it offers modest added value.

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

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

The description is a single sentence defining the main purpose, followed by a short second sentence with practical attributes (free, deterministic, no login). It is front-loaded and contains no filler or redundant information.

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

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

Given the rich schema descriptions and strong annotations, the description is largely complete for a calculator tool. It states what is computed and key usage constraints (free, no login), though it does not detail the exact output structure, which is not provided by an output schema.

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

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

All 7 parameters have complete descriptions in the schema (100% coverage), so the baseline is 3. The description merely restates that the tool uses 'fatturato' and 'codice ATECO' without adding new parameter semantics beyond the schema.

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

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

The description uses the specific verb 'calcola' and clearly identifies the resource (imposta sostitutiva e contributi INPS) within the Italian regime forfettario. It also mentions the key inputs (fatturato, codice ATECO), which differentiates it from sibling calculators for other tax regimes.

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

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

The description implies the tool is for regime forfettario calculations, but it does not explicitly state when to use it over alternatives like calc_iva or calc_imu, nor does it mention exclusions or prerequisites. Usage context is inferred from the name and mention of 'regime forfettario italiano', but no explicit alternative guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: free (€0), deterministic, and no login required. It does not describe the output format, but this is a minor gap given the strong annotation coverage.

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

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

The description is two sentences and packs all key facts: purpose, supported use cases, rate source, and behavioral traits. It is front-loaded with the verb and resource, and there is no redundant or filler content.

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

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

Despite the absence of an output schema, the description explains the core calculation scope and legal reference. The schema fills in parameter details. A minor gap is the lack of any statement about what the tool returns (e.g., amount in euros, breakdown), but overall the context is sufficient for a complex 11-parameter calculator.

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

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

Schema description coverage is 100%, and each parameter already has detailed descriptions (e.g., aliquota_permille, rendita_catastale, conditional requirements). The tool description adds only high-level category info and the legal basis, which does not materially go beyond the schema's parameter documentation.

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

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

The description opens with a specific verb and resource: 'Calcola l'IMU italiana' and enumerates the exact property categories (fabbricati, terreni agricoli, aree edificabili). This clearly differentiates it from sibling calculators like calc_iva or calc_forfettario.

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

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

The description gives clear context for when to use the tool: for Italian IMU calculation with specific property types and the municipality rate. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it over sibling tax tools.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context beyond them: it is deterministic, free, requires no login, always exposes base_iva and base_ritenuta separately, zeroes IVA for extraUE, and explicitly refuses to invent OSS rates for private EU consumers. No contradiction exists.

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

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

The description is dense but every sentence earns its place: first the core VAT calculation, then special regimes, then the critical two-basis rule, then cost/determinism/login guarantees. It is front-loaded with purpose and scoped to the tool's complexity.

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

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

Given the tool's 8-parameter complexity, conditional intraUE logic, and absence of an output schema, the description plus detailed schema fully cover the essential business rules: OSS limitations, extraUE zeroing, two-base behavior, and ritenuta rates. The safety profile is already declared via annotations, and the description supplies the domain-specific caveats an agent needs.

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

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

Schema description coverage is 100%, so the structured field descriptions carry the burden for parameters. The tool description adds useful high-level context about how contributo_integrativo and rivalsa_inps affect the two bases, but it does not meaningfully elaborate individual parameters beyond what the schema already says.

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

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

The description states a specific verb and resource: 'Calcola l'IVA italiana su un imponibile' with the exact rate set, optional ritenuta, and non-taxable regimes. It clearly differentiates the tool from siblings like calc_forfettario or calc_reverse_charge by focusing on ordinary Italian VAT on professional invoices.

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

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

The description gives clear context: it is for professional invoices where the contributo integrativo and rivalsa INPS create two distinct taxable bases, and it handles intra-UE/extra-UE non-taxable regimes. It does not explicitly name alternatives or state when not to use it, but the intended scope is evident.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those annotations: it is deterministic, free, requires no login, returns obligations for both parties with applicable legal references, and treats non-EU countries as an explicit error rather than a supported branch. No contradiction with annotations.

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

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

The description is dense but well-organized: purpose and result first, then the three confusing cases with legal references, then operational characteristics. Every clause earns its place and no information is redundant with the structured schema.

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

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

With no output schema, the description compensates by stating what is returned: the VAT amount the buyer must self-assess and the obligations of both parties with the applicable rule. It also clarifies the main edge case (non-EU supplier). It stops short of describing the exact output structure, but is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so all parameters already have descriptions. The description adds meaningful legal nuance to 'paese_cedente' by explaining how its values map to the three reverse-charge scenarios and to the error case, which helps the agent select valid inputs correctly.

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

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

The description uses a specific verb ('Calcola') and a precise resource (IVA dovuta in regime di inversione contabile), and clearly differentiates the tool from generic VAT calculators by naming the three reverse-charge cases it handles. Even without naming siblings, the scope is unambiguous and specific to the tool's domain.

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

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

The description clearly states when to use the tool: for reverse charge calculations involving EU non-IT suppliers, Italian suppliers in specific sectors, and it explicitly says non-EU suppliers are an error case. It provides clear context and an explicit exclusion, though it doesn't name alternative sibling tools like calc_iva or calc_split_payment.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds valuable behavior beyond that: it returns two separate amounts, a liquidity impact, and FatturaPA instructions. It also discloses that the tool is free, deterministic, and requires no login, and it warns about the N6 code misuse, which is useful operational context.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, outputs, FatturaPA caveat, and cost/auth traits. There is no filler or repetition of the schema's parameter descriptions. Front-loading the purpose makes it immediately scannable.

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

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

With no output schema, the description properly explains what the tool returns: two separate amounts, liquidity impact, and FatturaPA instructions. It also covers the key regulatory nuance (N6 not applicable) and the free/authenticated status, making the description self-sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds conceptual context around imponibile and IVA flow, but it does not add new format, default, or constraint details 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.

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

The description opens with a specific verb and resource: 'Calcola la scissione dei pagamenti' for forniture alla Pubblica Amministrazione, backed by the legal reference art. 17-ter DPR 633/72. It also distinguishes itself from reverse charge by explicitly stating that Natura N6 codes belong only to reverse charge, which differentiates it from the calc_reverse_charge sibling.

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

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

The description clearly states when to use the tool: for supplies to the PA under split payment rules. It also gives a meaningful exclusion by noting that N6 codes are not used here and belong only to reverse charge, implicitly steering agents away from this tool for reverse-charge scenarios. It stops short of explicitly naming calc_reverse_charge as the alternative, so it is not a full 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses multiple behavioral traits: determinism, no login required, free usage ('Gratis (€0)'), and the return format ('righe strutturate ... + una resa testuale'). It also clarifies the non-official nature of the output, which is important context the annotations do not provide.

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

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

Despite being long, the description is dense and well-structured: it starts with the core purpose, then covers the three modes with their codes and deadlines, the return type, the expected input chain, and finally the caveats. Every sentence adds valuable information and there is no filler.

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

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

Given the tool's three-mode complexity and the absence of an output schema, the description covers all modes concretely (codes, deadlines, split rules), states the output structure (structured rows + textual rendering), and identifies the exact upstream tools that produce the inputs. It also sets expectations about what it does not do, making the description complete for safe invocation.

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

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

Schema description coverage is 100% with detailed per-field mappings to calc_* outputs, so the baseline is 3. The description adds high-level rules such as IMU split and bollo deferral, but most of the parameter-specific meanings are already in the schema, so the added semantic value is limited.

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

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

The description opens with a specific verb and resource: 'Compone le RIGHE del modello F24' (composes the rows of the F24 model), and enumerates the exact domains (Erario, INPS, IMU, bollo) and their codes. It clearly distinguishes itself from sibling calculators by stating it works 'a partire dagli importi già calcolati' (from already-calculated amounts).

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

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

The description gives explicit when-to-use context by naming the typical input chain: 'l'input tipico sono gli output di calc_forfettario ... calc_imu ... parse_fatturapa'. It also provides an explicit exclusion: 'NON genera il modello ministeriale F24' and notes the result is an indicative compilation that does not substitute professional advice, offering clear boundaries for appropriate use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, showing safety. The description adds useful context: it's free, deterministic, no login needed, and the generated CF is the base variant. No contradiction.

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

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

The description is concise (3-4 sentences), well-structured, and front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately covers input requirements, behavior, limitations (base CF only), and operational details (free, deterministic, no login). It is complete for this tool.

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

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

Schema coverage is 100%, but the description adds meaning by listing key parameters and noting that comune and codice_belfiore are alternatives, and specifying the date format. This goes beyond the schema.

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

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

The description clearly states it generates an Italian Codice Fiscale from personal data, specifying the required fields and noting that the omocodic variant is handled by the agency. It is distinct from sibling tools which are mostly financial calculations and validations.

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

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

The description explicitly says when to use (to generate CF from anagrafic data) and implies that validation is a different tool (validate_codice_fiscale). However, it does not explicitly state when not to use or list alternatives.

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

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

Even though annotations indicate readOnlyHint=false, the description goes further by detailing exact side effects: a never-seen IBAN is recorded as 'pending confirmation' and an alert email is sent to the account holder. It also states the requirement for an API key and that credits are not consumed, providing complete transparency.

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

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

The description is a bit long but each sentence carries necessary warnings and operational details, front-loaded with the core purpose. The 'ATTENZIONE' warning effectively highlights the critical state-modification aspect.

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

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

For a tool with side effects, API key requirement, and a manual follow-up step, the description is remarkably complete. It covers what the tool does, what changes it makes, what it cannot do (confirmation), and where the human confirmation process happens, leaving no major gaps.

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

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

Schema description coverage is 100%, with each parameter already documented. The description adds contextual meaning (IBAN is 'letto su una fattura') but does not explain param relationships (e.g., anyOf requirement) beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: comparing an IBAN from an invoice against the supplier's history and reporting whether it is confirmed, seen but unconfirmed, or never seen. This distinguishes it from sibling tools like validate_iban (syntax validation) and guardian_supplier_status.

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

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

The phrase 'Il gesto anti-BEC' gives clear context for when to use the tool (invoice payment fraud prevention). It also explicitly states that IBAN confirmation is not exposed to agents, indicating a clear non-goal. However, it does not explicitly name alternative tools or scenarios where another tool would be preferred.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: IBANs are returned masked, API key is required, and the operation consumes no credits. This goes beyond what structured annotations provide.

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

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

The description is concise (three short sentences in Italian) and front-loaded with the core purpose, then key details like masked IBANs and authentication/cost. Every sentence carries useful information without fluff.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return content (VIES status, IBAN counts), masking, and auth. It lacks pagination or response structure details, but these are not critical given the simplicity and good annotations.

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

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

The only parameter 'only_alerting' is fully described in the input schema (100% coverage), including its behavior and conditional filtering. The tool description adds no extra parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states 'Elenca i fornitori che questo account sta sorvegliando' (lists monitored suppliers), a specific verb and resource. It further distinguishes from siblings by specifying aggregated VIES status and IBAN confirmation counts, making it an overview rather than a single-supplier tool.

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

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

The description implies usage context (overview of all monitored suppliers) and provides prerequisite/cost info (API key, free credits), but does not explicitly reference alternatives like guardian_supplier_status or state when not to use it. Sibling differentiation is only implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: IBANs are masked (showing only country, bank, last 4 digits), authentication via API key is required, and the operation does not consume credits. This goes beyond the annotations and gives the agent useful safety and privacy information.

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

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

The description is concise and front-loaded, with the main purpose in the first phrase. Subsequent sentences add necessary context (masking, API key, credits) without waste. Every sentence earns its place, and the structure is easily scannable.

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

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

For a simple read-only tool, the description covers the essential context: what it returns, the meaning of the history, masking behavior, and authentication requirements. It does not describe the exact output schema or edge cases (e.g., no IBANs found), but the annotations and schema fill in most gaps. This is sufficient for the tool's simplicity.

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

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

Schema description coverage is 100%, with both 'partita_iva' and 'codice_fiscale' already documented. The description does not add additional parameter-level detail, but it reinforces that the tool applies to a specific supplier. Since the schema fully describes the parameters, a baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the historical record of IBANs for a supplier, with specific statuses (confirmed, pending, rejected) and the time dimension. It uses 'storico degli IBAN visti' as the resource and explains its role as the reference for judging new IBANs, distinguishing it from sibling tools like guardian_check_iban.

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

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

The description provides clear context for when to use this tool: when you need the full history of IBANs for a supplier and their confirmation statuses. It states that it requires an API key and does not consume credits, but it does not explicitly mention alternative tools or exclusion criteria, so it lacks the high bar of explicit when-to-use vs. alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context beyond annotations: it requires an API key, does not consume credits, and specifies what the last check includes (VIES outcome, authoritative flag, elapsed time, anomalies). No contradiction with annotations.

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

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

The description is two sentences and front-loaded. The first sentence directly states purpose and output details; the second covers requirements and cost. No unnecessary words, perfectly concise.

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

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

For a simple read-only tool with two well-documented parameters and no output schema, the description fully explains what the response contains (VIES outcome, authoritative status, time since last check, anomalies) and prerequisites (API key, no credits). Combined with annotations, this is complete.

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

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

Schema coverage is 100%, with descriptions for both parameters (`partita_iva` and `codice_fiscale`). The description adds minimal context beyond the schema, mainly that the tool operates on a supplier within the account (implicitly linking parameters to the account). It does not clarify the anyOf relationship, but the schema already covers that. Baseline 3 is appropriate.

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

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

The description clearly states the tool tells whether a supplier is monitored ('sorvegliato') by the account and details the last verification (VIES outcome, authoritative response, time since last check, anomalies). It uses a specific verb ('Dice') and names the resource (supplier status), distinguishing it from siblings like guardian_watch_supplier or guardian_list_suppliers.

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

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

The description gives clear context: it is for checking surveillance status and last verification details. It also notes the prerequisite of an API key and that the operation does not consume credits. It does not explicitly name alternatives or exclusion criteria, but the context is sufficient for an agent to decide when to use it.

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

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

The annotations only indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds rich behavioral context: IBANs are registered only as 'in attesa di conferma', never as confirmed, with the rationale that an IBAN on a document is not a baseline. It also discloses that excluded items (full plan, already watched, missing identity) are returned counted and motivated, and that it requires an API key but consumes no credits. This significantly goes beyond the annotations.

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

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

The description is concise and front-loaded. The first sentence has the main verb and purpose, subsequent sentences add essential details (IBAN policy, exclusion handling, API key, credits) without redundancy. Every sentence contributes meaning, and the structure is easy to scan.

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

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

For a write tool with a complex nested schema and no output schema, the description is fairly complete. It explains what happens to excluded suppliers ('viene restituito contato e motivato'), the authentication requirement, and the non-consumption of credits. It could be more explicit about the exact response shape or common error cases, but the provided context is sufficient for an agent to understand the operation's scope.

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

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

The schema already provides 100% description coverage, including details like iban entering as 'in attesa di conferma' and expected_country's purpose. The tool description reinforces these with the principle 'MAI come confermati' and explains the exclusion outcome for incomplete identities, adding context about how the system treats the supplier parameters. This adds value beyond the schema, though the schema already does heavy lifting.

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

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

The description clearly states the verb and resource: 'Registra uno o piu' fornitori nel guardiano' (registers one or more suppliers in the guardian) and explains the purpose: so that IBAN changes and VIES variations are intercepted by nightly checks. It distinguishes from sibling tools like 'guardian_check_iban' (which checks IBANs) and 'guardian_list_suppliers' (which lists suppliers), making it uniquely about adding suppliers to surveillance.

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

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

The description clearly implies when to use: when you want to start monitoring suppliers for IBAN/VIES changes. It provides context such as the API key requirement and the fact that IBANs are only marked as 'pending confirmation'. However, it does not explicitly name alternatives or state when not to use, but the sibling tools make the use cases obvious. This is clear context without explicit exclusions.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive, but the description adds substantial behavioral context: it does not generate the telematic file (because it is not publicly reproducible), it never fills missing data silently (explicit errors), it validates VAT offline, and it is deterministic with no login required. This exceeds the baseline set by the annotations.

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

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

The description is dense but front-loaded with the core purpose and validation scope, followed by important limitations, alternatives, and disclaimers. It is long, but for a complex tool with many validation rules, every sentence carries necessary information. It could be slightly more structured with bullet points, but it remains highly informative.

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

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

The description specifies exactly what the tool returns (populated sections, totals, deadline, control report), enumerates the validation rules and exclusions (e.g., XI only for goods, SM/GB rejected), and clearly states the major caveat about not generating the telematic file. Combined with the exhaustive input schema, the agent receives a complete operational picture even without an output schema.

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

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

The input schema has 100% description coverage with detailed explanations of every parameter, including enums, patterns, and cross-field constraints. The tool description adds only high-level guidance like using intrastat_periodicity first and does not provide any field-specific semantics beyond what the schema already offers, so it does not meaningfully enhance the schema's documentation.

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

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

The description clearly states the tool's function: composing and validating INTRASTAT sections from operation rows, assigning each row to the correct section, and returning populated sections, totals, and a control report. It distinguishes itself from sibling tools by explicitly naming intrastat_periodicity and verify_payee for related but different purposes.

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

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

It explicitly instructs to determine periodicity first with intrastat_periodicity and to use verify_payee for live VIES, while this tool only validates offline. It also states that the tool does NOT generate the telematic file and that the official channel must be used, providing clear when-to-use and when-not-to-use guidance.

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

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

The description fully discloses behavioral traits: deterministic, free, no login, deadline calculation with holiday shift, asymmetry of thresholds (>, >=). Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context without contradiction.

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

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

The description is front-loaded with the main purpose but is quite long and dense with regulatory details. While every sentence adds value, it could be more concise. Still well-structured.

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

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

Given the complexity (5 params, thresholds, date calculation), the description is very complete. However, there is no output schema, and the description only hints at return values (normative source, deadline) without full structure. A bit more clarity on output would elevate completeness.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains the ordering and interpretation of ammontari_trimestri_precedenti, the threshold logic, and the specific deadlines. It compensates for the lack of output schema with detailed behavioral information.

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

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

The description clearly states the tool determines INTRASTAT submission periodicity and deadline based on previous quarters' amounts. It distinguishes itself from siblings like intrastat_compose and intrastat_reference by its specific role.

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

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

The description provides context on when to use the tool (e.g., for checking periodicity) and notes it is indicative and not a substitute for professionals. However, it does not explicitly compare to sibling tools or 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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value with 'Gratis (€0), deterministico, nessun login richiesto' and lists exclusions. 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.

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

The description is somewhat lengthy but every sentence adds specific detail. It is front-loaded with the main purpose and structured logically. A minor trim could improve conciseness.

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

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

With no output schema and zero parameters, the description fully compensates by listing all return content and providing usage context. It also mentions sibling tool intrastat_compose for validation.

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

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

Input schema has zero parameters and 100% coverage trivially. Description adds no parameter info because none exist. Baseline 4 is appropriate.

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

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

The description states 'Restituisce, senza alcun input, le tabelle di riferimento INTRASTAT' clearly identifying the verb and resource. It details specific outputs (member states, thresholds, etc.) and distinguishes from sibling tools by noting it requires no input and provides reference data.

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

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

Explicit guidance: 'Usalo per validare gli input prima di intrastat_compose, per popolare un form, o per citare la fonte di una soglia invece di ricordarla a memoria.' Also lists what it does NOT produce, helping the agent decide 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.

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

Description adds value beyond annotations by declaring it's free and requires no login. Annotations already indicate readOnly, idempotent, non-destructive. No contradiction.

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

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

Two short, informative sentences with no wasted words. Each sentence provides essential information.

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

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

For a simple lookup tool with one parameter and no output schema, the description is sufficient. It covers purpose, cost, determinism, and authentication requirements.

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

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

Schema coverage is 100% for the single parameter. The description adds minimal extra meaning (e.g., example format) beyond the schema constraints.

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

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

The description clearly states the tool looks up and validates an ATECO 2007 ISTAT code and returns the activity description. It implicitly distinguishes from sibling 'search_ateco' which likely does a broader search.

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

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

Description mentions it's free, deterministic, and requires no login, which gives context for when to use it. However, it does not explicitly state when not to use it or compare to alternatives like 'search_ateco'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful context beyond them: free (€0), no login required, deterministic, the comune field is always null, and 14 provinces are certainly wrong. These data-quality and access caveats are critical for an agent deciding whether to trust the result. There is no contradiction with the annotations.

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

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

Three sentences all earn their place: the core function, the critical limitations, and the cost/auth summary. It is front-loaded with the main purpose and uses a compact list of example provinces. There is no redundancy or filler.

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

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

For a single-parameter read-only tool with no output schema, the description covers scope, limitations, and auth/cost. It even names response fields like 'comune' and 'province_non_rappresentate', but does not name the main province field or describe behavior for invalid CAPs. It is nearly complete but relies on the agent infering some response details.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the tool uses the 2-digit PREFIX of the CAP to determine the province, which explains why the result can be wrong for some provinces. It also reinforces the 5-digit format already in the schema. It doesn't cover validation behavior for malformed CAPs, so not a 5.

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

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

The description states a specific verb and resource: 'Restituisce la provincia del PREFISSO di 2 cifre di un CAP italiano' (returns the province of the 2-digit prefix of an Italian CAP). It also clearly differentiates itself by explicitly saying it does NOT return the comune. No sibling tool covers CAP lookup, so there is no ambiguity about what this tool does.

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

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

The description gives clear context: use it to get a province from a CAP prefix, and warns when not to rely on it ('per 14 province ... la provincia resa è SBAGLIATA con certezza'). It stops short of naming an alternative tool, but siblings contain no CAP lookup, so the guidance is effective. Without explicit when-to-use vs alternative wording, it doesn't earn a 5.

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

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

The description goes beyond annotations by explaining the tool is deterministic, free, requires no login, and does not record data. It also discloses that it returns 'indeterminato' when data is missing, which is not in annotations. No contradiction with annotations.

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

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

The description is quite lengthy (multiple paragraphs) and includes detailed explanations of common mistakes. While informative, it could be more concise. However, the front-loading of the core function is good.

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

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

Given the complexity of 10 parameters and no output schema, the description covers edge cases, common errors, and the conditions for each parameter. It is nearly complete for an AI agent to understand the tool's behavior.

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

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

With 100% schema coverage, the description adds significant context beyond the schema, such as how to obtain tipologia_id from nis2_tipologie, consolidation rules for impresa_autonoma, and interpretation of criterii_impresa_collegata. This enriches the parameter meaning.

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

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

The description clearly states that the tool determines if a subject falls under NIS2 scope and whether it is ESSENZIALE or IMPORTANTE, citing articles. It also distinguishes from siblings like nis2_tipologie by mentioning that tool for tipologia_id.

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

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

The description provides clear usage context: it is a preliminary evaluation tool, not a legal opinion. It explains when it returns indeterminate and asks for missing data. However, it does not explicitly state when to avoid using this tool compared to alternatives like nis2_reference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: takes no input, deterministic, free, no login required. No contradictions with annotations.

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

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

The description is relatively long but each sentence adds specific value, listing contents in a structured manner. It could be slightly more concise, but there is no redundancy.

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

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

Despite lacking an output schema, the description comprehensively details what the tool returns, including thresholds, formulas, sources, and exclusions. It is fully adequate for a reference tool.

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

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

There are no parameters (schema coverage 100%). With 0 parameters, the baseline is 4. The description does not need to add parameter info, and it correctly avoids misleading statements.

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

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

The description clearly states the tool returns NIS2 thresholds, exact formula, source, relevant articles, criteria, registration window, and exclusions. It uses a specific verb 'Restituisce' and distinguishes itself from sibling tools like nis2_ambito and nis2_tipologie by focusing on reference data.

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

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

The description explicitly advises using the tool to cite thresholds instead of relying on memory. While it doesn't explicitly state when not to use it, the context clearly positions it as a reference tool, which is sufficient differentiation among sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: free, deterministic, no login, search behavior (accent-insensitive, all terms must appear), and the critical caveat about no ATECO mapping. Adds meaningful context beyond annotations.

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

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

The description is verbose, containing multiple warnings and explanatory sentences. While logical, it could be more concise by omitting redundant cautions. Front-loads purpose well.

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

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

No output schema, but the description implies the response includes `tipologia_id`. However, it does not specify the result structure (e.g., list of objects with fields). Adequate but could be more explicit about return format.

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

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

Schema coverage is 100% with good descriptions. The description adds minor extra value: examples for `q`, default for `limit`, and counts per `allegato`. Baseline 3 is appropriate.

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

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

The description clearly states it is the official list of subject types from NIS2 annexes, with search capability. It explicitly positions itself as the tool to obtain `tipologia_id` for use with `nis2_ambito`, distinguishing its role among siblings.

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

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

Provides explicit when-to-use guidance (find tipologia_id for nis2_ambito) and a clear when-not-to-use warning (no ATECO mapping exists). Does not list alternatives 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.

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable non-obvious behavior: deterministic, free, no login required. This goes beyond what annotations convey. No contradiction.

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

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

Two sentences, front-loaded with core purpose and outputs, then additional differentiators and constraints. Every sentence adds value; no unnecessary words.

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

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

Given the tool's simplicity (1 param, no output schema), the description covers purpose, constraints, and cost/auth. It misses potential error cases or return format, but given context, it's largely complete.

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

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

Schema coverage is 100% with a clear description for xml_content. The description reinforces that the parameter is the XML content but adds no additional format or constraints. Baseline 3 is appropriate as description doesn't significantly enhance parameter understanding.

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

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

The description clearly states it extracts structured data (cedente, cessionario, righe, imposte) from FatturaPA/SDI XML. It explicitly distinguishes from the sibling tool parse_verify_fatturapa by noting 'no VIES verification', making the tool's purpose and boundaries unambiguous.

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

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

The description specifies when to use this tool (deterministic parsing only) and explicitly contrasts with VIES verification, guiding the agent away from using it for verification tasks. It also mentions cost and auth constraints (free, no login). Lacks explicit 'when not to use' for other scenarios but sufficient for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes well beyond this by disclosing: extraction is deterministic ('NON sono inferiti da un LLM'), external VIES call behavior with shared budget ('una sola interrogazione VIES per chiamata'), honest degradation to 'attenzione' when VIES is down or budget exhausted, and no login/free. It also explains the checks performed (IBAN MOD-97, P.IVA/CF checksum, VIES comparison). No contradictions with annotations.

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

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

The description is long but front-loaded with the primary purpose and then systematically covers extraction, checks, return format, external I/O, cost, and a caveat. Every sentence contributes operational information (red flags, verdict values, budget constraints, out-of-band warning). It is appropriately structured for a complex tool, though slightly verbose.

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

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

Given no output schema, the description sufficiently covers return values ('Restituisce il parse completo più supplier_verification con verdetto (ok / attenzione / alto_rischio) e red flag puntuali'), input preprocessing (.p7m), failure modes, shared external I/O budget, and free/no-login access. This is complete for a tool with parsing and verification complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains expected_country's fraud-flag role ('Un IBAN estero su un fornitore atteso italiano è il campanello #1 della frode'), clarifies that the default party 'cedente' is the supplier who receives payment, and notes that .p7m must be unpacked before passing xml_content. This elevates the value above the schema alone.

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

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

The description opens with a specific verb+resource: 'Estrae i dati strutturati da un XML FatturaPA/SDI E, nella stessa chiamata, verifica anti-frode la parte indicata' — clearly defining a combined parse-and-verify action. It distinguishes itself from siblings like parse_fatturapa (parse-only) and verify_payee by framing itself as 'la difesa contro la truffa del cambio-IBAN sulle fatture passive'.

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

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

The description provides clear context for when to use the tool ('È la difesa contro la truffa del cambio-IBAN sulle fatture passive') and when not to rely on it exclusively ('NON sostituisce la verifica out-of-band (telefonata al fornitore su un numero già noto)'). It references verify_payee for comparison on external I/O but does not explicitly define alternatives like parse_fatturapa for parse-only needs, so it's clear but not fully exhaustive.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. Description adds critical context: stemmed search, alias support, deterministic, free, no login required. No contradiction found.

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

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

Two dense sentences with no fluff. Front-loaded with purpose and key features. Every sentence adds value.

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

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

For a 3-parameter search tool with no output schema, the description covers behavior, constraints (auth, cost), ordering, and alternatives. Nothing missing.

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

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

Schema coverage is 100%, so baseline 3. Description adds that the search is 'case/accent-insensitive, con stemming e alias per-mestiere', which enhances meaning for the 'q' parameter beyond schema.

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

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

Description explicitly states 'Ricerca full-text sui codici ATECO' using the description, and contrasts with sibling 'lookup_ateco'. Verb 'cerca' and resource 'codici ATECO' are clear, distinguishing from other tools.

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

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

Clearly says when to use: 'quando il codice NON è noto' and points to 'lookup_ateco' for the opposite. Also details case-insensitivity, stemming, and alias handling.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: 'deterministico' reinforces idempotency, 'nessun login richiesto' clarifies auth requirements, and 'Gratis' indicates cost. These details go beyond annotations.

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

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

The description is extremely concise, consisting of a single informative sentence. Every word adds value: the action, resource specifics, key traits (deterministic, no login, free). No filler.

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

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

The description lacks any explanation of the return value or output format. For a validation tool, agents need to know whether it returns a boolean, error messages, or validated data. Without an output schema, the description should compensate but does not.

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

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

The input schema includes a 100% descriptive parameter description. The tool description adds no extra information about the parameter beyond what the schema already provides, so it meets the baseline for high schema coverage.

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

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

The description clearly states the verb 'Valida' and the resource 'Codice Fiscale italiano', adding specifics like format, check digit, and homocody management. This distinguishes it from sibling tools like 'generate_codice_fiscale'.

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

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

The description does not explicitly state when to use this tool versus alternatives (e.g., validate_partita_iva, validate_iban). However, the name and description strongly imply its usage for Italian tax code validation, providing some implicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral context: it is free (possibly cost implication), deterministic (same input always same output), and requires no authentication. This goes beyond annotations by clarifying the operation's cost, determinism, and accessibility.

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

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

The description is extremely concise: two sentences containing only essential information. It front-loads the core function and then adds contextual details without redundancy.

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

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

Given the simple input schema and no output schema, the description could have specified the return value (e.g., validation result plus bank details). It mentions identifying the bank but does not describe the output format. This gap moderately impacts completeness for an agent that needs to understand what the tool returns.

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

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

Schema coverage is 100% and the schema already describes the 'iban' parameter with max length and example. The description does not add further parameter details beyond the schema's information, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Valida' and the resource 'IBAN', specifies the MOD-97 checksum method, and adds the unique feature of identifying the bank for Italian IBANs. It effectively distinguishes this tool from sibling validation tools (e.g., validate_codice_fiscale) by naming a specific resource and operation.

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

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

The description provides context such as 'Gratis, deterministico, nessun login richiesto' but does not explicitly state when to use this tool versus the sibling validation tools. No 'when not to use' or alternative references are given. The guidance is implied by the resource name, but not explicit.

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

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

Annotations already indicate readOnly and idempotent behavior; description adds useful transparency about cost, determinism, and lack of authentication requirements, though it does not describe error handling or output format.

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

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

Single concise sentence covering tool purpose and key attributes with no redundant information.

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

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

For a simple validation tool with no output schema, the description is fairly complete, covering input format and behavioral traits, though it could mention the output (e.g., boolean success or error message).

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

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

Schema coverage is 100% with a clear parameter description including example. The description adds no additional parameter-level detail beyond the schema.

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

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

The description clearly states 'Valida una Partita IVA italiana' with specific format details (11 cifre + checksum Luhn), distinguishing it from sibling tools like validate_codice_fiscale or validate_iban.

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

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

The description provides context (free, deterministic, no login) but does not explicitly state when to use this tool versus alternatives or mention prerequisites.

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

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

Annotations already indicate a read-only, idempotent, non-destructive operation, and the description adds valuable behavioral context: it is free, deterministic, requires no login, and the is_pec_domain result can be null, explicitly distinguishing null from false. This goes well beyond the structured annotations.

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

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

The description is three focused sentences: what the tool does, the critical three-valued output semantics, and the operational characteristics. Every sentence adds essential information and there is no redundant filler.

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

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

With no output schema, the description does well to explain the key is_pec_domain semantics, which is the most important nuance. However, it does not fully specify the overall response shape or behavior for a malformed email, leaving a small gap in return-value understanding.

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

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

Schema coverage is 100%, and the only parameter 'email' is already described in the schema with format and example. The description reinforces that the address is a PEC address and mentions domain checking, but it does not add substantive new parameter semantics beyond what the schema already provides.

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

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

The description names a concrete verb and resource: validate an Italian PEC address, checking format and domain against the AGID list of certified providers. This clearly separates it from sibling validators like validate_iban and validate_partita_iva by focusing on PEC-specific semantics.

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

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

The description establishes clear context: use this tool when an Italian PEC address needs validation against the AGID provider list. It does not explicitly mention when not to use it or name alternative validators, but the domain-specific framing makes the intended use unambiguous.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds crucial behavioral context: external VIES I/O, honest degradation to 'attenzione' when VIES is down or budget exhausted, the never-false-ok guarantee, free/no-login status, and the non-substitution warning. This richly complements the annotation hints without contradiction.

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

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

The description is compact yet information-dense, covering purpose, checks, return verdict, external dependency, degradation behavior, cost, access, and a critical caveat in a few sentences. Every sentence earns its place with no fluff or repetition.

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

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

Given no output schema, the description clearly states what the tool returns (verdict ok/attenzione/alto_rischio + red flags) and covers failure modes, limitations, and placement among alternatives. It is complete for a tool of this complexity—an agent knows how it behaves, when to use it, and what to expect.

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

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

The input schema covers each parameter with descriptions (100% coverage), so baseline is 3. The tool description adds extra semantic context about verification logic, such as IBAN MOD-97 and ABI checks, VIES live name matching, and expected_country defaulting to IT. It does not exhaustively tie every parameter to its checks, but it meaningfully enriches the schema.

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

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

The description states a specific action: 'Verifica anti-frode di un beneficiario PRIMA di pagare una fattura', explicitly distinguishing it from the sibling validation tools by targeting BEC/IBAN-change fraud. It clearly names the resource (beneficiary) and the timing (before payment), going well beyond a generic verb.

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

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

The description clearly specifies when to use the tool ('PRIMA di pagare una fattura'), contrasts it with other tools ('A differenza degli altri strumenti fa I/O esterno (VIES)'), and explicitly states what it does NOT replace (out-of-band verification via phone). This gives an agent practical decision guidance.

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