Scarica fattura su file

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

ANNOTATION CONTRADICTION: The annotations declare readOnlyHint=true, implying this is a safe read-only operation, but the description and title clearly indicate it downloads/writes a file to disk ('su disco', 'outputPath' parameter, 'Scarica fattura su file'). This is a write/mutation operation (creating files locally), contradicting the readOnlyHint annotation. The description itself is actually accurate, but it contradicts 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?

Single sentence that is dense and informative, enumerating all four formats with parenthetical explanations. front-loads the purpose and format options. Slightly dense but efficient with no wasted 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?

No output schema exists, so the description should hint at return values—it does not. For a 6-parameter, 3-required download tool with a local-file side effect and a conditional format (pdd), the description handles format semantics well but omits confirmation/error behavior (e.g., what happens on success, whether it returns file info, behavior when file exists). The pdd availability condition is a good touch. The contradiction with readOnlyHint also undermines 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%, so all 6 parameters are documented in the schema. The description adds limited extra value: it explains the pdd format availability condition (pddAvailable=true, which is a datum not in the schema). However, it adds nothing about id vs idSdi distinction, filename usage, or how id/idSdi/filename interplay for identification—the schema already covers definitions adequately.

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?

Clear specific verb+resource: 'Scarica una fattura su disco nel formato scelto' with explicit format options (xml, pdf, zip, pdd) and their meanings. Distinguishes itself from sibling tools like search_invoices and get_invoice_detail by describing a file download operation with format choices. The pdd availability note adds specificity beyond siblings.

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

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

The description explains what each format represents (xml=original file, pdf=readable, zip=invoice+SDI notifications, pdd=conservation package), which helps the agent choose the right format. However, it doesn't explicitly state when to use this tool over search_invoices/get_invoice_detail (which could also retrieve data), nor when NOT to use it, and mentions the required direction parameter implicitly without guiding when to pick sent vs received.

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