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

No annotations exist, so the description carries the full burden, and it does well: it discloses that the output is evidence-gathering only, that no semantic contradiction detection happens, that results are potential not conclusive, and it describes the JSON return shape (fecha_consulta, alcance, sobre, evidencias, avisos). It omits any mention of permissions, limits, or cost.

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 and evidence list, then limitations, then output format — a logical order. It is dense and contains a typo ('mencionanun'), and the single long semicolon-chained sentence is harder to scan than it needs to be.

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, so the description must cover return values, and it does for the JSON mode (listing the object's fields). The default markdown output is only labeled 'texto legible', leaving its structure underspecified, but overall an agent has enough 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%, so the baseline is 3. The description adds genuine value beyond the schema by explaining that 'sobre' drives a passage search across both norms and by detailing what formato="json" returns, which the schema only hints at.

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: 'Reúne para dos normas la EVIDENCIA de un posible conflicto', then enumerates exactly which evidence types are gathered (identificación en el Gestor, vigencia SUIN, jerarquía, notas de reforma, pasajes temáticos). This is clearly distinguishable from siblings like comparar_articulos 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 states a when-not: 'NO detecta contradicciones semánticas' and warns 'el resultado es un conflicto POTENCIAL, no una conclusión jurídica; verifica en los enlaces antes de actuar'. It gives clear context for use, though it never names a specific sibling tool to use instead when a semantic comparison is actually wanted.

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?

With no annotations, the description carries the full burden and does well: it discloses the fields returned, the freshness property (same-day), and candid limitations (no norm content, no text, no stable PDF link). It omits auth/permission or rate-limit behavior, but the disclosure of what is and isn't available is substantial.

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?

Three dense sentences that are front-loaded with the returned fields, then usage, then limitations. Nearly every clause earns its place, though the filter list and caveats are packed tightly enough to slightly reduce scanability.

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 and no annotations exist, so the description must explain results and constraints itself, which it does: it names the returned fields, the filter combinations, and the three things the tool cannot provide. An agent has enough to call it 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?

At 100% schema coverage the baseline is 3, and the description goes beyond it by explaining the cross-parameter dependency and giving a worked example ('tipo="LEY" y numero_norma="2466" devuelve el 53.160'). This clarifies the joint use of tipo and numero_norma that the schema only states as 'exige tipo'.

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 (buscar) and resource (Diario Oficial), and enumerates exactly what it returns: número, tipo de edición and fecha de publicación. It also situates the tool against the Gestor Normativo, so an agent can distinguish it from the cataloguing/search tools in the sibling set.

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 a clear when-to-use condition ('para saber qué salió publicado y cuándo, incluso el mismo día, antes de que el Gestor Normativo lo catalogue') plus two explicit exclusions ('NO dice qué normas contiene ... ni trae su texto'). It stops short of naming a specific sibling tool to use instead for norm content, which is the only gap.

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?

No annotations are provided, so the description carries the full burden, and it does so richly: it warns the vigencia field returned is the searcher's own and unreliable, that the index has gaps ('Teletrabajo' returns zero), and that long phrases match by common words. These are exactly the behavioral caveats 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?

Dense but front-loaded: capability, then scope limits, then the unreliable-field warning, then the index-gap caveat and fallback. Every sentence earns its place with no redundancy.

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 no annotations, the description supplies the behavioral, safety-relevant and fallback context an agent needs. 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 description coverage is 80%, so the schema already documents texto, desde, sector and vigencia. The description clarifies that the vigencia filter reflects the searcher's state, which doesn't always match the document sheet, adding modest value; limite remains undocumented in both.

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') and enumerates searchable fields (título, epígrafe, materia, entidad emisora) and coverage (1844 onward, includes docs the Gestor Normativo lacks). It clearly distinguishes itself from resolver_cita and buscar_por_tema.

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 when NOT to use it ('NO busca dentro del articulado ni sirve para citas exactas') and routes to resolver_cita for citations, plus buscar_por_tema after an empty result. Usage conditions and alternatives are fully spelled out.

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?

With no annotations, the description carries the full burden and does well: it discloses corpus size (44.839 providencias), recency, the return fields (sentencia, tipo, fecha, síntesis), the handoff to obtener_documento with fuente='corte', and a non-obvious behavioral trait — the relatoría does not index long phrases, so it retries with the most distinctive word and announces this in the response. It omits pagination/rate behavior, but otherwise this is rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource and its distinguishing claim, then the return shape, then the query caveat, then the sibling routing. Every sentence earns its place 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?

For a search tool with no output schema and no annotations, the description supplies the return fields, corpus scope, query behavior caveat, and cross-tool handoff, which is everything an agent needs to invoke 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%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the long-phrase indexing limitation and the automatic retry with the distinctive core, which directly affects how 'termino' should be supplied. The 'fuente=corte' link also clarifies downstream usage.

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: search Constitutional Court sentencias and autos from the relatoría, with coverage count and recency. It explicitly distinguishes itself from buscar_jurisprudencia_suprema and buscar_jurisprudencia_consejo_estado, so an agent can route without opening sibling 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 when-to-use: this is the route for constitutional jurisprudence because the Gestor covers little of it, and it names the sibling tools to use for Suprema and Consejo de Estado instead. It also gives a concrete usage rule — request autos (A) explicitly since they are mostly procedural and excluded by default.

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?

With no annotations, the description carries the full burden and does well: it explains the exact-match-then-OR-fallback behavior with a notice, and warns that in OR mode the page count measures corpus size, not relevance. It also mentions each result includes the legal problem, its answer, and the SAMAI link. Missing: rate limits, auth, or what a failure/empty result looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool returns and its tribunal scope, then the search mechanics, then pagination. Dense but each sentence carries routing or behavioral information. Parenthetical enum-like listings add bulk but serve disambiguation.

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 search tool with no output schema and no annotations, the description covers scope, result shape (problema jurídico, respuesta, SAMAI link), and search-mode behavior. Remaining gaps are edge-case handling (empty results, timeouts) but nothing an agent strictly needs to invoke 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 value by explaining why 'pagina' exists (SAMAI paginates in ~10 blocks without free offset) and reinforcing the exacto OR fallback. The 'limite' nuance of per-page display is partly covered by 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+resource (buscar providencias del Consejo de Estado) and explicitly distinguishes the tribunal from the Corte Constitucional and the Suprema, which is essential given sibling tools like buscar_jurisprudencia_suprema. It also enumerates the subject matters (nulidad y restablecimiento, contratación estatal, nulidad electoral, reparación directa, conceptos de la Sala de Consulta).

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 'tribunal DISTINTO de la Corte Constitucional y de la Suprema' clause gives clear when-to-use guidance by differentiating from sibling jurisprudence tools. It also explains how to advance results with 'pagina'. It does not name specific sibling tools or give explicit when-not-to-use conditions, but the tribunal distinction is a strong routing cue.

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?

With no annotations, the description carries the full burden and does well: it discloses the search engine semantics (full-text, no stopword filtering, exact-phrase default), the consequence of exacto=false (result explosion, unusable in Penal), and the shape of each result (cited norms, a ruta). It omits any auth/permission or rate-limit notes, which is a minor gap for a public legal dataset.

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 resource and scope, then differentiation, then output, then search behavior. Every clause carries signal, though the paragraph is dense and long enough that the search-semantics detail 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?

No output schema exists, so the description appropriately explains what each result contains (normas and a ruta for retrieval) and the search behavior of a 7-parameter tool. Combined with the 100%-covered schema, an agent has what it needs; only auth/limit context 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 description coverage is 100%, so the baseline is 3. The description restates the exacto behavior and notes sala's obligatoriness, but these are already documented in the schema fields, so it adds little parameter meaning beyond what the structured data provides.

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?

Starts with a specific verb+resource and coverage: 'Providencias de la Corte Suprema por sala: Tutelas, Civil, Laboral o Penal, desde 1991.' It explicitly disambiguates from the same-named sibling by naming the different tribunal (Corte Constitucional vs Corte Suprema), so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing context by naming buscar_jurisprudencia and explaining that these are distinct courts, plus follow-up chaining (resolver_cita for cited norms, obtener_documento with fuente="suprema" for full text). It lacks guidance against the other search siblings (e.g., buscar_por_tema), so it is clear but not exhaustive.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses critical search behavior: the portal indexes only thematic summaries, not full articulado, and joins terms with OR. It does not cover auth, rate limits, or return format, but the key limitations are stated.

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 purpose and the critical indexing caveat before alternatives. Four sentences, no waste, and the most important limitation is marked clearly with IMPORTANTE.

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 annotations, the description covers scope, indexing limitation, query behavior, and two alternatives. It could mention return format or pagination, but the core invocation guidance is complete enough.

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 88%, so the baseline would be 3. The description adds meaningful semantics for the main query parameter by explaining OR-joining and advising few distinctive terms, which goes beyond the schema descriptions. It does not explain every filter, but it exceeds the baseline.

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 leyes, decretos, resoluciones, conceptos y sentencias del sector público colombiano. It distinguishes this tool from two siblings by directing full-text search to obtener_documento and exact citations to resolver_cita.

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 tells the agent when to use this tool versus alternatives: use obtener_documento for text inside a specific norm, and resolver_cita for an exact citation. It also gives concrete query advice for the free-text search: use few, highly distinctive words.

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?

With no annotations, the description carries the full burden and does so: it discloses that no full text is returned (only epígrafe, PDF link, and ficha) and, critically, that administrative/personnel acts are hidden by default and constitute two of every three documents. The latter is a non-obvious default that materially changes result counts.

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: scope first, then the routing rule, then the default-hiding caveat with the flag that overrides it. Every sentence carries routing or behavioral information; none is 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 stating exactly what is returned (epígrafe, PDF, ficha). Combined with the coverage of the hidden-default behavior, 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 description coverage is already 86%, so the baseline is 3; the description adds real value by explaining why incluir_administrativos defaults to false and how large its effect is. It does not add syntax or format detail for the remaining filters (tipo, desde/hasta, texto, numero, pagina), which the schema already documents.

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 and resource (regulations of the Agencia Nacional de Hidrocarburos, 785 documents) and enumerates the subject matter: exploration/production contracts, royalties, fiscalización, reserves. It also distinguishes itself from resolver_cita for national laws/decrees, so the 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?

Explicit when-to-use (hidrocarburos y regalías), explicit when-not (leyes o decretos nacionales de cualquier sector → resolver_cita), and a conditional on the incluir_administrativos flag. 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?

With no annotations, the description carries the full burden and does so well: it warns that most results are non-extractable PDFs, that validity status is unreliable and only a portal row where present, and that filter behavior differs per source. These are exactly the operational caveats an agent needs and cannot obtain from the schema.

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 a capitalized 'CUÁNDO NO USARLA' block, followed by caveats; every sentence carries usable information. It is dense and long, but no sentence is filler, so it stays within appropriate bounds for a multi-source tool.

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, multi-source tool with no output schema, the description covers the main retrieval and validity pitfalls. It omits operational details like auth needs or pagination behavior beyond limite/pagina, but the described response behavior ('Cada respuesta dice qué hizo') fills the most important gap.

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 71% and the description adds real meaning: it instructs choosing the regulator via `entidad` and details per-source filter behavior (Invima requires texto or año, Superfinanciera/Supertransporte default to the current year, ANM ignores año for circulares). This directly enriches `anio`/`texto`/`entidad` beyond the schema, though it stops short of covering every parameter.

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 (buscar) and resource (actos administrativos de reguladores sectoriales que el Gestor NO cataloga), and immediately distinguishes it from siblings resolver_cita and buscar_por_tema. An agent can tell exactly which corpus this tool covers versus the national law/decreto corpus.

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' section naming the alternatives (resolver_cita, buscar_por_tema) and the condition that routes to them, plus notes that the Decreto Único Reglamentario is already in the Gestor. When-not and alternatives are both specified.

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?

With no annotations, the description carries the full burden and does well: it discloses the ~20 s first-search latency, the fact that the portal returns the complete result set with no cap, and that subsequent pages of the same term are instant. It does not state auth/permission requirements, which would be the remaining gap for a mutation-free read tool.

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 scope, then the return format, then the routing tip, then the latency caveat. Every sentence delivers an actionable fact with no filler, despite the description being relatively dense.

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 and no annotations, yet the description covers return shape (extracto + enlace), follow-up tool, latency, pagination, and rate-limiting behavior. Nothing an agent needs in order 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%, so the schema documents texto and desde, but the description adds real meaning: it explains that 'desde' is the pagination lever to reuse an existing result set rather than issuing a new search. This is operational semantics the schema's terse 'Cuántos saltarse antes de empezar' does not convey. 'limite' gains no extra explanation.

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 (el normograma de la DIAN: decretos, resoluciones, conceptos y circulares en materia tributaria, aduanera y cambiaria) with a clear verb of search, and explicitly distinguishes itself from siblings ('que ninguna otra herramienta cubre'). An agent can tell this apart from buscar_normas or buscar_normativa_anh 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?

Routes the agent to the correct follow-up: 'para leer el documento usa obtener_documento con fuente="dian"'. It also gives pagination guidance ('pagina con desde en vez de lanzar búsquedas nuevas'). What's missing is explicit when-not guidance against the close sibling buscar_normas, but the usage context is otherwise clear.

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?

With no annotations, the description carries the full burden and excels: it warns that the tool returns PDFs, not full text, and highlights the critical date discrepancy between web publication and the actual norm date. These are non-obvious, high-impact behavioral traits that an agent must know.

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?

Three sentences, each purposeful: first defines scope, second warns about PDF-only output, third warns about date semantics. There is zero fluff, and the most critical caveats are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter search tool without an output schema, the description covers what is searched, the PDF-only limitation, and the crucial date quirk. It omits details about result format or pagination, but the essential operational context is present and sufficient for correct invocation.

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 covers only 50% of parameters (texto and incluir_administrativos have descriptions). The description adds semantic context by giving example search topics (transmission, expansion plans) and mentioning administrative acts, but it does not clarify the behavior of limite or pagina. This partial compensation warrants a middle score.

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 description clearly specifies the tool's resource (UPME circulars and resolutions) and enumerates content types (transmission/gas calls, expansion plans, administrative acts). The explicit UPME name distinguishes it from sibling sector-specific tools like buscar_resoluciones_creg and buscar_normativa_anh, and the verb is implied by the tool name and title.

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 gives a clear context of when to use the tool by listing its coverage areas and the issuing entity. It does not explicitly name alternatives or state when not to use it, but the specificity strongly implies the intended use case.

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?

No annotations exist, so the description carries the full burden, and it does substantial work: it discloses the data source ('índice empaquetado'), availability behavior ('instantáneo, funciona aunque el portal esté caído'), and the shape of each result (tema, subtema, normas, sentencias, conceptos, plus temsubid and normid). The main gap is that it never addresses the 'limite' cap or pagination behavior.

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 in the first clause, then result shape, then the id-handling warning. Three dense sentences with no filler. The id-taxonomy warning is longer than average but earns its place by preventing real id-format errors.

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 no annotations, the description must carry return and safety information, and it does describe the returned fields and offline behavior. Remaining shortfalls — the 'limite' semantics and explicit sibling selection among the many search tools — are minor for a simple two-parameter lookup.

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 exactly 50%: 'texto' is documented with examples while 'limite' has only structural constraints and no description. The description adds no meaning about either parameter (its 'ts-' discussion is about returned ids, not inputs), so it neither compensates for the coverage gap nor exceeds the schema. Baseline 3 applies.

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 ('tema, subtema y las normas, sentencias y conceptos asociados') and frames itself as the 'Consulta temática oficial', so the verb+resource is unambiguous. It actively distinguishes itself from siblings by naming explicar_relacion_tema (follow-up) and listar_catalogos (a different taxonomy), so an agent can place it without opening other 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 clear context: it is the thematic index lookup, works offline, and routes the agent to explicar_relacion_tema afterwards using temsubid/normid. It also warns against conflating its 'ts-' ids with the 'sub-'/'tema-' ids from listar_catalogos. It stops short of stating explicit when-not-to-use conditions against the other search siblings (buscar_normas, buscar_unificado, etc.).

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?

With no annotations, the description carries the full burden and does well: it discloses that this is the only sectoral source whose text is readable here, that it is the only one publishing a vigencia signal, that the signal comes in separate compilations (vigentes vs derogadas), and warns not to reduce that signal to a boolean. Missing auth/rate-limit or return-shape notes, but the behavioral quirks disclosed are substantive.

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 resource scope, then the differentiating traits, then the routing instruction. Dense with useful caveats and no filler, though the parenthetical about how to interpret the vigencia signal is a touch long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param search tool with no output schema and no annotations, it covers scope, sibling routing, and the key vigencia caveat. An agent has enough to call it correctly; only return format details are absent, which is a minor gap.

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 all four parameters are already documented, including the compilacion enum and the anio default behavior. The description adds the meaning of the vigencia signal in the results, but does not extend parameter syntax beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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 (buscar) and resource (resoluciones de la CREG) with the topical scope spelled out (tarifas, conexión, comercialización, plantas solares, gas natural). It also distinguishes itself from siblings by naming resolver_cita and referencing obtener_documento, so an agent can tell it apart 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: 'Para leyes o decretos nacionales de otros sectores usa resolver_cita,' and points to obtener_documento(fuente="creg") as the way to read full text. This is clear when-to-use and when-to-use-something-else 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?

With no annotations, the description carries real weight: it discloses parallel execution, per-source attribution ('cada resultado declara su fuente'), the important caveat that SUIN vigencia is labeled 'SEGÚN EL BUSCADOR' and is not the official ficha, the profile-dependent source expansion, and the 'Para leer' handoff to obtener_documento. It does not address rate limits or explicitly state read-only nature, but for a search tool the behavioral picture 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?

Purpose and the source list are front-loaded, followed by routing guidance and output behavior. It is a dense single paragraph, but every clause (profiles, vigencia caveat, json shape) earns its place with little 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?

For a 5-parameter tool with no output schema and no annotations, the description compensates well: it explains the json return object fields (fecha_consulta, alcance, texto, resultados, sin_resultados, fallidas, avisos) and the markdown-vs-json difference, so an agent knows what to expect from either format.

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 100%, so the baseline is 3, and most param detail in the description (perfil union of sectors, fuentes default excluding DIAN, formato json field list) is duplicated from the schema field descriptions. The description adds only marginal meaning beyond what the schema already documents.

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) and resource (múltiples fuentes jurídicas nombradas: Gestor Normativo, Corte Constitucional, SUIN-Juriscol, DIAN), and explicitly distinguishes itself from siblings by naming resolver_cita for exact citations and 'su buscador propio' for a specific tribunal. An agent can pick this apart from the individual source tools 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 an explicit when-to-use ('cuando la consulta es abierta o por materia y no hay herramienta obvia') plus when-not/alternatives ('para una cita exacta sigue siendo mejor resolver_cita', 'para un tribunal concreto, su buscador propio'). Routing is unambiguous for the sibling list provided.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals two critical traits: the date input is filtered by the YEAR of the modifying norm (not exact date), and the tool does not discover or track new norms automatically. This goes beyond the schema and helps avoid misuse, though it doesn't describe the return format.

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 two sentences with no redundant wording. The first sentence front-loads the core purpose, and the second adds a crucial limitation. Every word earns its place, making it highly concise and well-structured.

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?

The description covers purpose, parameters, and key behavioral limitations. Since there is no output schema, the description could benefit from a brief note about the return format, but for a tool with only two simple parameters and clear schema descriptions, it is largely complete. The explicit inclusion of change types (modification, repeal, addition) adds useful context.

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 100%, with both parameters fully documented in the input schema (e.g., 'desde' states 'se filtra por el AÑO de la norma modificadora'). The description adds no additional param semantics beyond reinforcing that only listed norms are considered, 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?

The description clearly states the tool's function: 'Resume los cambios' (summarizes changes: modification, repeal, addition) on explicitly listed norms. It also distinguishes its scope by stating it does NOT automatically track novelties or discover new norms, differentiating it from sibling tools that search or retrieve norms.

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 implies when to use the tool: when you have a specific list of norms and want changes since a date. The negative statement 'NO rastrea novedades automáticamente ni descubre normas nuevas' provides a clear exclusion, though it does not name alternative tools. This gives better guidance than no context, but lacks explicit references to siblings.

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?

With no annotations, the description carries the full burden and does so well: it discloses the classification taxonomy, the Dice bigram similarity threshold (≥0.92), the 'revisar manualmente' fallback for unmatched text, the absence of a semantic model, and a key limitation — that the portal consolidates text and does not publish the prior wording, so the comparison is against the last reform rather than a full history.

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 and efficient overall, but the single dense paragraph with multiple parenthetical asides is slightly run-on and could be split for easier scanning.

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 content (marked diffs, classification, manual-review flag) and the con_reforma caveat. It stops short of specifying the response structure, which leaves a small gap for a tool with no output schema.

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 beyond the schema by clarifying that norma_b/articulo_b are unused under con_reforma=true and what that flag actually triggers (locating the last annotated reform and extracting the modifying article).

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 (compare one article's text across two norms) and further specifies the output behavior: marking additions/deletions, classifying differences, and flagging unmatched cases. This is clearly distinct from sibling tools like buscar_normas or historial_norma, which retrieve rather than diff.

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 explains the two operating modes and when each applies: default two-norm comparison, or con_reforma=true when only one norm is available. It does not name sibling alternatives or state when NOT to use this tool, so it falls short of a full 5.

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?

No annotations are provided, so the description carries full disclosure burden. It adds useful behavior (results include the sector and an 'advertencia' that declares the profile's limits) and a scoping constraint, but says nothing about permissions, pagination, or mutation/read semantics.

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?

Two tight sentences with the core action front-loaded and the usage guardrail immediately after; every clause earns its place 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 and no annotations, the description covers purpose, the routing rule, and partially what the call returns (sector + advertencia). It is nearly complete for a 3-parameter read tool, though richer return/error behavior would push it higher.

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 100%, so texto, limite and perfil are already documented, including the enum and the 1-20 range. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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') plus the resource (fuentes y filtros preconfigurados de un perfil sectorial) and even enumerates the five sector values. An agent can distinguish it from the many buscar_* 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?

Explicitly gives the when-not condition ('NO uses un perfil para lo que no cubre: si la materia es otra') and names the concrete alternatives, buscar_normas and resolver_cita. This is a textbook routing instruction.

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?

No annotations are provided, so the description carries the full transparency burden. It discloses the output composition (documents with title and link, plus the character of the level), explains that levels are classified as vinculante/orientador/informativo, and adds a caveat that it is not legal advice and to verify on the link. It omits edge behaviors like pagination or no-result handling, but it gives substantial behavioral context beyond the schema.

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 concise and well structured: three sentences lead with the core action, then describe the output, then give usage direction and a caveat. Every sentence adds value with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description properly explains what is returned (documents with title, link, and level character) and covers legal caveats. It also provides usage alternatives. Minor gaps remain about result ordering and no-result behavior, but the description is largely complete for a search tool of this complexity.

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?

The schema already covers 100% of the parameters, so the baseline is 3. The description restates the 'nivel' options and explains the character of each level, but it does not add new meaning to 'texto' or 'limite' beyond what their schema descriptions already 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?

The description opens with a specific verb and resource: 'Busca normativa colombiana por nivel de autoridad', lists the exact levels allowed, and states the returned data (documents with title, link, and level character). It also explicitly contrasts with sibling tools by saying 'para buscar sin nivel usa buscar_normas o buscar_por_tema', so it clearly distinguishes itself from 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?

The description contains explicit when-to-use guidance: 'ÚSALA cuando la pregunta pida un nivel concreto' and gives the alternative: 'para buscar sin nivel usa buscar_normas o buscar_por_tema'. This is direct, actionable, and names specific sibling tools as 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?

With no annotations, the description carries the full burden and does so well: it discloses two confidence tiers (alta/baja), a no-fabrication guarantee ('Nunca inventa el estado'), the response leading with a scope line, and source-failure behavior. It stops short of describing latency or rate characteristics.

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, but the single dense paragraph stacks parentheticals and multiple asides (status list, confidence, sentence exception, no-fabrication rule, scope line) that make it harder to scan than it needs to be.

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 one-param read tool with no output schema, the description adequately explains what comes back: status values, confidence level, and the leading scope line stating which source was and wasn't consulted. Little 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?

One required param with 100% schema description coverage, so the schema already documents the cita format with examples. The description's mention of 'C-337/11' adds marginal domain context but no syntax or format detail beyond the schema; baseline 3 applies.

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 el estado de vigencia de una norma' with the exact enum-like values (Vigente, Derogado, etc.). It clarifies the domain edge (laws/decrees in SUIN, not sentences), though it never names a sibling tool by name for differentiation.

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?

Provides a clear when-not case: a sentencia like 'C-337/11' is not looked up in SUIN but verified in the Corte Constitucional relatoría. However, it gives no guidance on choosing between this and sibling tools like historial_norma or buscar_en_suin for the norm case.

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?

No annotations, so the description carries the burden. It states 'No consulta la red' (a real behavioral trait an agent needs), discloses that the full output is long, and that results are pre-packaged indexes with a generation date. It does not describe the response shape or performance, but the safety/behavioral profile is well covered.

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, then usage guidance, then a note about behavior. Four tight sentences, each earning its place. The final clause about the full table being 'largo' is slightly redundant but useful for output-size expectations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, no-output-schema, metadata-listing tool with no annotations, the description covers purpose, when to use, network behavior, and the parameter's effect. The only gap is that it does not hint at the return structure (e.g., that it lists per-source coverage and index dates), which is minor given no output schema requirement.

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 genuinely useful semantics: passing `fuente` returns ONLY that source's scope, which the description notes is what is typically needed, versus the long full table without it. That is practical guidance beyond the enum/description in 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 object ('Declara el alcance real: qué fuente responde cada pregunta') and clearly distinguishes itself from the many buscar_* siblings by declaring it is about coverage scope, not retrieval. An agent can tell what this tool does versus buscar_por_tema or buscar_unificado 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?

Explicitly says when to use it: 'Úsala ANTES de concluir que algo "no existe" a partir de una búsqueda vacía' and to check index freshness. It also gives the selection rule for the parameter. This is exactly the when/when-not guidance the dimension rewards.

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?

With no annotations, the description carries the full burden and does so well: it discloses the env-var gating, the temporary in-memory mode with TTL expiry, the persistence mode via EXPEDIENTES_DIR that survives restarts, and per-action side effects (crear returns id, exportar writes markdown). It still omits error behavior (e.g. agregar to a missing id) and any permission details beyond the activation flag.

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?

It is front-loaded with the purpose, then configuration, then the action semantics, so the reader gets the gist immediately. The prose is dense but every clause adds operational information; only the env-var detail is slightly buried mid-sentence.

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 stateful, multi-action tool with no output schema, the description covers persistence, lifespan and the return of each action, which is what the agent most needs. Remaining gaps are minor: exact shape of 'leer' output and failure modes are unspecified.

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 100%, so the schema already documents id, ruta, campo, texto and accion, including their per-action applicability. The description largely restates these constraints (id required for agregar/leer/exportar, ruta only for exportar) and adds little beyond the schema, so the baseline 3 applies.

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 description names the concrete resource (un expediente) and enumerates the four specific verbs it supports (crear, agregar, leer, exportar), each with its effect explained. It is unmistakably distinct from the sibling set, which are all stateless search/lookup tools.

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?

It gives real usage context: the tool is disabled by default (EXPEDIENTES=1) and 'agregar' only works against an 'expediente YA CREADO'. However, it never frames when an agent should reach for this tool rather than, say, just answering, nor does it name any exclusion.

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?

With no annotations, the description carries the behavioral burden and does disclose meaningful validation behavior: it rejects temsubid values sourced from listar_catalogos or other catalogs. It also reveals the coupling requirement between the two ids. It stops short of describing output format or failure modes in depth, but covers the key behavioral constraint well.

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?

Three sentences, front-loaded with the return value before constraints and the alternative. Dense and largely waste-free, though the parenthetical prefix example and the alternative tool reference add some length.

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 tool with no output schema or annotations, the description supplies the essential context: what it returns, where the ids come from, what gets rejected, and an alternative for bulk retrieval. It is close to complete, with only return structure left implicit.

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 specifies the temsubid prefix format ("ts-38872") and, crucially, the cross-parameter constraint that both ids must originate from the same buscar_por_tema row, which the schema does not convey.

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", defined inline as the extract explaining why a norm is pertinent to a specific subtopic. This is clearly distinguishable from siblings like buscar_por_tema and obtener_documento, which it explicitly references.

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-to-use: both identifiers must come from the SAME row of buscar_por_tema. It names the alternative (obtener_documento with fuente="gestor") and its purpose, and states an explicit exclusion (ids from listar_catalogos are rejected here).

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?

With no annotations, the description carries the full burden and does so well: it discloses ordering behavior (by year, undated notes last and unordered), the crucial caveat that the last ANNOTATED reform is not necessarily the one in force, and that the portal may not annotate all reforms. It omits any auth/rate-limit or failure-mode context, but for a read operation this is rich disclosure.

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, then layered with ordering rules, the caveat, and the alternative. Dense but every sentence carries functional information; only the JSON field enumeration is slightly 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?

No output schema, but the description compensates by describing the JSON object structure and the ordering/warning semantics. Combined with 100% parameter coverage, an agent has nearly everything needed to invoke 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 description coverage is 100%, so the schema already documents cita, desde, limite, formato and articulo, making 3 the baseline. The description adds the JSON return shape for formato="json", but adds no extra syntax or semantics for the other 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 resource: returns the chain of reforms the Gestor annotates on a norm, with per-article detail and literal citable notes. It is clearly distinguishable from siblings, notably resolver_cita, which it names for the vigencia query.

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 vigencia use case to resolver_cita and frames this tool as the reform-history source, which is strong context. It does not spell out a full when-not-to-use boundary, so it falls just short of the top score.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the returned fields (tipo, fecha, tema, ruta para obtener_documento, enlace), the ordering (SU and C first), and a strong reliability caveat that mentionar no es reiterar and the relation may be incomplete. It does not cover permissions, rate limits, or pagination behavior.

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 key output is front-loaded in the first clause, and the caveat sentences about citations vs. verified lines are substantive rather than filler. Sentences are long and dense, but every element earns its place.

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, so the description must describe return contents, and it does so thoroughly (fields, ordering, route/link to the document). For a read-only two-parameter tool with no annotations, the main remaining gap is that the limite/pagination behavior and the read-only nature are only implied.

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 both parameters are already documented (sentencia with format examples, limite with bounds). The description adds only the identification convention (relatoría + ponente + fecha) and says nothing about the limite parameter, so it does not meaningfully exceed 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 precise verb and resource: it returns the providencias the relatoría registers as CITANTES of a Corte Constitucional sentencia, and even names the underlying data block ("citaciones"). This clearly separates it from generic search tools like buscar_jurisprudencia and from obtener_documento, which it references only as a downstream route.

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 conveys the intended context (consult who cites a given sentence) and warns that the result is citations, not a verified 'línea'. However, it never states when to prefer this over siblings such as buscar_jurisprudencia or resolver_cita, so the routing decision is left largely implicit.

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?

With no annotations, the description carries the full burden and does well: it discloses the scope boundary (only Gestor Normativo de Función Pública, only valid for buscar_normas), the mandatory filter for 'temas', the prefixed id format, and a non-obvious caveat that DIAN's absence from 'entidades' is a cataloging choice rather than a data gap. It does not address pagination behavior (desde/limite) or response shape, leaving a modest gap.

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 dense but front-loaded: it opens with what the tool returns, then constraints, then scope warnings. The closing DIAN caveat is somewhat repetitive in its phrasing, but each sentence carries actionable information rather than 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?

For a 7-parameter catalog tool with no annotations and no output schema, the description is nearly complete: catalog-to-parameter mapping, mandatory-filter rules, id conventions, and scope limits are all covered. The only omission is pagination behavior for desde/limite, which is minor.

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 57%, so the description must compensate, and it does: it maps each catalogo value to its companion parameters (subtemas uses tema_id, conceptos_fp uses numero/anio), states that filtro is obligatory for 'temas', and explains the 'tema-' prefix convention. Only desde and limite remain undocumented in both places.

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 description states a specific verb and resource: it returns the valid values for the filters of buscar_normas, enumerating the catalog types (tipos, anios, entidades, temas, subtemas, conceptos_fp, normas_fp). It also explicitly distinguishes itself from siblings, naming buscar_normativa_tributaria as the correct tool for DIAN material and excluding SUIN-Juriscol and the high courts.

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?

It states when to use it (to obtain valid filter values for buscar_normas), when not to (does not cover DIAN, SUIN-Juriscol, or the three high courts), and names the alternative tool for the DIAN case. It even flags the mandatory-filter condition for 'temas', which is usage guidance in 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?

With no annotations provided, the description carries the full burden. It discloses that the tool provides classification, not new documents, and implies it lacks full-text and validity data by stating resolver_cita handles those. It does not detail output format or pagination behavior, but it does a good job of setting expectations for a curated list tool.

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 three focused sentences with no filler. It front-loads the source and classification purpose, states what the tool does not provide, and gives a clear usage directive. The heavy use of caps is slightly noisy but does not detract from clarity.

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 the lack of annotations and output schema, the description provides sufficient context for a list/discovery tool: it explains the curation source, the limitation (no new documents), and the relationship to resolver_cita. It does not describe the response structure, but the purpose is simple enough that the description, together with the schema, sets adequate context.

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?

The schema already describes 'desde' and 'texto' (67% coverage), so the description need not repeat them. However, the description adds no parameter-specific meaning and does not compensate for the undocumented 'seccion' property beyond the title's theme focus. 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?

The description states a clear, specific purpose: it lists environmental regulations classified by ANLA/Eureka. It explicitly says 'Lo que aporta es la CLASIFICACIÓN, no documentos nuevos' and instructs the agent to use it 'para descubrir QUÉ normas aplican a un tema ambiental,' clearly distinguishing it from siblings like resolver_cita.

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?

It gives explicit guidance: use this tool to discover which regulations apply to an environmental topic, and then use resolver_cita to resolve each one. It names the alternative tool and explains why resolver_cita is better for full text and validity, making the when-to-use decision unambiguous.

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?

With no annotations, the description carries the full burden and delivers: chunked-not-whole returns, validation failure before the network with a stated missing-parameter and a working minimal example, total/shown/omitted reporting, the exact 'desde' cursor for the next chunk, and the disk-write alternative via 'entero'.

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 behavior and the source-parameter matrix, then the return-metadata contract. Dense but every clause carries information; the liberal ALL-CAPS emphasis is stylistic noise rather than 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?

For an 18-parameter, no-annotation, no-output-schema tool, the description covers invocation rules per source, error behavior, and return shape including pagination. 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 94%, so the per-parameter meanings are already documented with 'Solo X' prefixes. The description usefully synthesizes the source-to-parameter matrix in one place, but adds little semantic detail beyond what the schema fields already state.

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 and resource (devuelve el texto de un documento) and immediately constrains scope: 'troceado, nunca entero'. It enumerates the seven sources and distinguishes the tool from siblings by defining exactly which source each invocation targets.

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 per-source parameter requirements ('gestor necesita id; corte, ruta; suprema, ruta y sala...') and states that mismatched combinations are rejected before network access. It implies but does not explicitly state the workflow position relative to siblings like buscar_normas, so routing guidance is strong but not fully spelled out.

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?

No annotations are provided, so the description carries the full behavioral burden. It adds useful context about batch resolution and avoiding repeated downloads for multiple articles, but it does not describe permissions, read-only nature, error behavior, or the validation mode, which is only covered in the schema.

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 usage rule, and every sentence has a practical function. It is dense but not bloated, though the multiple examples and batching explanation make it slightly longer than strictly necessary.

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 the rich schema descriptions, the description is complete enough for an agent to select and invoke the tool correctly. It covers purpose, usage routing, batch behavior, and article extraction, but omits the validation mode and does not compensate for the absence of annotations with broader behavioral context.

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 100%, so the schema already documents all seven parameters, including examples, defaults, and the validar/formato/contexto behavior. The description reinforces the batch citas and articulos patterns, but adds little parameter meaning beyond what the schema already provides.

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 description states a specific verb and resource: resolving legal citations such as laws, decrees, and rulings. It distinguishes this from imprecise word-based search and gives concrete citation examples, so an agent can identify the tool's purpose 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?

It gives an explicit usage condition: use it whenever the question mentions a concrete norm, because word search is imprecise. It also explains batch citations and multiple articles from the same norm. However, it does not name a specific sibling tool as the alternative and gives no explicit when-not condition.

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