Esegui un’operazione di lettura API

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description goes beyond them by clarifying that total-calculation operations are POST yet have no side effects, which explains why a POST-shaped call appears in a read-only tool and prevents the agent from assuming mutation.

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 action and structured with a clear 'use catalog / prefer dedicated tools' ordering. The trailing English sentence largely restates the opening line, adding mild 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?

For a generic dispatch tool with no output schema, it covers what the agent needs: how to identify the operation, the catalog tool for discovery, the shape of query/path/body, and the read-only contract. It could say more about response format or error behavior, but the API reference link partly covers that.

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 75%, so the description must compensate somewhat. It enumerates the query parameters (q, sort, fields, fieldset, page, per_page) and notes that company_id is automatic, adding meaning beyond the schema's generic query/path_params objects, though it does not detail the operationId lookup format.

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: run any read-only Fatture in Cloud API operation identified by operationId, with a link to the API reference. It is clearly a generic escape-hatch read tool, distinct in kind from the specialized siblings, though it does not itself name which sibling to use (that appears in usage guidance).

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?

Explicitly directs the agent: find the operation and its parameters via fic_api_catalog, and for invoices, installments, clients, and situation prefer the dedicated tools. This gives both a when-to-use path and a when-not-to-use rule naming alternatives.

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