tax_profile_set

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

With no annotations, the description carries the full burden, and it does disclose one crucial trait: "I campi non passati restano invariati", i.e. a partial merge rather than a replace, which matters enormously for a mutation tool with zero required parameters. It says nothing about permissions, plan gating, validation failures, or what the profile looks like after the write, so the behavioral picture is only half-drawn.

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 content is dense and front-loaded with the core action, but it is delivered as one sprawling sentence stitched together with parentheses and commas, which makes it hard to scan. Several parenthetical examples duplicate information already present in the schema descriptions.

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 an eight-parameter tool with nested oneOf structures and no output schema, the description covers the semantic surface well: what each setting group means, the merge behavior when fields are omitted, and how planned payments feed into cash-flow and F24 output. Remaining gaps — validation behavior and post-write state — are secondary for a configuration setter.

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 already 88%, so the baseline is 3, but the description earns a bump by giving domain meaning the schema only gestures at: concrete coefficient values per ATECO sector (78/67/40/86/62) with worked examples, the 15% vs 5% aliquota rule, and the 26.07% gestione separata rate with the 24% alternative. It maps the abstract `overrides` and `planned_payments` names onto real accounting concepts (acconti versati, rateizzazioni).

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?

"Imposta il profilo fiscale del forfettario" is a specific verb + resource, and the parentheticals enumerate exactly which settings are written (coefficiente, aliquota, previdenza, importi versati, pagamenti pianificati). It is clearly distinct from tax_profile_get and from the simulator/estimator siblings, though the description never names those alternatives to reinforce the contrast.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of prerequisites such as configuring the profile before calling tax_estimate or regime_simulator. The domain hints (which coefficient corresponds to which ATECO) are value-selection help, not usage routing.

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