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

With no annotations, the description carries the full burden. It discloses important behavioral traits: it only identifies POTENTIAL conflicts, does not detect semantic contradictions, and returns links for verification. This goes beyond a simple action description, though it omits details like failure behavior or data 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 a single, information-dense sentence with clear components and a separate warning. It is concise and front-loaded with 'EVIDENCIA', though the heavy use of capitalization and semicolons makes it slightly less readable than ideal, but every part 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?

Given the tool's complexity (two norms, multiple evidence types) and lack of output schema, the description sufficiently indicates what is gathered and how to treat the result (verify links). It does not detail the exact return structure, but sets expectations for a potential-conflict evidence report.

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% for all three parameters, so baseline is 3. The description adds minimal parameter-specific insight; it mentions 'pasajes que mencionan un tema' which aligns with 'sobre', but the schema already explains that parameter. No significant added semantics.

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: 'Reúne para dos normas la EVIDENCIA de un posible conflicto' and lists specific evidence components (identificación, vigencia, jerarquía, reformas, pasajes). It distinguishes itself from siblings by explicitly noting it does NOT detect semantic contradictions, making it unique among conflict-related 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?

The description gives context for use: it gathers potential conflict evidence, not legal conclusions, and instructs to 'verifica en los enlaces antes de actuar'. It excludes semantic contradiction detection, but does not name alternative tools explicitly, so slightly short of full 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?

Without annotations, the description discloses critical behavioral traits: it does not search article text, its vigencia field is unreliable and contradicts the document's own record, its index has gaps (Teletrabajo example), and long phrases match loosely. This far exceeds baseline.

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 provides essential either what the tool does or its limitations and alternatives. The use of caps for critical warnings aids parsing, and it remains focused despite its 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?

Given the tool's complexity and the absence of an output schema, the description covers scope, exclusions, reliability caveats, index gaps, and fallback tools, making it sufficient for an agent to select and 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?

The description clarifies that 'texto' covers title, epigraph, subject, or issuing entity, and warns that the 'vigencia' filter/field is based on the buscador and unreliable. Since the schema already describes most parameters (80% coverage), the description adds meaningful context but doesn't need to explain 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?

The description clearly specifies the tool searches SUIN-Juriscol documents by title, epigraph, subject, or issuing entity, and distinguishes it from resolver_cita by stating it is not for exact citations. It also notes its coverage of documents not in Gestor Normativo, differentiating from sibling search 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?

Explicitly states when not to use: for exact citations ('LEY 909 DE 2004' returns nothing) and points to resolver_cita. Also advises trying buscar_por_tema or resolver_cita when a subject search doesn't yield expected results, providing clear 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?

Since no annotations are provided, the description carries the full burden. It discloses the return format (sentencia, tipo, fecha, síntesis, and a route to obtener_documento) and the special handling of long queries (retrying with a distinctive term and announcing it). It does not explicitly state that the operation is read-only, but the wording 'Busca' and 'Devuelve' strongly implies a non-destructive search, so the transparency is good but not exhaustive.

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: it starts with the core purpose, then provides usage context, return details, and query limitations. It contains some redundancy (e.g., repeating 'CORTE CONSTITUCIONAL' in caps and restating the alternative tools), but overall it is efficient and every sentence serves a purpose.

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 return fields. It also covers the main usage context, distinguishes from sibling tools, and notes a known limitation. It does not mention all possible edge cases (e.g., empty results, error handling), but it is sufficiently complete for an agent to invoke the tool correctly in most scenarios.

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 descriptions already cover 100% of the parameters, so the baseline is 3. The tool description adds context about the 'termino' parameter (that long phrases are not indexed and will be retried with a shorter term), which is helpful but does not fundamentally redefine any parameter. Therefore, it stays at the baseline with a slight bonus for that extra context.

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 purpose: it searches for sentencias and autos in the Constitutional Court's relatoría. It also distinguishes the tool from related ones by name (Gestor Normativo, buscar_jurisprudencia_suprema, buscar_jurisprudencia_consejo_estado), making its scope unmistakable.

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 explicitly states when to use this tool (for recent constitutional jurisprudence) and when not to (for other courts, pointing to specific alternatives). It also provides practical guidance about the relatoría's indexing limitation with long phrases and explains the retry behavior, which helps the agent use the tool effectively.

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. It transparently discloses that results include the juridical problem and answer, not the full text, but a SAMAI link, and explains the exact-match expansion to OR with a notice.

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 a bit verbose with editorial remarks like 'que es lo que de verdad sirve', but it is well-structured with clear sections for purpose, output, and search behavior, making it easy 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?

Given no output schema, the description sufficiently covers expected results (problem/answer, link, not full text) and search nuances. It lacks explicit error/empty-result handling, but overall it provides enough context for correct usage.

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?

All 4 parameters are described in the schema, and the description adds meaningful context: exacto behavior with fallback to OR, limite meaning results per page, and pagina explaining SAMAI's paging constraints versus other tools.

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 purpose: searching 'providencias tituladas' from the Consejo de Estado, and explicitly distinguishes it from the Corte Constitucional and Corte Suprema, which differentiates it from siblings like buscar_jurisprudencia_suprema.

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 provides guidance on when to use this tool by noting it is distinct from other high courts, and explains search behavior (OR default, exact phrase with exacto=true). However, it does not explicitly compare against the generic buscar_jurisprudencia or other specific tools.

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 it does so richly. It discloses full-text search, no stop-word removal, exact-phrase default, example result counts, and that results include cited norms plus a route for full-text retrieval.

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 every sentence earns its place: it front-loads purpose and differentiation, then adds workflow integration and search behavior. It is long but not wasteful, with clear structure and 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?

Despite lacking annotations and an output schema, the description covers output contents (cited norms, route), integration with sibling tools, and search quirks. This is sufficient for an agent to invoke the tool correctly and handle results across a multi-step workflow.

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 provides 100% coverage with detailed descriptions for all 7 parameters, including exacto's OR behavior and sala's requirement. The description adds search-behavior context but does not materially improve parameter-level meaning 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?

The description clearly states the tool searches Supreme Court rulings by chamber (Tutelas, Civil, Laboral, Penal) since 1991. It uses a specific verb ('Busca') and resource, and explicitly distinguishes it from buscar_jurisprudencia, which targets the Constitutional Court.

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 explicitly contrasts with a sibling tool by naming it and clarifying that the two courts are different. It also provides chaining guidance: cited norms can be resolved with resolver_cita and full text via obtener_documento with fuente="suprema". It advises using distinctive terms and notes the exact-phrase 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 provided, the description carries the burden of behavioral disclosure. It reveals a key limitation: the index covers only thematic summaries, not the full text ('indexa solo los resúmenes temáticos, NO el articulado completo'), and that terms are OR-joined. However, it does not describe the response format or pagination behavior, which could be useful.

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 appropriately sized, with each sentence earning its place: main purpose, critical indexing caveat, search strategy, and alternative tool references. It is front-loaded with the core function and maintains relevance throughout.

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 tool's complexity (8 parameters, no output schema, no annotations), the description provides essential context: scope, limitations, and alternative routes. It does not explain result ordering or default behavior with zero parameters, but the schema already documents parameter constraints and defaults, so the description covers the most important non-obvious aspects.

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 baseline is 3. The description adds value beyond the schema by explaining that the search engine uses OR logic and that users should use few, distinctive words, directly guiding the 'palabras' parameter. It also points to specific alternatives for other search needs, clarifying when this tool's parameters are 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 purpose: 'Busca leyes, decretos, resoluciones, conceptos y sentencias del sector público colombiano.' It specifies the verb (buscar), the resource type, and the target sector, which distinguishes it from more specialized search siblings. The list of document types adds specificity beyond a generic 'search'.

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 explicitly provides usage guidance and alternatives: 'Para buscar dentro del texto de una norma concreta, usa obtener_documento con fuente="gestor" y buscar_en_texto. Para una cita exacta, usa resolver_cita.' It also advises how to use the tool effectively ('Usa pocas palabras y muy distintivas') based on the OR behavior.

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 burden for behavioral disclosure. It clearly discloses that the tool does not return full text (only epígrafe and links to PDF/detail page), that personal acts are hidden by default (two out of three documents), and that there are 785 documents, setting clear expectations about output and scope.

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 and information-rich with every sentence earning its place: purpose, scope, output limitation, exclusions, sibling alternatives, and a critical default-behavior warning. The use of SHOUTED keywords ('ÚSALA', 'NO', 'OCULTA') makes key guidance scannable without adding unnecessary bulk.

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 having no output schema and no annotations, the description covers all essential context: document type scope, topical scope, document count, return format (epígrafe + links, not text), navigation to alternatives for out-of-scope queries, and the critical default filter behavior. The 7-parameter schema is well-complemented by the description's behavioral context, making the tool safely invocable by an agent.

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 86% of parameters with descriptions, but the description adds crucial semantic context beyond the schema: it explains the meaning of incluir_administrativos (nombramientos y encargos) and why it matters statistically, and clarifies that pagination means 20 items per page with 40 total pages. This supplements the schema meaningfully without redundancy.

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 identifies the tool as searching ANH resolutions, agreements, and circulars related to hydrocarbons, listing specific topics and document count. It distinguishes itself from siblings by explicitly stating it is for hydrocarbon and royalty regulation, not for national laws/decrees of any sector, and names alternatives (resolver_cita, buscar_normas).

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 explicit when-to-use (hydrocarbon regulation and royalties) and when-not-to-use (not for national laws/decrees, not for other sectors) guidance, naming specific alternative tools. Also gives critical usage detail about personal acts being hidden by default and how to include them, which is essential for correct tool selection and invocation.

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. It discloses that most results are PDFs without extractable text, that vigencia is often not published, and where it appears it's only the portal's own claim. It details divergent filter behaviors across entities (Invima requires text/year, Superfinanciera/Supertransporte stay in current year, ANM ignores year for circulares) and advises specifying a year explicitly. This is exceptional transparency.

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 long but well-structured with clear sections: scope definition, explicit 'CUÁNDO NO USARLA', then a paragraph on PDF/vigencia caveats, then a dedicated section on filter divergence. It is front-loaded with purpose and exclusions. Every sentence earns its place given the tool's complexity; it is dense but not redundant.

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 tool with 7 parameters and many entity-specific behaviors, the description covers purpose, exclusions, filter caveats, vigencia limitations, and hints that responses include metadata about which behavior was applied ('Cada respuesta dice cuál de estas cosas hizo'). It doesn't detail the exact return format, but that's not required without an output schema. The only minor gap is pagination behavior across entities, but that's inferable from the 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 71% (limite and pagina lack descriptions), but those are self-explanatory pagination parameters. The description adds significant semantic value beyond the schema: it explains how the 'texto' and 'anio' filters behave differently per entity, and warns about the need to specify a year for certain entities. It also clarifies 'entidad' by saying each entity declares its sector and limits, and mentions 'solo_entidad' behavior indirectly. This goes well beyond the schema's basic descriptions.

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 (buscar) and resource (actos administrativos de reguladores y ministerios sectoriales) with a clear exclusion: 'que el Gestor Normativo NO cataloga.' It explicitly contrasts with siblings resolver_cita and buscar_por_tema, so an agent can immediately tell this tool apart from the national-law 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?

A dedicated 'CUÁNDO NO USARLA' section explicitly says to use resolver_cita or buscar_por_tema for leyes and decretos nacionales, and warns that the Decreto Único Reglamentario of each sector is already in the Gestor. It also directs to resolver_cita for real vigencia. This is explicit when-not-to-use and 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?

Without annotations, the description carries the full burden, and it does well. It discloses the return format ("Devuelve el extracto... y el enlace al texto completo"), the performance behavior ("la primera búsqueda de cada término tarda ~20 s"), and the pagination quirk ("las páginas siguientes del MISMO término son instantáneas"). These are critical behavioral details not otherwise available.

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 well-structured and front-loaded. It starts with the core purpose, then differentiation, return value, follow-up tool, and a performance warning. Every sentence earns its place, and the AVISO is long but 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 lack of output schema and the tool's complexity (search with pagination and performance quirks), the description covers the essential information: what it searches, what it returns, how to read the document, and how to paginate efficiently. It also explains the unusual 20-second first-query delay, which is crucial for agent planning.

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 67% of parameters with descriptions (texto and desde), and the description adds meaningful context for "desde" by explaining its role in pagination: "pagina con desde en vez de lanzar búsquedas nuevas." The description does not elaborate on "limite," but the schema provides default, minimum, and maximum values, so the marginal gap is small.

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 what the tool does: "Busca en el normograma de la DIAN: decretos, resoluciones, conceptos y circulares en materia tributaria, aduanera y cambiaria." It uses a specific verb (Busca) and a specific resource (normograma DIAN), and explicitly differentiates it from siblings with "Es lo que ninguna otra herramienta de este MCP cubre."

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 tells the agent when to use this tool: when searching for DIAN tax/customs/exchange regulations, and it explicitly names the alternative for reading full documents: "Para leer el documento usa obtener_documento con fuente=\"dian\"." It also provides usage guidance for pagination, advising to use "desde" instead of launching new 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?

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?

With no annotations, the description carries full burden. It discloses key behavioral traits: the query resolves against a packaged index making it instantaneous and offline-capable; each result includes specific fields (temsubid, normid); the prefix 'ts-' is part of the ID and must be preserved; and it warns that IDs from different taxonomies can collide, potentially returning the wrong topic. This is rich behavioral context.

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 front-loaded with the main function. Each sentence adds value, though the last sentence about taxonomies and prefixes is somewhat dense. Overall, it's well-structured with no wasted words.

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 explains the main return values (tema, subtema, associated norms/sentences/concepts, temsubid, normid). It also explains follow-up usage and an important caveat about catalog collisions. It doesn't explicitly mention pagination or the 'limite' parameter, but overall it gives enough context to use the tool 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 50% (texto described, limite not). The description does not mention parameters at all, so it adds no meaning beyond the schema. The tool description neither explains 'limite' nor reinforces its usage. For a low-to-mid coverage, the description should have stepped in, but it didn't.

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 purpose: 'devuelve tema, subtema y las normas, sentencias y conceptos asociados.' It also differentiates it from siblings by mentioning the 'índice empaquetado' (instantaneous, works offline) and the specific ID handling with 'ts-' prefix, which is unique to this tool.

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 clear context for when to use this tool: for a 'Consulta temática oficial' (official thematic query). It implies a use case when the portal is down ('funciona aunque el portal esté caído') and provides guidance on using the returned IDs with 'explicar_relacion_tema'. It doesn't exclude alternatives explicitly, but the context is clear enough.

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. It discloses the unique full-text access capability, the separate compilations (vigentes/derogadas), and the critical literal-signal rule ('Esa señal se traslada literal; no la conviertas en un sí o un no'). While it doesn't detail return structure or pagination, it provides substantial behavioral context beyond the baseline.

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 dense sentences with no filler, containing only high-value information. The use of caps for key directives (ÚSALA, NO, ÚNICA) aids scanning, though it is slightly emphatic. Every sentence earns its place, but the length is near the upper bound of conciseness.

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 compensates by covering what the tool searches, sector scope, how to access full text (via obtener_documento), the vigencia literalness nuance, when not to use it, and alternative tools. This provides everything an agent needs to select and invoke the tool 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. The description adds value by explaining the default behavior of anio ('SIN ÉL solo se mira el año en curso, que trae muy pocas') and contextualizing compilacion with the explanation of separate compilations and literal signal transfer, exceeding the schema's basic property descriptions.

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 'Busca las resoluciones de la Comisión de Regulación de Energía y Gas' with a specific verb+resource, lists the sector topics (tarifas, conexión, comercialización, plantas solares, gas natural), and explicitly distinguishes from siblings by noting it is the only sectorial source and excluding laws/decrees with resolver_cita/buscar_normas.

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 provides explicit positive guidance ('ÚSALA para la regulación energética y de gas'), explicit negative guidance ('NO sirve para leyes o decretos nacionales de otros sectores'), names alternative tools (resolver_cita, buscar_normas), and directs to obtener_documento with fuente='creg' for full text, leaving no ambiguity about when to use this tool.

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 transparency burden. It discloses parallel searching, source attribution per result, profile-driven source expansion, and the caveat that SUIN validity is labeled per the search engine and is not official. It does not explicitly state read-only behavior, but 'busca' and 'agrega' strongly imply a non-mutating search operation.

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 reasonably compact and front-loaded with the core action, but it packs multiple conditional clauses and caveats into a few long sentences. It remains readable and scannable without being overly 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?

The description explains the result shape (source + link + source declaration) and the SUIN validity caveat, which is important given no output schema is present. It does not detail error behavior, pagination, or exact response structure, but for a multi-source search tool the provided context is largely sufficient.

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 provides complete coverage for all four parameters, and the description adds useful semantic context for 'perfil' and 'fuentes', such as tributario → DIAN and salud → INVIMA/Supersalud. No parameter is left unexplained.

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?

Clearly states that the tool searches multiple named legal sources in parallel and aggregates results with source and link. It also distinguishes itself from exact-citation and court-specific tools, making its purpose unmistakable.

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 when the query is open-ended or subject-based and no more specific tool is obvious, and tells the user to prefer resolver_cita for exact citations or a dedicated court search for a specific tribunal. This gives clear when-to-use and when-not-to-use 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 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?

The description explains the core behavior (marking additions/deletions, classifying differences, detecting editorial changes, flagging manual review) but does not mention side effects, permissions, or rate limits. Since no annotations are provided, the description carries the burden and could be more explicit about read-only 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 description is a single dense sentence that packs substantial information without unnecessary verbosity. It is structured logically, though it could be split into clearer sentences for readability.

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?

There is no output schema, but the description gives a clear picture of the tool's behavior and expected outcome. It sufficiently describes the comparison, classification, and manual review flags, allowing an agent to infer what the result will look like.

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% with all four parameters documented with examples. The description adds no additional parameter semantics beyond the schema, so it meets the baseline but provides no extra 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?

The description clearly states the verb 'Compara' (compare), specifies the resource (articles between two norms), and distinguishes it from sibling search/list tools by focusing on comparison and diff classification.

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 describes the main function but does not explicitly state when to use this over alternatives like 'cambios_desde' or 'analizar_conflicto'. The phrase 'Sin modelo semántico' hints at a limitation but does not provide clear selection 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 the full burden of behavioral disclosure. It transparently explains that the tool runs preconfigured sources/filters, returns profile results with sector, warning, date, and disclaimer, and that each profile declares its own scope/limits. This goes beyond surface-level description, though it omits details like error handling or authentication, preventing 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?

The description is three sentences and front-loaded with the core purpose. Every sentence earns its place: the first states what it does, the second explains the output and profile limitations, and the third provides explicit negative guidance. There is no redundancy or fluff, making it 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?

Given the moderate complexity (3 params, no output schema, no annotations), the description covers the main operational context: preconfigured sources, profiles, output contents, and usage boundaries. However, it lacks a detailed breakdown of the return structure or behavior on invalid inputs, which would be needed for a perfect 5. The presence of sibling-tool references adds contextual completeness.

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 input schema covers 100% of parameters with descriptions, including valid profile IDs, the 'texto' example, and the 'limite' range. The description adds little beyond the schema—mainly repeating profile names and giving usage context. Since schema coverage is high, a baseline of 3 is appropriate, and the description does not meaningfully enhance parameter understanding.

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 begins with a specific verb and resource: 'Ejecuta una consulta con las fuentes y los filtros preconfigurados de un perfil', clearly identifying the tool's function. It distinguishes itself from siblings by listing profile types and explicitly referencing alternative tools like buscar_normas and resolver_cita, making the purpose unmistakable.

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 provides explicit when-to-use guidance by naming the profiles and instructing to use describir_fuentes for the list of profiles. It also contains a clear negative directive: 'NO uses un perfil para lo que no cubre' and points to buscar_normas or resolver_cita for other matters, leaving no ambiguity about when to use this tool versus 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?

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?

The description openly states that the tool never invents a status and will say when a status is not available, including a confidence level. This is especially valuable because no annotations are provided. It does not mention side effects, but the tool appears read-only, so no contradiction exists.

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 a single, focused sentence that conveys the core behavior, output types, confidence levels, and fallback policy without unnecessary detail. It is concise yet complete.

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 adequately explains the nature of the output: status values, confidence levels, and the 'do not invent' rule. It could be slightly more explicit about the format of the returned guidance, but overall it provides enough context for an agent to use the tool 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?

The single parameter 'cita' is clearly described with examples ('Ley 909 de 2004' or 'Decreto 1072 de 2015'), and the schema coverage is 100%. The description adds enough context to understand what kind of citation is expected.

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 purpose: to return the validity status of a legal norm. It specifies the main output values ('Vigente', 'Derogado', 'Vigencia en Estudio') and the confidence levels, which distinguishes it from sibling tools like buscar_normas or obtener_documento.

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

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

The description explains the tool's behavior regarding confidence levels and fallback when no status is found, but it does not explicitly say when to use this tool versus an alternative sibling such as historial_norma or resolver_cita. The guidance is implicit rather than explicit.

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 no network access, that indices are packaged, that the full table is long, and that the parameter returns only one source's scope. This gives the agent a clear mental model of the tool's 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 description is compact and front-loaded: first sentence gives the core purpose, second adds usage timing, third clarifies parameter behavior. Every clause earns its place; 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?

For a simple single-parameter tool with no output schema and no annotations, this description is complete. It covers purpose, when to use, network behavior, parameter effects, and output size expectations, making it self-sufficient for an agent.

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?

Although the schema already documents the 'fuente' parameter at 100% coverage, the description adds meaning: with the parameter it returns ONLY that source's scope (which 'usually is what's needed'), without it the full table is long. This advises on parameter choice and output size 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?

The description states the tool declares the real scope: which source answers each question, what is not covered, and the generation date of packaged indices. This specific verb-resource pair (declara alcance) clearly distinguishes it from sibling search tools by being a metadata/inventory tool.

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 usage instructions: use it BEFORE concluding something doesn't exist from an empty search and to check if the index freshness is current. It also states 'No consulta la red' as an exclusion, clarifying it is not for live lookups among the sibling search tools.

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 and excels: it discloses the activation flag (EXPEDIENTES=1, disabled by default), memory vs. disk persistence via EXPEDIENTES_TTL_MS and EXPEDIENTES_DIR, and the exact behavior of each action (e.g., 'crear' returns the id, 'agregar' requires an already created expediente). This goes well 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 a concise, information-dense paragraph that front-loads the primary purpose, then covers configuration and action semantics in order. Every sentence contributes new behavioral information without redundancy, making it highly 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?

For a tool with 5 parameters, no output schema, and no annotations, the description fully covers the lifecycle (create, add, read, export), persistence behavior, activation requirements, and parameter constraints. It provides enough detail for an agent to select and invoke the tool correctly in most scenarios.

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 adds minor clarifications such as 'agregar' requiring an already created expediente and the markdown output for 'exportar', but it mostly reiterates schema details. Overall it adds marginal 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?

The description opens with 'Crea, agrega, lee o exporta un expediente para agrupar consultas, citas y observaciones de una investigación', explicitly naming the verbs and resource. This clearly distinguishes it from sibling search/retrieval tools, making the tool's purpose unambiguous.

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?

Clear context is provided: it is for grouping investigation-related items, requires the EXPEDIENTES=1 flag to be enabled, and supports four specific actions. No explicit alternatives are mentioned, but the tool's role as a container versus the siblings' search functions is implied, so there is clear context without exclusions.

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?

Despite no annotations, the description discloses key behavioral constraints: the requirement that both IDs come from the same busqueda row, the format of temsubid with prefix, and rejection of other catalog IDs. It does not detail error handling or response format beyond mentioning the return as an extract, but the constraints add meaningful 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 three sentences, front-loaded with the tool's purpose, followed by usage constraints and an alternative. Every sentence adds value with no redundancy or 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 simple 2-parameter tool with no output schema, the description adequately explains return value (restrictor excerpt), input requirements, and an alternative for related queries. It doesn't specify error cases, but this is not a significant gap given the focused nature of 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%, but the description adds crucial semantics: the 'same row' relationship between normid and temsubid, and the explicit rejection of IDs from other catalogs. This goes beyond the schema's property descriptions, which only state the source and prefix.

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 purpose: 'Devuelve el "restrictor": el extracto que explica por qué esa norma es pertinente para ESE subtema en concreto.' It uses a specific verb ('devuelve') and resource (el restrictor), and distinguishes itself from siblings by emphasizing the specific subtopic relationship and referencing buscar_por_tema for identifiers.

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 usage guidance is provided: both identifiers must come from the same row of buscar_por_tema, and ids from listar_catalogos or other catalogs are rejected. It also offers an alternative tool (obtener_documento with fuente='gestor') for seeing all restrictors, clarifying when not to use this tool.

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?

The description conveys that the tool is read-only ('Devuelve') and clarifies what it does not do (it is not a validity deduction). However, it does not explicitly address side effects, permissions, or potential errors. Given the absence of annotations, the description carries the full burden but stops short of a complete behavioral 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?

The description is concise, consisting of two sentences that convey purpose, content, and the key distinction from another tool. Every word adds value, with no redundant or irrelevant 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?

The description provides sufficient context for correct usage: it explains what the tool returns, what it does not do, and which sibling tool to use for current status. Combined with the well-structured schema, this gives a complete picture without needing an 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?

The schema descriptions cover 100% of the parameters and provide meaningful examples and constraints (e.g., 'ej. "6"' for articulo, maximum for limite). This goes beyond simple parameter names, adding practical guidance for usage. A score above 4 would require additional nuance not present in the description itself.

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 purpose: it returns the chain of reforms (modifications, additions, repeals, substitutions) noted by the Manager for a given norm. It also specifies the resource (norma) and the action (devuelve la cadena de reformas), making it immediately distinguishable from other 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?

The description explicitly differentiates this tool from resolver_cita, stating that it provides the portal's notes rather than a validity deduction and directing the user to resolver_cita for current legal status. This gives clear guidance on when to use this tool and when to use an alternative.

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?

Since no annotations are provided, the description carries the full behavioral disclosure burden. It discloses the volume constraint on 'temas', the id prefix convention ('tema-24457') due to taxonomy reuse, and the subtle trap that DIAN's absence from the entity catalog does not mean DIAN regulations do not exist. These are non-obvious behaviors beyond what the schema reveals.

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 a single dense paragraph, but every sentence contributes value—from listing catalog types and counts to explaining special cases and scope limitations. It is appropriately sized for the complexity, though it could benefit from bullet points to improve skimmability. It is front-loaded with the main purpose before diving into cautions.

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 absence of an output schema, the description covers essential context such as scope limitations, required 'filtro' for 'temas', and the prefix convention. It does not explicitly describe the return format or pagination behavior, but the schema already defines 'limite' and 'desde' with defaults. The description is complete enough for a catalog-listing 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?

The description adds significant meaning to the 'catalogo' parameter by explaining all seven enum values and their specific purposes. It also clarifies that 'tema_id' is used with 'subtemas' and 'numero'/'anio' with 'conceptos_fp'. However, it does not elaborate on 'desde' and 'limite' (pagination parameters), which are already documented in the schema with defaults, so the description compensates well for the 57% schema coverage.

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 that the tool lists valid catalog values for buscar_normas filters (document types, years, entities, themes) and also supports special catalogs for subtopics, concepts, and DAFP norms. It goes beyond the title by naming the specific resource and filter context, and differentiates from siblings by explicitly limiting its scope to the Gestor Normativo de Función Pública.

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 provides explicit usage guidance: it says these catalogs are ONLY for buscar_normas and do NOT cover DIAN (suggesting buscar_normativa_tributaria as an alternative), SUIN-Juriscol, or the high courts. It also explains that the 'temas' filter is obligatory due to volume and instructs how to use subtemas and conceptos_fp with specific parameters. This is clear when-to-use and when-not-to-use 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 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 provided, the description carries the full burden and does disclose important side effects: it never returns the entire document, can write to disk with entero=true, and can download with ruta_destino without returning text. It does not mention error cases or output format details, but the key behaviors are transparent.

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 fairly concise and well-structured, with a clear introductory sentence followed by source-specific details and behavioral notes. There is slight redundancy between 'troceado, nunca entero' and the later 'Nunca devuelve el documento entero', but this does not significantly hurt 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?

The description explains the main outputs (text chunks, total/mostrado/omitido, path when entero=true, download with ruta_destino) despite the absence of an output schema. It also references related search tools like buscar_normativa_sectorial and buscar_jurisprudencia_consejo_estado, placing the tool in context. Minor gaps remain around exact return structure and failure behavior.

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 description adds substantial meaning beyond the schema by mapping each source to its required identifier (e.g., gestor uses id, consejo uses token, sectorial uses entidad + url). It also clarifies parameter exclusivity, such as seccion only for corte and historial only for gestor, making correct parameter selection much easier.

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 text of a document from one of seven named sources. It also differentiates itself from sibling search tools by focusing on document retrieval and content extraction.

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 useful guidance on how to use sub-features like buscar_en_texto, articulo/seccion, and historial, and explains entero and ruta_destino behavior. However, it does not explicitly state when to prefer this tool over sibling search tools, leaving that comparison 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?

Sin anotaciones, la descripción asume la carga de explicar el comportamiento: devuelve identificación, vigencia, texto pedido y enlaces; aclara que en modo validar nunca afirma vigencia; y menciona que con articulos la norma se descarga una sola vez. No detalla posibles errores o efectos secundarios, pero para una herramienta de resolución de citas es suficientemente transparente.

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?

La descripción es informativa y no contiene relleno, pero es un párrafo denso con frases en mayúsculas y enumeraciones largas. Podría organizarse mejor en viñetas o secciones, aunque cada oración aporta información útil.

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?

Dado que no hay esquema de salida, la descripción explica bien los tipos de respuesta: resolución con enlace, validación clasificada, y control del contexto y vigencia. No cubre posibles errores, pero el contexto es suficiente para que un agente entienda cuándo y cómo usar la herramienta.

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?

Aunque el esquema ya documenta cada parámetro, la descripción añade valor con ejemplos concretos, explica la relación entre url y validar, el uso de citas para lotes y la combinación de articulos con cita. Cubre todos los seis parámetros y aclara las opciones de comportamiento.

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?

La descripción establece claramente que la herramienta resuelve citas normativas concretas y la diferencia explícitamente del buscador por palabras, indicando cuándo debe usarse. Incluye ejemplos representativos de citas de leyes, decretos, sentencias y artículos.

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?

Se indica de forma directa que debe usarse siempre que la pregunta mencione una norma concreta y se advierte evitar el buscador por palabras. También explica cuándo usar los parámetros citas, articulos, validar y contexto, con ejemplos.

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