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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds materially beyond them: determinism ('SEMPRE uguali a parità di dati'), fixed windows closed three days before the last data point because Amazon attribution is still incomplete, and where the ACoS target is sourced from (cockpit ORC-058 or `acos_max`). It also states org-scope behavior, which is exactly the kind of context annotations cannot carry.

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 and the routing instruction are front-loaded, which is good, but the middle is a single dense paragraph cataloguing roughly fifteen action codes with no formatting, and it is written in Italian while the schema and sibling names are English. Much of it earns its place as reference for the returned `action` column, but the structure makes it harder to scan than it needs to be.

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, and the description compensates well: it names the metric set (ACoS/CTR/CVR/CPC/RPC/AOV), the previous-period comparison, and defines every value of the `action` column, so an agent can interpret results. The main gap is the phantom `account_id` scope parameter and the unexplained shape of the period-over-period comparison, otherwise it is complete for a 7-parameter read-only report.

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 100%, so the baseline is 3, and the description does add real value for `action` (a free-form string in the schema whose valid codes are only defined here) and for the `acos_max` fallback to the cockpit. However, it describes an `account_id` parameter ('senza account_id copre tutti gli outpost autorizzati; con account_id filtra quell'outpost') that does not exist in the input schema, which will mislead an agent into trying to pass it.

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 opening line names a specific resource and behavior: ads performance from the data hub with server-computed, deterministic numbers. The closing line fixes the grain ('Livelli: campaign (default) | keyword | search_term'), and the description explicitly distinguishes it from `execute_sql` and from the `ads_list_*` / `ads_update_*` action loop, so an agent can separate it from siblings without opening a schema.

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 an explicit use-this-instead rule: 'USALO al posto di execute_sql per QUALSIASI domanda su ACoS/spesa/keyword... non riscrivere le formule', plus the follow-up path 'rileggi lo stato live con ads_list_* e proponi la scrittura con ads_update_*'. Both the when and the what-next are stated rather than implied.

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