creg_leer_documento

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond them: the vigencia shown is CALCULATED by vigencia.py rather than read from the Estado row, documents can exceed 50,000 chars (174/2021 over 200,000), the response tells you the next 'desde', and 'buscar' matches case- and accent-insensitively.

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-loaded with the core action, then workflow, then a structured Args/Returns block; every section is useful. There is mild duplication between the Args block and the schema descriptions, and the Returns line restates the vigencia/pagination point already made above.

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 single-argument read tool with full annotation coverage, the description supplies everything an agent needs: where the path comes from, how vigencia is derived, how to paginate long documents, and how to locate text. An output schema exists, yet the description is still clear about what comes back.

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?

With reported schema coverage at 0% for the top-level param, the description's Args block documents all four fields with defaults (ruta, max_caracteres=8000, desde=0, buscar) and explains their pagination relationship. It does not mention the 500–50,000 bound on max_caracteres or the length limits on 'buscar', so it is strong but not exhaustive.

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 and resource ('Lee el contenido completo de un documento regulatorio .md del repositorio') and names the sibling that produces the input path ('Dado la ruta relativa de un documento (obtenida de creg_buscar)'), so an agent can distinguish it from creg_buscar 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?

Gives clear context and a concrete workflow: obtain 'ruta' from creg_buscar, and for citing an article locate it with 'buscar' then read with 'desde'. It does not address when to prefer this over siblings like creg_relaciones or creg_listar_categorias, so it stops short of explicit exclusions.

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