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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: the exact evidence fields gathered, the SUIN-vigencia lookup, the limitation on semantic detection, and the caution that the output is not a legal conclusion.

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 evidence fields, then caveats and the alternative tool. Dense but nearly every clause earns its place; the single long paragraph could be slightly tightened but is well-ordered.

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?

No output schema exists, yet the description explains the json return structure and the markdown default, covers all four parameters' roles, and states the tool's limits. Nothing essential 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that 'sobre' pulls passages from both norms mentioning that theme and details the shape of the json output (fecha_consulta, alcance, sobre, evidencias, avisos) beyond the schema's terse enum note.

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: it gathers EVIDENCE of a possible conflict between two norms, and enumerates exactly what evidence per norm (identification in Gestor, vigencia per SUIN, hierarchy level and character, reform notes). It explicitly differentiates itself from comparar_articulos, so an agent can route correctly without opening the 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?

Explicit when/when-not guidance: it declares it does NOT detect semantic contradictions, that the result is a POTENTIAL conflict and not a legal conclusion, that links must be verified before acting, and that comparar_articulos is the tool for confronting the text of two concrete articles.

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

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

Annotations already cover readOnly/idempotent/openWorld safety, and the description adds substantive behavior beyond them: it does NOT list the norms each diario contains, does not return text, and the diario PDF has no stable link. It also notes the freshness advantage (same-day visibility). No auth or rate-limit detail, but the added context is strong.

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 what it returns, then purpose, then filter mechanics, then exclusions/alternatives. Dense but every sentence carries information; slightly long but not padded.

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 6-parameter read tool with no output schema, the description covers return fields, filter combinations, non-returned data, unstable links, and sibling routing. Nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema can't: tipo and numero_norma must be used together to find the diario that published a norm, with a worked example (LEY + 2466 → 53.160). This genuinely clarifies how to combine filters.

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 resource (published Diarios Oficiales) and the exact fields it exposes (número, tipo de edición, fecha de publicación). It explicitly distinguishes itself from resolver_cita and buscar_normas, so an agent can route correctly without opening schemas.

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 concrete when-to-use context (knowing what was published and when, even same-day, before the Gestor Normativo catalogues it) and explicit when-not-to-use with named alternatives: resolver_cita for a norm's text, buscar_normas for subject searches.

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

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, openWorldHint), so the description is not obliged to restate safety. It nonetheless adds high-value behavioral caveats: the returned vigencia comes from the searcher and is unreliable, the index has gaps ('Teletrabajo' returns zero), and long phrases match on common words. This goes well beyond what annotations declare.

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 purpose, size and searchable fields before the caveats, and every sentence carries operational weight (unreliable vigencia, index gaps, pagination loop, empty-result fallback). It is dense and runs long, but there is little pure filler to cut.

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?

With no output schema, the description still tells the agent what comes back (título, epígrafe, enlace, vigencia) and warns that the vigencia value is not trustworthy. Combined with the coverage gap and empty-result guidance, an agent has everything needed to call this correctly and interpret results.

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 80% (baseline 3), and the description adds meaning on top: it clarifies that vigencia and sector narrow the text search rather than replacing it, and demonstrates the desde/limite pagination arithmetic. It does not add format detail for the free-text query beyond the schema example, 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 ('Busca en los 56.832 documentos de SUIN-Juriscol... por título, epígrafe, materia o entidad emisora') and explicitly scopes out what it is not ('NO busca dentro del articulado'), routing to resolver_cita. An agent can distinguish it from buscar_por_tema, buscar_normas and the many sibling search tools without opening schemas.

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-not conditions and named alternatives: use resolver_cita for exact citations and real vigencia, use buscar_por_tema when a search returns empty. It also explains the pagination loop ('repite la misma llamada con desde = desde + limite'), which is actionable invocation guidance.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses corpus size and recency, the exact return fields (sentencia, tipo, fecha, síntesis, ruta para obtener_documento con fuente="corte"), and a non-obvious engine behavior: the relatoría does not index long phrases, so a retry occurs with the most distinctive word and the response announces it ('se buscó con el núcleo «X»'). That is substantive behavioral context annotations cannot carry.

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?

Dense but front-loaded: identity and corpus first, then return shape, then the query-retry caveat, then sibling disambiguation. Every sentence carries information an agent needs to call the tool correctly; nothing is redundant boilerplate.

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 read-only search tool with no output schema, the description supplies the return fields and the handoff to obtener_documento (fuente="corte"), covers all sibling alternatives, and warns about the long-phrase limitation. Nothing needed to invoke or interpret a call 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: how 'termino' behaves against the relatoría's indexing (long phrases fail, most distinctive word is used), plus a warning that autos are numerous and mostly procedural so they must be requested explicitly. The remaining parameters (desde, hasta, limite) are left to the 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?

Names a specific verb+resource ('Sentencias y autos de la relatoría de la Corte Constitucional') and quantifies the corpus (44.839 providencias, fallos de 2026). It explicitly distinguishes itself from the sibling jurisprudencia tools (Suprema, Consejo de Estado), so an agent can route without opening a 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?

States when to use it ('Es la vía para jurisprudencia constitucional: el Gestor tiene muy poca') and names both alternatives with the condition that selects them: 'para la Suprema usa buscar_jurisprudencia_suprema; para el Consejo de Estado, buscar_jurisprudencia_consejo_estado'. It also tells the agent how to retry when a long phrase fails.

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

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

Annotations already declare read-only, idempotent, open-world behavior, and the description adds substantial non-obvious mechanics on top: exact-phrase search with automatic silent widening to OR plus a warning, OR-mode page counts measuring corpus rather than relevance, limite truncating within a page with dropped results not reappearing, and pagination being page-based because SAMAI doesn't allow free offset. It also discloses what each result contains (problema jurídico + respuesta, SAMAI ficha link, token for obtener_documento).

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 purpose and routing before the mechanics block, and every sentence carries information (routing, result contents, search behavior, pagination caveat). It is dense and long, but not padded; a slight cost in scannability is the only knock.

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?

With no output schema, the description compensates by describing the result payload (problema jurídico and its answer, SAMAI link, download token) and how to fetch full text via obtener_documento with fuente="consejo". Combined with the pagination and exact/OR semantics, an agent has everything needed to call and interpret this tool.

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 100%, so the baseline is 3, but the description adds real semantics the schema only gestures at: the auto-widening behavior of exacto, the fact that limite cuts inside the current page and the excess is lost rather than deferred, and why pagina is used instead of an offset. These are non-obvious operational consequences that materially change how an agent sets the parameters.

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 ('Providencias tituladas del Consejo de Estado') and immediately scopes it to the contencioso administrativo domain with concrete subject matter. It explicitly names the sibling tools for the other high courts (buscar_jurisprudencia, buscar_jurisprudencia_suprema) and the radicado-based alternative (resolver_cita), so an agent can route correctly without opening any 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 explicit when-to-use-this vs when-to-use-sibling routing rules: this tool for Consejo de Estado, buscar_jurisprudencia for Corte Constitucional, buscar_jurisprudencia_suprema for Suprema, and resolver_cita when a specific radicado exists. That is exactly the alternative-selection guidance the dimension asks for.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses that each result carries cited norms resolvable with resolver_cita and a ruta usable with obtener_documento(fuente="suprema"), that the search auto-retries with OR and flags it in the response, and that common words are not dropped. These are actionable behaviors not derivable from structured fields.

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?

Dense, front-loaded and every sentence carries routing or behavioral information, with scope and exclusions stated first. It is heavy on stacked parentheticals, which slightly hurts scanability, but nothing is padding.

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?

With no output schema, the description compensates by describing what a result contains (cited norms, ruta) and how pagination works (limite max 10, use desde for more). For a 7-parameter search tool this is complete enough to call correctly.

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 100%, so baseline is 3, but the description adds real meaning: sala is effectively mandatory per call and defaults to Tutelas, anio/magistrado scope within a sala, and exacto=false should not be used to work around empty results. The exacto widening cost is already in the schema description, so it is partly redundant.

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?

Names a specific verb (buscar) and resource (providencias de la Corte Suprema por sala), gives the covered date range and the four salas, and explicitly excludes the two nearest siblings (Corte Constitucional via buscar_jurisprudencia and Consejo de Estado via buscar_jurisprudencia_consejo_estado). An agent can route to it without opening any 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?

States when to use it, the hard constraint that each call covers ONE sala and defaults to Tutelas only, that civil/laboral/penal questions must name their sala, that anio and magistrado narrow within it, and how to widen a failed exact search. Alternatives are named with their conditions.

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

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

Annotations already cover the read-only/idempotent profile, and the description adds genuinely non-obvious retrieval behavior: the portal indexes only thematic summaries rather than the full articulado, and terms are combined with OR. That directly changes how an agent should formulate a query, which is exactly the kind of context annotations cannot carry.

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 purpose, then flags the critical indexing caveat with IMPORTANTE, then gives the two routing alternatives. Dense but every sentence earns its place; slightly crowded by the two consecutive alternative sentences.

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 an 8-parameter search tool with no output schema and no required parameters, the description covers the essential trap (summary-only index, OR semantics) and the routing to obtener_documento/resolver_cita. It does not describe result shape or ordering, but annotations and the rich schema cover most of the remaining ground.

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 88%, so the schema documents almost every parameter (anio pattern, tema/subtema id prefixes, tipo_documento rejection behavior). The description only adds the OR/few-distinctive-words guidance for palabras, so baseline 3 is appropriate.

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 (busca) plus the exact resources (leyes, decretos, resoluciones, conceptos, sentencias) and scopes them to the Colombian public sector, which cleanly separates it from the jurisprudence- and sector-specific siblings.

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?

Explicitly routes to alternatives by condition: obtener_documento with fuente="gestor" y buscar_en_texto for full-text search inside a norm, and resolver_cita for exact citations. It also tells the agent how to query (pocas palabras y muy distintivas), which is actionable usage guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), but the description adds real behavioral context: it returns no full text, only epígrafe/PDF/ficha, and by default hides personnel acts (two of every three) with a documented override. This is exactly the hidden-default behavior an agent could otherwise miss.

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?

Dense but front-loaded: identity, scope, output limitation, alternative tool, default-hiding behavior with override. Every clause carries actionable information with no filler.

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?

With no output schema, the description correctly explains what comes back (epígrafe, PDF, ficha, not text), and pagination is handled in the schema. Nothing an agent needs to invoke it correctly 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 coverage is 86%, so most parameters are self-documenting. The description still adds meaning beyond the schema by explaining why incluir_administrativos defaults to false and how consequential that default is. Other params (tipo, texto, pagina) add nothing beyond the 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 and resource (resoluciones, acuerdos y circulares de la ANH) plus document count and topical scope (contratos, regalías, fiscalización, reservas). It also distinguishes itself from the sibling resolver_cita by sector. An agent can pick it without opening the 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?

Explicit routing: 'ÚSALA para hidrocarburos y regalías' and 'Para leyes o decretos nacionales de cualquier sector usa resolver_cita'. It also instructs when to toggle incluir_administrativos. Both the when and the alternative are named.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new context beyond that: most results are PDFs without extractable text, validity status is usually absent and where shown is the portal row rather than verification, and each response self-reports what it did.

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 purpose, then the exclusion clause, then caveats — a logical progression. It is dense and parenthetical-heavy, but nearly every sentence carries non-obvious operational information, so little is wasted.

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 7-parameter, no-output-schema tool spanning heterogeneous sources, the description covers the source scope, the routing alternatives, the per-entity filter quirks, and the return-format limitations directly in the text. Nothing an agent needs to call it without guessing 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?

With 71% schema coverage the baseline is ~3, and the description exceeds it: it explains that `entidad` selects the regulator and discloses that filters behave differently per entity (Invima requires text or year; Superfinanciera/Supertransporte default to the current year; ANM ignores year for circulares). Coverage of `limite`/`pagina` is left to the schema, keeping this short of a 5.

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 resource (actos administrativos: resoluciones, circulares, acuerdos) from a specific source class (reguladores y ministerios sectoriales), and explicitly delimits the scope with 'que el Gestor Normativo NO cataloga'. An agent can distinguish it from the national-law siblings without opening any 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?

Contains an explicit 'CUÁNDO NO USARLA' clause that names the alternatives (resolver_cita, buscar_por_tema) and the condition selecting them (leyes y decretos nacionales). It also notes that the Decreto Único Reglamentario per sector is already in the Gestor, steering the agent away from a redundant call.

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

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, but the description adds behavior they cannot convey: ~20 s for the first search of a term because the portal returns the full uncapped result, and that subsequent pages of the same term are instant. This latency and pagination cost model is exactly the extra context the bar asks for.

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 resource, then alternatives, then the performance warning. Every clause carries information (domain, routing, latency), but it is dense and the final warning sentence is long; slightly tighter phrasing would help. No wasted content.

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 read-only search tool with no output schema it states the return shape (extracto y enlace), routes to obtener_documento for the full text, warns about latency, and prescribes a pagination strategy. Nothing an agent needs to call it correctly 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 coverage is 67%: 'texto' and 'desde' are documented, 'limite' is not. The description adds real meaning beyond the schema by explaining that 'desde' should be used to paginate the same term rather than firing new searches, and by hinting at the uncapped result ('no admite tope') relevant to 'limite'. It still never explains 'limite' semantics, so a 4 rather than a 5.

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 resource and scope: the DIAN normogram of decretos, resoluciones, conceptos and circulares in tax, customs and exchange matters, explicitly claiming domain that no other tool covers. It names the sibling (buscar_normas) that does NOT serve this normogram, so an agent can differentiate without opening schemas.

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?

Explicit routing: use obtener_documento with fuente="dian" to read the full document, use resolver_cita for an already-cited law/decree or the Estatuto Tributario, and a warning that buscar_normas does not cover this normogram. When/when-not and the alternative are stated directly.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the description's added value is substantial: it specifies the exact return fields (título, resumen, fecha, enlace PDF) and explicitly that full text is NOT returned, plus two non-obvious behaviors (post-filtering of personal acts affecting page size, and portal dates being web-publication dates rather than norm dates).

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 purpose and routing, then accumulates operational caveats. Every sentence carries actionable information and none are filler, though the density makes it longer than a typical description; it borders on over-packed but remains efficient.

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?

Given no output schema, the description fully compensates by describing the return shape and its limitations, and it covers sibling routing, pagination mechanics, hidden-result filtering, and date semantics. An agent has everything needed to call and interpret results correctly.

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 only 50% schema coverage, the description compensates well: it explains how pagina interacts with limite (block counting, fixed limite during paging) and clarifies the effect of incluir_administrativos via the post-filtering behavior. It does not, however, add much to the texto parameter beyond the schema's own examples.

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 (buscar circulares y resoluciones de la UPME), enumerates the content types covered (convocatorias de transmisión y gas, planes de expansión, actos administrativos), and immediately distinguishes itself from siblings buscar_resoluciones_creg and resolver_cita. An agent can identify the correct source without opening any 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?

Explicitly routes the agent: CREG queries go to buscar_resoluciones_creg and laws/decrees go to resolver_cita. It also states operating constraints (don't change limite while paginating) and explains when a short page is not the last one, which prevents misuse of pagination.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial operational context beyond them: it answers from a packaged index instantly and without network, falls back to the Gestor portal only when a term is missing, and clarifies that 'limite' counts theme/subtheme rows rather than documents.

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?

The purpose is front-loaded and every sentence carries distinct operational value (return shape, fallback behavior, id format, cross-tool routing). It is dense and slightly long, but there is little genuine 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?

With no output schema, the description fully carries the burden: it describes the returned fields, the per-row cap of 8, the temsubid/normid identifiers with their 'ts-' prefix, and how to feed those ids to explicar_relacion_tema from the same row.

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 only 50%; 'texto' is documented in the schema, but the description rescues 'limite' by explaining it counts theme/subtheme rows, not documents. It does not add syntax detail for 'texto', so it is strong but not exhaustive given the coverage gap.

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 ('Consulta temática oficial') and enumerates exactly what it returns: tema, subtema, and the associated normas, sentencias and conceptos. It also distinguishes itself from siblings by naming resolver_cita for a single norm and buscar_normas for keyword searching.

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 routing: use this for thematic consultation, resolver_cita for a specific norm, and buscar_normas for word-level searching across summaries. It also states the runtime behavior of when it hits the network versus the local index.

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

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

Beyond the annotations (which already declare safe read-only/idempotent behavior), the description discloses substantive traits: each query traverses ONE compilation of ONE year, texto never filters by content, no anio means only the current year, the vigencia flag is transferred literally and must not be collapsed to yes/no, and full text requires obtener_documento(fuente="creg").

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 every sentence carries operational value, but the body is one dense semicolon-chained block that is harder to scan than it needs to be. Slightly more structural separation would improve it without losing content.

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?

With no output schema, the description supplies the return shape (número, año, epígrafe, estado, ruta de lectura) and explains the cross-parameter interaction that governs results. For a filter/list tool with an openWorld hint, nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the absence of anio silently scopes to the current year, texto filters only by número/año/epígrafe and never by content, and compilacion="todas" spans the same year. limite receives no extra explanation, keeping this at 4 rather than 5.

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 ('Resoluciones de la Comisión de Regulación de Energía y Gas') and enumerates the substantive domains (tarifas, conexión, comercialización, plantas solares, gas natural). It also names the sibling tools it is NOT (buscar_normativa_upme for UPME, resolver_cita for laws/decrees), so an agent can route without opening schemas.

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 conditions and alternatives: pass anio even when the number appears in texto; use "todas" to merge vigentes+derogadas of a year; use buscar_normativa_upme for UPME and resolver_cita for national laws/decrees. This is a near-complete routing rubric.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive, openWorld), and the description layers on non-obvious behavior: limite is per-source so totals multiply, a failed source is reported as a failure rather than an empty result, SUIN vigencia is engine-labeled and not the official record, and results carry a ready 'Para leer' call to obtener_documento. This is real operational context beyond the structured fields.

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 come first, then parameter precedence, then output/caveats, which is well front-loaded. It is dense and runs long, but each clause carries a distinct constraint (per-source limit, override rule, vigencia caveat, failure semantics), so there is little filler.

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?

No output schema exists and the description compensates by describing the result payload (source, link, 'Para leer' call) and the failure behavior. For an open-world aggregator with five parameters and no output schema, nothing an agent needs to call or interpret it appears to be 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 coverage is 100% (baseline 3), but the description adds precedence semantics the schema does not: passing fuentes overrides the profile source set and perfil then only orders, and perfil's sector-to-source additions (salud → INVIMA/Supersalud, mineria → ANM) are spelled out. It stops short of documenting formato json field contents beyond what the schema already lists.

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 a concrete resource set: parallel search across four named sources, aggregating results with source and link. It also positively distinguishes itself from siblings (resolver_cita for exact citations, court-specific search engines for a single tribunal), so an agent can separate it from the ~25 search siblings without opening a 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?

Explicit routing rules: use when the query is open/subject-based and no obvious tool exists; use resolver_cita for exact citations and the court-specific searcher for a concrete tribunal. This gives both when-to-use and when-not-to-use with named alternatives.

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

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

Annotations already declare the safe read-only, idempotent, open-world profile, but the description adds real behavioral context: only the year of `desde` is honored, undated notes are discarded, each citation resolves independently, and a failed citation is recorded rather than aborting the batch. It also sketches the returned content (acción, norma modificadora, artículo, nota). It stops short of stating limits or output format, so a 4.

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 purpose and return shape, then filtering semantics, then exclusions/alternatives. Every sentence carries information, though it is dense and runs long; a small trim of the redundant 'una que falla se anota' clause would tighten it.

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 two-parameter, no-output-schema tool, the description covers purpose, return fields, date-filtering behavior, partial-failure semantics, and the two alternative tools. With annotations handling safety, an agent has everything needed to call it correctly.

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 100%, so the baseline is 3, but the description adds meaning beyond it: it explains that '2019-12-31' effectively means all of 2019, that undated notes are dropped, and that every cita must carry its own year and resolves separately. That materially clarifies both parameters.

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 result ('resume los cambios: modificación, derogación, adición') scoped to 'LAS NORMAS QUE SE LISTAN', and enumerates the returned fields per norm. It explicitly names the two sibling tools it is not (buscar_diario_oficial, historial_norma), so an agent can route without opening any 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 explicit when-not guidance ('NO rastrea novedades ni descubre normas nuevas') and names the exact alternative for each excluded case: buscar_diario_oficial for newly published material and historial_norma for the full history of a single norm including undated notes. Nothing is left to inference.

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

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

Annotations already declare a safe read-only, idempotent operation, but the description adds substantial behavior beyond them: the classification method (text patterns for plazo/sanción/excepción/etc.), the Dice-bigram threshold of ≥0.92, the 'revisar manualmente' fallback, the absence of a semantic model, and the non-obvious portal behavior behind con_reforma. This is exactly the kind of context annotations cannot carry.

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 comparison action, then the method, then the con_reforma caveat, then sibling routing; every sentence carries information. It is dense and slightly run-on, but no sentence is filler given the tool's complexity.

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 comparison tool with no output schema and full schema description coverage, the description supplies the missing return semantics (added/removed marking, difference categories, manual-review bucket) and both operating modes. Nothing essential for correct invocation is absent.

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 100%, so the baseline is 3. The description goes beyond it by clarifying the interaction semantics of con_reforma — that norma_b (and articulo_b) need not be supplied, and why the tool can infer the counterpart article from the portal's annotated reform. That adds real meaning over the schema's per-field text.

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 specific verbs and resource: comparing article text between two norms, marking additions/deletions, classifying differences by patterns, and detecting editorial changes by lexical similarity. It explicitly names what it is not for ('Sin modelo semántico') and names siblings (historial_norma, analizar_conflicto), so an agent can distinguish it without opening any 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 explicit conditional usage: use con_reforma=true when you don't have the second norm, and explains why (the portal consolidates and doesn't publish prior wording). It then routes to alternatives with conditions: historial_norma for all reforms of a norm, analizar_conflicto for whole-norm conflicts. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, but the description adds real context: no year/page/filter support, one line per result including sector and the profile's self-declared limits, and 'no guarda nada'. It stops short of describing pagination or result-size behavior beyond the limit param.

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?

Every sentence carries load: source routing, return shape, filter exclusion, and the negative routing rule. Front-loaded with the core action and no filler.

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?

No output schema exists, yet the description describes the return format (one line per result with sector and warning). Combined with the source map and exclusion rules, an agent has everything needed to call this correctly versus its siblings.

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 100% (baseline 3), and the description adds meaning beyond it: it explains what each enum value routes to and where perfil ids come from (describir_fuentes), plus explicitly rules out filter parameters the agent might expect. That mapping is genuine semantic value.

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 (ejecuta la consulta) and resource (perfil sectorial preconfigurado), and pins each perfil value to its authoritative source (laboral→Gestor Normativo, tributario→DIAN, etc.). An agent can distinguish this from the many buscar_* siblings without opening a 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?

Explicit when-not guidance: 'NO uses un perfil para lo que no cubre', with named fallbacks (buscar_normas, resolver_cita) and a named alternative for filtering (buscar_resoluciones_creg con anio). The constraint that the profile accepts no year/page/other filters is stated directly.

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

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

Annotations already cover read-only/idempotent/open-world safety, yet the description adds real behavioral context beyond them: nivel determines the backend source (relatoría de la Corte Constitucional vs. Gestor filtrado por tipo), texto matches resúmenes and NOT articulado, and the output shape is disclosed (documentos con título y enlace + carácter del nivel). It even carries a scope disclaimer ('No es asesoría jurídica: verifica en el enlace').

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 purpose, then source routing, then usage, then the disclaimer — a sensible order with no filler sentences. It is dense and a few clauses run long, but every sentence carries routing or scope information an agent needs.

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?

With no output schema, the description compensates by stating what is returned (documentos con título y enlace y el carácter del nivel). Source routing, search-field limitation, and sibling alternatives are all covered, so an agent has everything required to call this correctly and interpret the result.

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 100%, so the baseline is 3, but the description genuinely adds semantics the schema does not: the value 'jurisprudencia' redirects to a different source and each remaining value is searched in the Gestor filtered by tipo. It also clarifies that texto is matched against resúmenes rather than articulado, which changes how an agent should phrase queries. limite is left to the schema, hence not a 5.

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 ('Busca normativa colombiana de UN nivel de autoridad') plus an extra effect ('explica su carácter'), and explicitly separates itself from siblings by naming buscar_jurisprudencia_suprema, buscar_jurisprudencia_consejo_estado, buscar_normas, buscar_por_tema and resolver_cita. An agent can route correctly without opening any other 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 an explicit trigger ('ÚSALA cuando la pregunta pida un nivel concreto') with a concrete example, states the when-not condition (búsquedas sin nivel van a buscar_normas o buscar_por_tema), and points to resolver_cita for article text. Alternatives and selection criteria are fully enumerated.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the confidence-level output, that the tool never invents the status, that the status applies to the whole norm even when the citation names an article, and that responses open with a scope line naming which sources were consulted. It also explains fallback behavior when the source does not respond (low confidence). These are substantial behavioral details not present in the annotations.

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?

The description is front-loaded with the core purpose and then proceeds through confidence, exceptions, alternatives, and response format. Every sentence carries operational information, but the length is notable for a single-parameter tool; minor condensation (e.g., the confidence-level sentences) could tighten it without losing value.

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?

With no output schema, the description adequately explains what is returned: the SUIN status strings, a confidence level, and a leading scope line. It also covers edge cases (sentencias, missing year, article-specific citations) and the fallback when the source is unresponsive, so an agent has enough context to call and interpret the tool.

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 100% and the schema already documents the single 'cita' string with examples. The description adds interpretation rules beyond the schema: a citation without a year yields multiple candidates instead of a choice, the status is for the entire norm even if an article is cited, and sentencia citations are out of scope. This adds meaningful semantic guidance, though it does not cover citation syntax exhaustively.

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 first sentence states a specific verb and resource: it returns the validity status of a law or decree as published on the SUIN ficha, including the enumerated states. It also distinguishes the tool from siblings by noting that sentencias have no vigencia and must be checked in the Corte Constitucional relatoría, so an agent can tell it apart from resolver_cita or historial_norma.

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?

Explicitly names alternatives and when to use them: 'Para las reformas de un artículo usa historial_norma; para su texto, resolver_cita.' It also gives an exclusion for sentencias like 'C-337/11' and explains that ambiguous citations without a year are listed rather than selected. This is clear when/when-not guidance with named alternatives.

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

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

Adds context beyond the annotations: it does not query the network (corroborating openWorldHint=false) and discloses that the underlying indexes are bundled and carry a generation date that may go stale. It does not elaborate on output shape beyond relative length, but with readOnly/idempotent already declared the bar is lower.

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 what the tool declares, then the usage rule, then the parameter behavior. Every sentence earns its place, though the single dense paragraph packs several distinct points together.

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?

With no output schema, the description carries the return-value burden and does so adequately: it explains that output is per-source scope plus index dates, and that size depends on `fuente`. An agent has enough to call and interpret it correctly.

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 100% and the enum already documents each source key, but the description adds behavioral meaning: passing `fuente` narrows the response to one source (the common case) while omitting it returns the full, long table. That default-behavior framing goes beyond the 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 and resource: it declares the real scope, which source answers each question, what is NOT covered, and the generation date of the bundled indexes. This is clearly distinguishable from the sibling search tools (buscar_*, consultar_*) which retrieve content rather than describe coverage.

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?

Explicitly says to use it BEFORE concluding something 'doesn't exist' after an empty search, and to check whether the vigencia index is still fresh. It also states when to pass `fuente` (usually what's needed) versus omitting it (the long full table).

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

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

Goes well beyond the annotations: gating by env var, in-memory records expiring per EXPEDIENTES_TTL_MS, disk persistence via EXPEDIENTES_DIR surviving restarts, and non-destructive export semantics (existing file is never overwritten, a numeric-suffixed sibling is written and the final path returned). This is exactly the operational context annotations alone cannot convey.

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 purpose and the key 'no consulta fuentes' qualifier, and every clause carries information. Some sentences are long and dense (the exportar sentence chains four conditions), which costs a point but nothing is padding.

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?

No output schema exists, yet the description covers the activation gate, storage lifetime, persistence, per-action parameter coupling, and export edge cases including the returned final path, while pointing to obtener_documento for a neighboring use case. Nothing needed to invoke it correctly 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 coverage is 100% and the schema already documents each field, so the baseline is 3. The description adds genuine cross-parameter meaning on top: id is required specifically for agregar/leer/exportar, campo and texto must be supplied together, and ruta may be a file or a directory with different write behavior.

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?

Names a specific resource (un expediente para agrupar consultas, citas y observaciones) and enumerates the four operations (crear, agregar, leer, exportar). Crucially it distinguishes itself from the many buscar_* siblings with 'No consulta ninguna fuente: guarda lo que le pasas', so an agent can route without opening the 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 explicit entry conditions (se activa con EXPEDIENTES=1, desactivado por defecto), prescribes the flow ('El flujo empieza siempre en crear, SIN id'), states the per-action prerequisites ('agregar exige campo y texto juntos'), and names an alternative for a related job ('Para guardar el texto de una norma usa obtener_documento').

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real context: it describes what is returned (the restrictor excerpt) and discloses validation behavior (ids not sourced from buscar_por_tema are rejected).

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 return value, then constraints, then the alternative — a logical order. Dense but every sentence carries information; minor overlap between the prefix constraint and the schema description keeps it from a 5.

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?

No output schema exists, yet the description explains the return value (the restrictor extract) and the sourcing/validation constraints. Nothing an agent needs in order to invoke it correctly 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by tying both ids to the same source row and stressing the required 'ts-' prefix, plus the consequence of passing a catalog id. This reinforces and extends the schema rather than merely repeating it.

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: it returns the 'restrictor' excerpt explaining why a given norm applies to a specific subtopic. It distinguishes itself from siblings by name (buscar_por_tema, listar_catalogos, obtener_documento), so an agent can route without opening another 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?

Explicitly states the prerequisite (both ids must come from the SAME row of buscar_por_tema), the when-not (an id from listar_catalogos or other catalogs is rejected here), and a clear alternative for a different need (obtener_documento with fuente='gestor' to see all restrictors at once).

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

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

Annotations cover the safety profile (readOnly/idempotent/non-destructive), but the description adds the traits that actually matter here: ordering by introducing-norm year, undated notes placed last and unordered, the caveat that the ANNOTATED last reform may not be the one in force because the portal doesn't annotate everything, and how articulo/desde/limite interact with the ordering. This is genuine behavioral disclosure beyond structured data.

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?

One dense paragraph, but front-loaded with purpose, then behavior, then sibling routing, then output shape. Nearly every clause earns its place; it is information-heavy rather than padded, though the density borders on hard to scan.

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?

With no output schema, the description compensates by naming the JSON fields (titulo, url, total, cambios, ultima_reforma, avisos), and it covers pagination semantics, ordering guarantees, the annotation-completeness caveat, and alternatives. An agent has everything needed to call and interpret it.

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 100%, so each parameter is already documented (baseline 3). The description goes further by defining the operation order — articulo filters first, desde/limite trim the already-ordered list afterwards, and ultima_reforma is computed over the full filtered set rather than the shown slice — which the schema does not express.

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 ("Devuelve la cadena de reformas... sobre una norma") and enumerates what the chain contains (modificó, adicionó, derogó, sustituyó, artículo afectado, nota literal citable). It is unmistakably distinct from siblings like buscar_normas or consultar_vigencia.

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?

Explicitly routes to three alternatives with their selecting conditions: resolver_cita for vigencia, cambios_desde for multi-norm changes from a year, comparar_articulos for before/after text comparison. Nothing is left to inference.

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

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

Beyond the read-only/idempotent annotations, it discloses crucial behavioral caveats: these are registrations not a verified line ('mencionar no es reiterar y la relación puede estar incompleta'), the ordering rule (SU and C before limite is applied), and the portal cap of 100 with no pagination.

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 purpose, then caveats and routing in a dense but waste-free flow. It is somewhat long and packs ordering, cap, and disclaimers into running prose, but every clause carries information.

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?

With no output schema needed, the description still covers scope ('Solo cubre la Corte Constitucional'), reliability caveats, ordering semantics, the hard cap, and routing — everything required to invoke it correctly.

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 100%, so the baseline is 3, but the description adds real meaning the schema lacks: it explains how 'limite' interacts with ordering, noting a low limit drops T and autos first, and reinforces the 100 hard cap.

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 ('Devuelve las providencias que ... CITANTES de una sentencia de la Corte Constitucional') and pinpoints the exact source block ('citaciones' de su ficha oficial), listing the returned fields. It is immediately distinguishable from tema-search and cita-resolution siblings.

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?

'Úsala cuando ya tienes la sentencia y quieres saber quién la cita' gives the trigger condition, and it names two alternatives with their selection rules: buscar_jurisprudencia for topic search and resolver_cita to read/verify the cited sentence itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds substantial behavioral context beyond them: the temas filter is mandatory due to volume, the id prefix exists because three taxonomies reuse numbers, and the negative-evidence caveat about DIAN entities. It omits pagination behavior (desde/limite), keeping it just short of a 5.

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 before the scope warnings, and each sentence carries information (what the catalogs hold, the mandatory-filter rule, the prefix rationale, the scope limits). It is dense and long, but virtually nothing is filler, so it stays on the useful side of verbose.

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?

With no output schema and 7 parameters over a 7-value enum, the description supplies the catalog semantics, param-to-catalog mappings, and cross-source scope that an agent needs. The only gap is that it does not describe the desde/limite pagination of the listing itself.

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 only 57%, and the description compensates: it ties tema_id to subtemas (with prefix), numero/anio to conceptos_fp, and notes filtro is mandatory for temas. It clarifies the relationship between the catalogo enum and which params apply, adding meaning the schema's terse descriptions do not fully provide.

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 concrete verb+resource (listar_catalogos returns the valid filter values for buscar_normas) and enumerates what the catalogs contain (tipos, años, entidades, temas, subtemas, conceptos_fp, normas_fp). It explicitly distinguishes itself from buscar_normativa_tributaria and names the sources it does not cover, so an agent can tell it apart from siblings without opening a 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 explicit when/when-not: the catalogs are ONLY for the Gestor Normativo de Función Pública and only work in buscar_normas, with named alternatives (buscar_normativa_tributaria for DIAN, and the exclusion of SUIN-Juriscol and the high courts). The 'OJO CON EL ALCANCE' note prevents misuse of the entity list.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds substantial context beyond them: it warns that almost everything listed is better resolved elsewhere, describes the return payload (título, resumen, enlace), notes it flags when a title's número doesn't match the resumen, and explains that texto filters only the fetched page so an empty result isn't definitive. Pagination size varies by section and must be read from the response, which is valuable operational detail.

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?

Long but dense and front-loaded: purpose, then the value/limitation, then return shape, then parameter behavior, then usage routing. Nearly every sentence carries a distinct fact, with only mild repetition between the 'classification not new documents' framing and the resolver_cita comparison.

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?

No output schema exists, yet the description explains what comes back (título, resumen, enlace, mismatch warnings) and how pagination behaves per section. Combined with the explicit alternative-tool routing, an agent has everything needed to call this correctly and interpret the result.

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 67% and the seccion enum has no inline description, so the description does real work: it names seccion as the theme selector with default 'leyes', and clarifies that texto filters only the page brought back rather than the whole section. It adds behavior the schema does not encode, though it doesn't enumerate or add syntax for cada sección value.

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: a curated classification of national environmental normativity maintained by ANLA in Eureka, grouped by theme. It explicitly frames what it contributes (the CLASSIFICATION, not new documents) and contrasts that against resolver_cita, which resolves the same laws and decrees with full text and vigencia.

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 and when-not: 'Úsala para descubrir QUÉ normas aplican a un tema ambiental y resuelve cada una con resolver_cita', plus the alternative consultar_perfil with perfil="ambiental" for filtering all sections at once. Alternatives and selection conditions are both named.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false / idempotentHint=false; the description supplies the substance: disk writes happen only with entero or ruta_destino (which override other params), dian/sectorial keep the original file while others write texto-<fuente>.txt to a temp folder, consejo cannot write, and repeated names never overwrite (suffix appended), which aligns with and enriches the idempotent/destructive hints.

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?

Nearly every clause carries information and the core purpose is front-loaded, but the middle section is a dense run-on spanning source matrices, output-part rules, and write behavior without clear breaks. Scannability suffers slightly though nothing is wasted.

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 an 18-parameter, 7-source tool with no output schema, the description is remarkably complete: it covers input requirements, rejection behavior, output shape (total/mostrado/omitido plus next 'desde'), and side effects. An agent has enough to call it correctly for any source.

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 94%, so the per-parameter descriptions already carry most weight, but the description adds cross-parameter semantics the schema cannot express: the source→required-parameter matrix, the precedence of entero/ruta_destino over everything else, and interaction rules (historial replaces text; articulo/seccion suppress buscar_en_texto; desde only advances chunking). This is real value beyond the 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 and resource ('Devuelve el texto ... de una de las siete fuentes') plus the hard scope constraint that it is always chunked, never whole. It distinguishes itself from the sibling search tools by pointing to resolver_cita and the per-source search engines for discovery.

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?

Explicitly maps each of the seven sources to its required parameters (gestor→id; corte/suprema/creg→ruta; consejo→token; dian→link; sectorial→entidad+url), states that mismatched combinations are rejected before any network call, and routes discovery to resolver_cita first. This is prescriptive when/when-not guidance.

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

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

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses mode precedence (citas sobre cita; con citas se ignora articulos), the conditional applicability of url/formato only under validar, and that validar switches the whole response to a verdict without vigencia. It also states what is returned (identificación, enlace, vigencia, texto) and which norm was resolved against.

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, followed by usage and sibling routing, then behavior and modes — a sound ordering. It is dense with little padding, though the one-line "Solo consulta, no guarda nada" mildly duplicates the readOnlyHint annotation and the final sentence bundles two different sibling alternatives.

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?

Despite no output schema, the description explains the normal return payload (identificación oficial con enlace, vigencia, texto pedido, norma contra la que resolvió) and the alternate validar return (veredicto). Together with the mode rules and alternatives, an agent has everything needed to call it correctly across all seven optional parameters.

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 100%, so each parameter is already documented; the description nevertheless adds genuinely non-schema information about how parameters interact (citas overrides cita, articulos requires cita pointing to a single norm and is ignored when citas is present, url/formato only valid with validar=true). Some clauses restate what the schema already says (contexto, formato), keeping it just below a 5.

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 (resolver citas de leyes, decretos, sentencias, artículos y códigos citados por su nombre) with a concrete example, and explicitly contrasts itself with buscar_normas and buscar_por_tema. An agent can identify this tool's niche without opening any 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?

"Úsala SIEMPRE que la pregunta mencione una norma concreta: buscar_normas y buscar_por_tema son para cuando no la hay" gives an explicit when-to-use plus the named alternatives and the condition that selects them. It also routes adjacent needs (historial_norma for reformas, linea_jurisprudencial for citas de sentencias).

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