Buscando con filtros avanzados

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 so well: it discloses that the server strips accents, that the historic inventory can only be queried by text when 'search' is present (its engine rejects other text combinations), that an EXACT fecha_publicacion is silently degraded to the whole year (with the range workaround), that the historic inventory caps at 1000 pages, and that duplicate rows are dropped with a 'nota'. These are exactly the non-obvious traits an agent needs.

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 a two-sentence summary of scope and inventory-merging before the parameter list, and the Args section is dense but well organized. The main cost is the lengthy 'Devuelve' block spelling out the return payload, which duplicates information already carried by the output schema and could be trimmed.

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 13-parameter merge tool with zero annotation and zero schema-description coverage, the description supplies everything an agent needs: filter applicability per inventory, format rules, catalog references, pagination limits, dedup behavior, and response shape. Nothing material for correct invocation is missing.

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 must compensate for all 13 parameters, and it does: every argument gets format, example, catalog source, and applicability scope (e.g. '00148-2026-HC' for expediente, comma ranges for fecha_publicacion, exact names for demandante/demandado, 'todas'|'algunas'|'frase' for modo, 1-based page). This meaning is entirely absent from the schema and is fully supplied here.

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: an AVANZADA search of the TC that merges the two inventories into a single unified view, with filters applying to both when equivalents exist. The scope is concrete and an agent can picture the operation. It does not distinguish itself from near-siblings such as buscar_sentencias, so it stops short of a 5.

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?

The description explains in detail which filters apply to which inventory (both when equivalent, sistematizacion-only when advanced) and notes that 'proceso' is ignored when 'search' is present, which is genuine conditional guidance. However, it never states when to choose this tool over the sibling tools (buscar_sentencias, resultados_sistematizacion, etc.); it only routes to the catalog helpers listar_filtros and listar_palabras for id values. Tool-selection guidance is implied rather than explicit.

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