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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real context: block size (~48,000 OCR characters), signed cursor, that re-sending the cursor re-reads the block without inflating counts, that delivered pages count as read, and the edge case where 'blocco' is non-null leaving a page unread. It references output fields (lettura_completa, blocco) that live in the output schema, so it is not fully self-contained but is behaviorally rich.

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 is front-loaded and the five short lines each add distinct information (scope, workflow, block size, alternatives, edge case). The dense, language-mixed phrasing (Italian prose wrapping English/literal field names like lettura_completa, blocco) costs some readability but there is little outright waste.

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?

An output schema exists, so return values need not be explained, and the description covers the workflow, alternatives, block sizing, cursor semantics and edge cases. What remains thin is the parameter layer (no typed description of 'continuazione' or budget units), but overall it is sufficient to drive correct sequential calling.

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 burden and largely does so: it explains that 'continuazione' is the signed cursor continuation from research_start (first call = the plan, then exactly the previous block's continuation), and the 48,000-character figure maps to budget_caratteri's default. It never formally names or types the parameters, so it compensates well but not completely.

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+resource (reads ALL pages in order, in blocks, without skipping) and explicitly differentiates itself from siblings by naming the alternatives for large sets (elenco/research_list, research_read, research_discard). The scope qualifier 'only for small sets' is clear, though the mixed Italian/English terminology slightly muddies an otherwise precise statement.

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?

Gives explicit when-to-use ('solo per insiemi piccoli', sequential full read), when-not ('per insiemi grandi preferire elenco, research_read e research_discard'), and the required workflow (first pass the research_start plan, then exactly the continuation until lettura_completa=true). An agent can select this tool without inference.

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