Imperio — Italian Tax & Compliance Tools

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new traits: it is free (€0), deterministic, and requires no login, which speaks to auth needs and result stability. It stops short of describing the return format, but that is minor for a pure calculator.

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 tight sentences, front-loaded with what the tool computes before the softer marketing traits. Minor redundancy in 'Gratis (€0)' where €0 merely restates Gratis, but overall it wastes little.

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 carries the burden of describing results, and while it names the outputs (imposta sostitutiva, contributi INPS), it gives no sense of the returned structure or fields. For a moderately complex 7-parameter tax calculation, that leaves a gap, though the rich schema offsets it somewhat.

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 schema already documents all 7 parameters, including the ateco/coefficiente alternation and the startup/riduzione_35 flags. The description only restates the fatturato and ATECO inputs and adds no syntax or constraint detail beyond the schema, matching the baseline of 3.

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

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

States a specific verb (Calcola) and resource (imposta sostitutiva e contributi INPS del regime forfettario italiano) and names the input basis (fatturato, opzionale codice ATECO). This clearly distinguishes it from sibling calculators such as calc_iva, calc_imu, or calc_reverse_charge, each of which targets a different regime/tax.

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 scope (regime forfettario) implies when to use it, and the parenthetical 'opzionale codice ATECO' hints at the input model, but there is no explicit when/when-not guidance or reference to alternatives among the many calc_* siblings. Usage must be inferred from the regime name.

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, so safety is covered. The description adds genuine behavioral context beyond that: no login required, free, deterministic, and the exact degraded response shape (`calcolato: false` with explanation and no amount) when the MEF table is unavailable or the Comune is exempt.

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?

Substantial but front-loaded and information-dense: the three property categories come first, then the rate-resolution rule, then failure modes and the free/deterministic note. Every sentence earns its place, though the parenthetical legal citations add length that an agent does not strictly need.

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 15-parameter tool with no output schema and non-trivial tax branching, the description covers the intent, the mutually exclusive input paths, and the error contract. It stops short of describing the successful return payload (only `aliquota_comune` and `calcolato` are named), which is the one remaining gap.

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 parameter docs carry most meaning, setting a baseline of 3. The description goes a step beyond by stating the cross-parameter relationship (aliquota_permille wins over common and the response flags divergence) and by naming the returned `aliquota_comune` field with its legal-status variants.

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

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

States a specific verb and resource ('Calcola l'IMU italiana (L.160/2019)') and immediately enumerates the three supported property bases (fabbricati, terreni agricoli, aree edificabili) with their respective input sources. An agent can distinguish it from every calc_* sibling without opening the schema.

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

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

The description resolves the key input decision explicitly: either pass `aliquota_permille` OR pass `comune` and let the server pull the MEF rate, with the precedence rule stated. It also names the failure conditions (prospetto not yet read, Comuni without IMU such as Trento, Bolzano, FVG). No sibling alternative exists, so nothing more is owed.

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 idempotentHint=true, but the description adds substantial behavioral context: it states the tool is deterministic, free, requires no login, and refuses to choose a threshold for the user, computing two scenarios instead. It also openly admits when it does not calculate the place for certain services. This goes well 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 dense but well-structured and front-loaded with the primary function. Every sentence provides essential information, and the use of semicolons and parentheses keeps it organized without verbosity. It efficiently covers multiple complex aspects 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 high complexity (16 parameters, 5 enums, no output schema), the description is remarkably complete. It covers the main logic, edge cases, the threshold behavior, legislation references, dual bases, territoriality rules, and even hints at output structure (Natura FatturaPA, annotation, norma, and the two scenarios with iva_importo: null). Nothing essential is missing for an 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the overall logic that ties parameters together, such as the dual bases for professionals (contributo integrativo in IVA base only, rivalsa INPS in both) and the dual scenario when soglia_ue_superata is not declared. This adds value beyond the per-parameter schema descriptions, so a 4 is justified.

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

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

The description clearly states the tool's purpose: calculating Italian VAT on a taxable amount with optional withholding tax, and determining territoriality for foreign transactions. It is specific with verbs and resources, and clearly differentiates from siblings like calc_reverse_charge or calc_split_payment through its comprehensive scope.

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 on when to use the tool (e.g., for VAT calculation including territoriality, for professionals with dual bases) and explains behaviors like the dual scenario for undecided EU threshold. However, it does not explicitly name alternatives or state when not to use it, so it misses the explicit exclusion that would warrant 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?

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world. Beyond that the description adds determinism, €0 cost, no login, the 'indicativa / non sostituisce il commercialista' disclaimer, and the composed output shape (structured rows + textual render). It adds real context but the safety profile is largely already covered by 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?

Front-loaded with the core purpose, then the code reference and the composition chain. It is long and dense (extensive tax-code enumerations that partly duplicate schema enum text), but every block is organized and the key routing information leads.

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 steps in to describe returns (sezione, codice, anno, importo, scadenza indicativa + resa testuale) and the extra regola_acconti field. It covers inputs-via-chain, outputs, and limitations for a fairly complex 4-param nested tool, though a little more on error/discrepancy handling (e.g. the bollo importo/numero_fatture mismatch) would complete it.

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

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

Schema description coverage is 100% and the nested forfettario/imu/bollo schemas already document every field, enum and default. The prose tax-code lists and the acconti rule add domain colour, but parameter-level meaning is essentially carried by the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Compone le RIGHE del modello F24') and scopes it to sections Erario/INPS/IMU/bollo. It distinguishes itself from the calc_* siblings by declaring it consumes their outputs, and explicitly negates what it is not ('NON genera il modello ministeriale F24 — né PDF né facsimile').

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

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

Gives explicit when-to-use via the COMPONIBILE chain: input is typically calc_forfettario, calc_imu, parse_fatturapa outputs. States the non-goal (indicative compilation, does not replace the commercialista or Agenzia delle Entrate verification) and adds no-login/no-cost conditions, leaving little to inference.

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?

Annotations cover safety (readOnlyHint true, destructiveHint false, idempotentHint true), and the description adds substantial extra value beyond them: it returns esito 'indeterminato' plus a clarifying question instead of guessing, cites article and comma per reasoning step, is deterministic, free, and login-free. It also enumerates the four high-error edge cases it handles, which materially informs the agent's expectations.

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

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

The core purpose is front-loaded in the first sentence, and the subsequent numbered rules are dense but domain-relevant. The single monolithic paragraph is longer than strictly necessary and some rule detail borders on over-specification, but it is well ordered and largely earns its space.

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 carries the burden of return-value explanation and does so partially (esito 'indeterminato' plus the DOMANDA). Given the complex ten-parameter domain it is otherwise thorough, though a fuller picture of the successful output shape would complete it.

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 rich per-parameter descriptions, so the baseline is 3. The description goes further by explaining how the dimensional parameters combine — the entry threshold (occupati >= 50 OR both financials > 10 M€) and the ceiling logic — which adds interpretive meaning beyond the raw schema.

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

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

States a precise verb+resource: determines whether a subject falls within NIS2 (D.Lgs. 138/2024) scope and whether it is ESSENZIALE or IMPORTANTE. It also positions itself against what it is not ('il pre-volo della dichiarazione', no ACN registration), which cleanly separates it from the lookup siblings nis2_reference and nis2_tipologie.

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 the tool applies (pre-flight applicability assessment, not an ACN filing) and relies on the schema to route the agent to nis2_tipologie for the required tipologia_id. It does not, however, explicitly contrast itself with nis2_reference or name exclusions, so it falls short of full when/when-not/alternative 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, 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 readOnly, idempotent, closed-world, non-destructive. The description adds useful behavioral context beyond them: it is free (€0), deterministic, requires no login, and the content is verbatim from Gazzetta Ufficiale. It does not describe pagination or exact return shape, but adds real value over 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?

Front-loads the resource and then the routing target, with the ATECO warning placed where it prevents a costly mistake. It is longer than a minimal description but the legal-rationale sentence earns its place; nothing reads as 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 read-only catalog listing with full schema coverage and annotations covering the safety profile, the description covers purpose, routing, and the key misconception. It does not spell out the return format or pagination, but given no output schema and rich param docs, the omission is minor.

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

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

Schema description coverage is 100%, so all three parameters (`q`, `limit`, `allegato`) are already fully documented, including the enum meanings. The description only restates 'con ricerca testuale' for `q`, adding no syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: an official catalog of NIS2 subject types from Annexes I–IV of D.Lgs. 138/2024, with text search. It explicitly distinguishes itself from siblings by naming its downstream consumer (`nis2_ambito`) and by ruling out the ATECO→tipologia path that `lookup_ateco`/`search_ateco` might suggest.

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

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

Gives an explicit purpose: find the `tipologia_id` to pass to `nis2_ambito`. It also states a strong when-NOT-to-use: there is no ATECO→tipologia mapping and this tool does not use one, with the legal rationale. The alternative path is unambiguously excluded.

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?

The description goes far beyond the annotations by disclosing deterministic extraction ('NON sono inferiti da un LLM'), exact validation logic (MOD-97, ABI, P.IVA/CF checksums), live VIES behavior with honest degradation ('degradare ONESTAMENTE ad attenzione, mai a un falso ok'), and external I/O limits (one VIES query per call). It also adds cost and authentication context ('Gratis (€0), nessun login'). This is consistent with readOnlyHint since the external I/O is a read-only lookup.

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 dense and every clause earns its place: extraction, verification checks, verdict scale, multi-IBAN handling, VIES budget degradation, cost/auth, and the out-of-band caveat. The verb and scope are front-loaded, with the most important operational constraints following logically.

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 complex tool with no output schema, the description covers return content (parse + supplier_verification verdicts/red flags), failure modes (VIES unreachable, shared budget exhausted), the external I/O constraint, and the safety caveat about out-of-band verification. The input contract is already documented in the schema, so nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds fraud-relevant meaning beyond the schema, such as why party defaults to cedente ('è lui che incassa'), why IBAN is collected only for the cedente, and the red-flag rule that a foreign IBAN on an expected Italian supplier is 'il campanello #1 della frode'. These enrich, rather than merely repeat, 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 opens with a specific verb-resource pair: 'Estrae i dati strutturati da un XML FatturaPA/SDI' and immediately adds the anti-fraud verification performed in the same call. It names the exact checks and distinguishes itself from siblings like parse_fatturapa and verify_payee by combining parsing with verification.

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

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

It clearly states the intended use case ('È la difesa contro la truffa del cambio-IBAN sulle fatture passive') and a key limitation ('NON sostituisce la verifica out-of-band'). It also explains behavior when VIES is down or the budget is exhausted. However, it does not explicitly say when to use this tool instead of parse_fatturapa or verify_payee for standalone needs.

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 cover readOnlyHint, openWorldHint, idempotentHint and destructiveHint, so the baseline burden is lower. The description adds real behavioral value on top: the tool performs external network I/O to VIES, the verdict degrades HONESTLY to 'attenzione' when VIES is down or the budget is exhausted (never a fake 'ok'), it is free with no login required, and the semantics of each verdict value are defined. 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 long but each sentence earns its place: purpose, check list, verdict enum, non_verificabile nuance, external-I/O caveat with degradation behavior, cost/auth, and the out-of-band disclaimer. It is well front-loaded with the core purpose and scoping. It borders on dense, and the VIES dependency is mentioned twice, so it falls just short of a 5.

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

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

With rich annotations (read-only, idempotent, open-world, non-destructive) and 100% schema coverage, the description's job is to cover the gaps — and it does: no output schema exists, yet the description defines the full verdict enum (ok / non_verificabile / attenzione / alto_rischio) and mentions red flags; failure modes (VIES down, budget exhausted) are disclosed; cost and authentication state are stated; and the security limitation is called out. Nothing an agent needs to invoke this safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the validation methodology per identifier (IBAN checksum MOD-97 + ABI bank lookup, VAT/CF checksum, expected_name matched against live VIES ragione sociale) and gives expected_country fraud significance ('Un IBAN estero è il campanello #1 della frode'). The ateco parameter receives no extra color, but the overall enrichment justifies a 4.

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 specifies a concrete verb (verifica anti-frode) and resource (beneficiario/payee) with a clear operational trigger: PRIMA di pagare una fattura, targeting IBAN-change fraud and Business Email Compromise. It distinguishes itself from sibling validators like validate_iban or validate_partita_iva by being a holistic fraud check that returns a verdict plus red flags, and it explicitly calls out 'A differenza degli altri strumenti fa I/O esterno (VIES)'.

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 'when to use' is explicit: before paying an invoice, as an anti-fraud gate. The 'when not to use' is also explicit: 'NON sostituisce la verifica out-of-band (telefonata al fornitore su un numero già noto)'. The description further clarifies the intended interpretation of the non_verificabile verdict so an agent doesn't misread it as an alarm, and differentiates itself from sibling tools through the external-I/O behavior.

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