Stato della fattura elettronica

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description still adds real value: it explains each SDI state's meaning and the follow-up action (error/discarded = correct and resend; rejected = correct; not_delivered = SDI failure) plus that verify_xml sends nothing. It omits any notes on latency of the read itself or auth requirements, keeping it from a 5.

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 purpose is front-loaded and the state enumeration earns its space by being the only documentation of return values. However the trailing English sentence duplicates the opening Italian sentence ('Shows the SDI status of an e-invoice, the rejection reason and optionally verifies the XML') and several states are defined with identical wording, so there is measurable 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?

There is no output schema, so the description must carry the return semantics, and it does: status value, Italian explanation, and rejection reason, with a full state glossary for interpreting the result. Given the two-parameter read-only schema that is nearly complete; only the document_id parameter and the issuer/receiver distinction remain underspecified.

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 50%: verify_xml is documented in the schema, and the description usefully reinforces that it performs a non-sending XML check, which is meaningful. document_id has no schema description and the prose only implies it refers to an issued document, adding little about its format or origin, so a 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?

States a specific verb+resource: it shows the SDI status of an issued document and reports the rejection reason, and it scopes to 'documento emesso' (issued invoices), which helps disambiguate from the received-document siblings. It never names an alternative tool (e.g. fic_get_issued_document) or the boundary between them, so it falls short of a 5.

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 gives concrete usage for one mode ('Con verify_xml controlla l'XML ... senza inviare nulla'), which tells the agent the verification is a dry run with no submission. But it never states when to prefer this over fic_get_issued_document or any sibling, nor any prerequisites, so usage is only implied for the main status-retrieval case.

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