it__submit_to_sdi

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

There are no annotations, so the description carries the full burden. It adds crucial context: it is irreversible, requires confirmation, needs mTLS, and returns the SDI identifier. However, it does not disclose the exact side effects of the confirmation flow, whether a valid confirmation token is mandatory, or what happens if the token is null. For a submission tool with no annotation coverage, a bit more behavioral detail would be expected.

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?

Four short sentences, each adding unique information. The first sentence states the action; the second adds the prerequisite; the third adds the security requirement and return value; the fourth is a clear warning. The phrase 'Requires confirmation (irreversible)' is slightly ambiguous—it could mean the user must confirm before the action proceeds, but in context with the confirmation_token parameter, it is understandable.

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 that an output schema is present and the description mentions the main return value (IdentificativoSDI), the return contract is sufficiently covered. It clearly states inputs (signed invoice), prerequisites (signature type and mTLS), and side effects (irreversible). It does not describe the acceptance/rejection flow, but the existence of a sibling it__check_sdi_status suggests this tool focuses on submission. Might mention that the submission is asynchronous and status is checked via it__check_sdi_status, but that is extra.

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 0%, so the description must compensate. It adds meaning to signed_file_base64 (the signed invoice) and filename implicitly, and directly ties the requirement of confirmation to the irreversible behavior. However, it does not explicitly state what the format of signed_file_base64 should be (e.g., base64 string encoding the signed XML), nor explicitly say the confirmation_token must be passed to proceed.

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 ('Submit'), resource ('signed FatturaPA invoice'), target ('SDI via SDICoop'), and outcome ('Returns the IdentificativoSDI assigned by SDI'). It clearly distinguishes this from sibling tools like it__sign_fattura_xades (signing) and it__check_sdi_status (status checking), which cover different phases of the same workflow.

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 states prerequisites ('must be signed (XAdES-BES or CAdES-BES) before submission', 'Requires mTLS certificate configuration') and mandates confirmation (irreversibility). It does not explicitly say 'use this when you have a signed invoice and want to transmit it, not before signing', but the context makes this inferable.

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