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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses that there is no hidden semantic expansion, that counts are returned SEPARATI and must not be summed, that the union is only complete under stated conditions, and that proposte_lettura suggestions don't certify relevance. These are valuable behavioral caveats, though the guidance remains dense and partly jargon-laden.

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?

Purpose and routing to research_start are front-loaded, then behavioral caveats follow. Every clause carries information, but the prose is a dense run-on wall that mixes return-format details with workflow rules, slightly hurting scannability.

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 10-parameter, multi-track tool with an output schema, the description covers return semantics (separate counts, next_inizio, union of windows, riscontri) and caveats well. The main shortfall is the missing explanation of modo/ordine/raggruppa, which an agent must infer or ignore.

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 carries the load. It explains ricerche/inizio, the common filters (dal/al/testata), the quanti per-track limits (1-100 elenco, 1-50 dettagliato), and mappa — but leaves three enum params (modo, ordine, raggruppa) entirely undocumented.

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 names a specific operation: a quick multi-query (1-8 'piste') search that returns per-query counts without merging totals. It explicitly contrasts this with research_start for 'una ricerca vera', so the agent can distinguish it from a key sibling without opening either 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 states when NOT to use it ('Per una ricerca vera le stesse piste vanno in research_start') and lays out the intended workflow: orient once with search or archive_coverage, then read results with read_passages, with mappa=false as the normal mode. Alternatives and sequencing are both explicit.

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