Leyendo el texto del cuadernillo

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

With no annotations, the description carries the full behavioral burden and does well: the PDF is downloaded into memory, processed page by page, never persisted to disk, with a hard cap of 10 pages per call and case-insensitive matching across all pages. It omits permission/auth requirements, error behavior for invalid codigo, and what the returned page text looks like.

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?

Front-loads the core capability and scope before the Args block; each sentence adds distinct information (search vs range mode, memory-only processing, page cap, query behavior) with no filler or repetition.

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 4-parameter tool with 0% schema description coverage and no annotations or output schema, the description covers access mode, limits, parameter semantics, and roughly what query returns (pages plus context extracts). Return shape for the page-range mode and failure modes for a bad codigo are the remaining minor gaps.

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 0%, so the description must compensate and it does fully: codigo is specified as TIPO+FECHA with a concrete example ('PC20260927'), pagina_desde/pagina_hasta are 1-indexed and inclusive with a 10-page maximum, and query is optional, case-insensitive over all pages, and overrides the range. Every parameter gains meaning beyond the bare 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 verb+resource ('Busca texto DENTRO del PDF de un cuadernillo' / reads its text by pages) and immediately scopes itself within the tool family by declaring it is the only integral-text read path for cuadernillos without an individual page (PC/DJ/JU/CA/IN/TU), which separates it from siblings like obtener_dispositivo_texto.

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 clear conditional guidance: use query to search across an entire PDF (recommended for PDFs of hundreds of pages), otherwise read controlled page ranges, and explicitly states query ignores pagina_desde/pagina_hasta. It implies the alternative (per-page tools) by defining its audience as cuadernillos WITHOUT an individual page, but never names that sibling or states a hard 'do not use when' condition.

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