it__archive_invoice

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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly states that the document is stored, that a SHA-256 hash and timestamp are generated per AgID circolare 65/2014, and that retention metadata is added. This goes beyond a vague 'archives this document' and gives the agent a concrete model of what happens. It does not mention errors, permissions, or idempotency, but still provides meaningful behavioral detail.

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

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

The description is concise at three sentences, each offering clear value: what it archives, how it archives it, and what it returns. There is no repetition of the tool name, no boilerplate, and no wasteful phrasing. It is well-structured and front-loaded.

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

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

The description supplies the main system behavior and return metadata, which is aligned with the output schema being present. However, because the input schema has zero described fields and the description gives no parameter-level guidance, an agent is still uncertain how to populate document_base64, format_id, signer_id, and document_id correctly. That makes the definition functionally incomplete for correct invocation.

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

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

The schema provides 0% description coverage, so the description must compensate, but it does not map any of the four parameters to the named purpose. It never mentions document_base64, format_id, signer_id, or that document_base64 is the signed invoice XML to be archived. The description's reference to 'the document' is plausibly that document, but it fails to make the connection explicit or explain how the optional parameters affect the operation.

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

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

The description uses a specific verb ('Archive'), a clear object ('a signed invoice'), and a precise domain ('conservazione sostitutiva', per AgID circolare 65/2014). It clearly distinguishes this tool from siblings like retrieve, verify, or list archived invoices, all of which have different purposes.

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

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

The tool's usage is implied: it is for signed invoices and for formal legal preservation, so an agent can infer when in the workflow this should be called. However, it does not explicitly state when to use it versus alternatives like it__submit_to_sdi or it__build_pacchetto_versamento, nor does it mention any exclusions or prerequisites.

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