build_sport_worker_exemption_dato_gestionale

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

With no annotations provided, the description carries the full disclosure burden and does so well. It reveals the exact TipoDato value, the legal verification basis, which Riferimento fields are or are not mandated, the caller's discretion in handling them, the success return shape, and the failure return shape when invalid riferimento_data is provided.

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?

Each sentence earns its place: the purpose, legal scope, coded value verification, parameter mandate context, how to pass the result, and the exact return/error shapes. It is detailed yet compact, and an agent can get what it needs without assembling requirements from other sources.

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 specialized build tool with 2 optional parameters and a clearly scoped legal codifica, the description is complete. It explains the legal context, the returned structure, the one failure path relevant to its only risky parameter, and the correct way to further use the result with a sibling tool, so the agent can call it correctly without additional lookup.

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 input schema already provides strong descriptions for both parameters, so the baseline is 3. The description adds extra context beyond the schema: that RiferimentoNumero is not intrinsically mandated by the spec but exists as a caller convenience, and that RiferimentoTesto/RiferimentoNumero are both discretionary for this codifica. That is legal/domain dimension both impossible to get from the plain schema.

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 action (Build the AltriDatiGestionali entry) tied to a precise legal domain (sport-worker IRPEF exemption under D.Lgs. 36/2021) and to a concrete output value (TipoDato 'ESENZSPORT'), which clearly distinguishes this from sibling builder tools. The legal constant, EUR 15,000/year threshold, and the verification reference all reinforce what the tool builds.

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 states clear applicability: compensation under art. 36, comma 6, D.Lgs. 36/2021, exempt up to EUR 15,000/year. It also explains how to use the result with add_linea_dettaglio() and contrasts this codifica with 'ALI-COMP' where RiferimentoNumero is required. It stops short of an explicit 'use when X, do not use when Y' rule, but the conditions are clear enough.

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