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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: the operation rewrites the local catalog, is extremely slow, returns a diff, and keeps a backup so a failed crawl doesn't leave the server without a catalog. This clearly discloses side effects and failure safety, meeting the bar for high 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 extremely concise: three short sentences that front-load the primary action, then provide a performance warning, usage guidance, and return/backup behavior. Every sentence earns its place 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?

Given that an output schema exists, the description does not need to detail the diff structure, but it does mention the diff and the backup mechanism. It covers failure safety and performance, which are essential for a mutation tool. However, it omits any mention of how `anio_min`/`anio_max` affect the update, a gap that matters for full 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?

Schema description coverage is only 33% (only `encuestas` has a description). The description adds context for `encuestas` (always filter with it) but offers no explanation for `anio_min` and `anio_max`, which remain undocumented beyond their names and value ranges. The description fails to compensate for the two missing parameter 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 opens with 'Recorre el portal del INEI y reescribe el catalogo local', which clearly states a specific verb ('Recorre/reescribe') and resource (the INEI portal and local catalog). This distinguishes it from sibling tools like listar_encuestas or estado_catalogo, which query or display catalog data rather than updating it.

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 warns that this is the slowest operation and instructs to always narrow with `encuestas` unless the user explicitly asks for the full catalog. It implies when not to use it (e.g., for quick catalog reading) but does not explicitly name alternative tools, so it stops short of a 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses critical runtime behavior: with function 'suma', a household with all missing rows remains missing rather than zero, and treating it as zero biases estimates. It also warns against 'aggregate all numeric' because summing product codes yields meaningless numbers. This adds significant behavioral context that annotations do not convey.

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

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

The description is compact but dense: the first sentence states the core purpose, the second paragraph explains why the tool exists, the third gives usage rules, and the fourth provides a critical warning. Each section serves a distinct function, 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?

Given the tool's complexity (nested variables object, multiple parameters) and the presence of an output schema, the description covers all essential behavioral aspects: aggregation logic, variable selection, missing-value handling, and differentiation from raw joins. The only notable omission is the `nivel` parameter's persona option, which is available in the schema but not mentioned in the text.

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 covers 67% of parameters; the description compensates by explaining the `variables` parameter in depth: users must explicitly map variables to functions because there is no automatic option, and it provides the example of summing product codes as a pitfall. It does not explain the `nivel` parameter, which allows both 'hogar' and 'persona', while the description only mentions household level; this is a slight gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Colapsa un modulo de gastos o produccion al nivel hogar' – a specific verb and resource – and immediately distinguishes itself from raw joins by explaining that modules 07-28 have one row per product and that joining raw inflates estimates. This clearly separates it from sibling tools like enaho_unir_modulos.

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 when to use the tool: for modules 07-28 that have product-level rows and need to be aggregated before analysis. It also instructs users to use enaho_buscar_variable to explore module variables, providing a concrete workflow. However, it does not explicitly list situations where another tool should be used instead (e.g., retaining product-level detail), so it lacks a true when-not clause.

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 adds meaningful behavioral context beyond the readOnly and idempotent annotations: it consults a pre-built index without downloading data, and it discloses error semantics for non-indexed surveys (clear error instead of misleading 'not found'). It also previews the grouped results and pagination, which are not in the annotations.

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

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

The description is concise yet information-dense, with clear sections: purpose, usage guidance, scope/limitations, and return format. It front-loads the primary purpose and gives actionable advice without 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?

Given the presence of an output schema and strong annotations, the description fills key gaps: when to use, performance characteristics, coverage limitations, and error behavior. It is complete enough for an agent to decide whether to invoke this tool and what to expect.

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 describes all 7 parameters with high coverage (100%), so the description need not elaborate on each. It does add conceptual context about the default survey scope and the encuesta override, but this largely mirrors the schema's encuesta description. Overall, the description adds modest 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 a clear statement of purpose: 'Encuentra en que modulo y con que nombre esta una variable.' It also distinguishes itself from siblings by describing it as the most-used, cheapest tool that queries a pre-built index without downloading microdata, making its role unique among the provided sibling 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 explicitly instructs 'Empieza SIEMPRE por aqui cuando no sepas el nombre exacto de una variable,' which is strong guidance. It also explains the default ENAHO scope, the ability to override with `encuesta`, and the coverage limitation of 16/67 surveys, but it does not explicitly name alternative tools for other scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false; the description adds substantial behavioral context by explaining what the diagnostics detect, why failures are dangerous, and that it returns apto_para_estimar with problems separated by severity. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose, then uses a structured bullet list to explain each of the five checks and their consequences. Every sentence adds value, and the markdown formatting makes it scannable; length is justified by the tool's complexity.

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

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

Given the tool's complexity, the description covers purpose, workflow timing, output content ('Devuelve apto_para_estimar y los problemas separados...'), and the key failure modes. It also complements the annotations and schema without relying on them; output schema exists so return-value detail is not required.

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 100% of parameters with descriptions for dataset, salida, and formato, so the baseline is 3. The description does not add parameter-level detail; it mentions dataset only implicitly and leaves salida/formato behavior to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's specific action: determining whether a dataset is fit for its intended use ('Responde si un dataset sirve'). It lists five concrete diagnostic checks and explicitly distinguishes itself from enaho_perfil ('Es distinto de enaho_perfil, que describe'), so it differentiates 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?

It explicitly names the alternative enaho_perfil and contrasts their purposes, and it gives workflow placement: 'Llamala despues de enaho_unir_modulos y antes de publicar cualquier cifra.' This is clear when-to-use guidance with an 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?

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds valuable methodological context: it builds a linearized difference over the full survey design, accounting for covariance between domains. This goes beyond the annotations and clarifies the tool's statistical 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 three sentences: a purpose-driven question, a clear list of outputs, and usage guidance with reasoning. Every sentence earns its place, and it is front-loaded with the core 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?

Given the tool's moderate complexity and the presence of an output schema, the description provides adequate context: purpose, outputs, and when to use it. It does not explain prerequisites, but those are captured in the schema and annotations.

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 high (89%), so parameters are well-documented in the schema itself. The description does not add parameter-specific details but aligns with the overall goal of comparing two groups, so the 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 returns the difference, standard error, confidence interval, t-statistic, and p-value for comparing two groups. It also distinguishes itself from the ad-hoc approach of comparing overlapping confidence intervals, making its specific role clear.

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 advises using this tool instead of checking overlap of individual confidence intervals and explains why that shortcut fails. It does not reference sibling tools directly, but the when-to-use guidance is strong and specific.

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 adds substantial behavioral context beyond the annotations: it explains the idempotent cache behavior (skipping already-downloaded complete modules), ZIP integrity verification with automatic redownload of truncated files, and a per-call download limit that returns a divide-the-request error. This goes well beyond the idempotentHint and readOnlyHint annotations, giving the agent a clear model of the tool's side effects and error handling.

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 remarkably concise: three short paragraphs that front-load the core purpose and return type, then add behavioral details without repetition. Every sentence earns its place, covering idempotency, ZIP verification, and rate limits in a compact way.

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 6 parameters, comprehensive schema, output schema, and annotations, the description covers all critical non-schema information: return type (paths), idempotent behavior, ZIP verification, and request limits. The output schema handles return values, so the description does not need to repeat them. The description is complete for a well-documented download 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 input schema already provides comprehensive descriptions for all 6 parameters (100% coverage), so the baseline is 3. The description adds meaningful context about the download limit per call, which directly affects how many anios and cortes can be requested, and explains the fallback between formats (STATA→SPSS→CSV) which is referenced in the formato parameter. This adds 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 clearly states the tool's function with a specific verb and resource: 'Descarga modulos al cache local.' It also distinguishes itself from siblings by explicitly stating 'NO devuelve microdatos, devuelve rutas,' making it clear this is a download-to-cache tool, not a data retrieval 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 provides clear context for when to use the tool (downloading modules to cache) and what to expect (returns paths, not microdata). It does not explicitly name alternative tools, but the distinction from data-access tools implies when to use it. The idempotent cache behavior and download limit also help the user understand practical usage constraints.

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

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

Annotations already provide safety hints (idempotent, non-destructive). The description adds that the tool returns ZIP paths for later reading with file tools, which is useful behavioral context, but it does not mention potential side effects, caching, or other operational details.

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: two sentences. The first sentence states the action and objects, the second explains the output format and the dictionary's purpose. No unnecessary words 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 that an output schema exists, the description does not need to list return fields. It provides sufficient context: what is downloaded, how the output is returned (ZIP paths), and why the dictionary is valuable. This is complete for a relatively simple documentation download 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 reinforces that the 'anio' parameter is the year ('del anio') and implies the dictionary is year-specific, but it adds no new semantic details about the 'encuesta' parameter beyond what the schema already provides. With 50% schema coverage, the description only marginally supplements the structured fields.

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 downloads technical sheets, variable dictionaries, and questionnaires for a given year ('Baja ficha tecnica, diccionario de variables y cuestionarios del anio'). The verb 'Baja' indicates the action, and the specific resources distinguish it from data download or search tools among the 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?

It provides a concrete usage context by explaining that the dictionary resolves definition doubts that the catalog and index cannot. While it does not explicitly name alternative tools or exclusions, the purpose is clear enough to know when to use this tool versus others.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: it reports the number of variables and rows without downloading, indicates whether the module has its own expansion factor, and explains why rows are lost when joining. This goes well beyond annotations.

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

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

The description is two sentences, front-loaded with a high-level summary of what the tool returns, followed by practical details. It is concise with no wasted words, effectively communicating purpose and key behavioral facets.

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 is a metadata card, the description covers the main outputs, the use case (before joining or estimating), and important behaviors (no download, row-loss explanation). The presence of an output schema and rich annotations reduces the need for the description to explain return values in detail.

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% with some parameter descriptions (modulo and encuesta), but the tool description does not add additional parameter semantics. The description focuses on output content rather than clarifying the meaning or format of parameters like 'anio' or 'modulo'.

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 it provides a 'Ficha de un modulo' with specific elements: nivel, llaves, factor esperado, tamano y trampas. This is a specific verb+resource+output summary that distinguishes it from sibling tools like listing or downloading modules.

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 says 'Consúltala antes de unir o estimar', giving clear context for when to use the tool. However, it doesn't explicitly name alternative tools or provide exclusion criteria, only implies this is a preliminary step to joining or estimating.

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

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

Beyond the read-only/idempotent annotations, the description discloses critical behavioral details: resampling clusters within strata to avoid optimistic standard errors, handling of negative incomes (Gini can fall outside [0,1], Theil discards them), and that the tool warns about negatives. This adds substantial value beyond the annotations.

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

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

The description is concise yet thorough, with a front-loaded purpose followed by method rationale and practical warnings. Every sentence adds value, and the structure is logical and easy to follow.

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 the methodology, edge cases, and usage guidance, which is complete for a complex tool with a companion output schema. It does not need to explain return values or parameters already documented in the schema. A small gap is not mentioning that 'dataset' must be prepared, but the schema covers that.

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 rich parameter descriptions (e.g., encuesta values, replicas range, indicadores list). The description does not add meaning beyond what the schema already 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?

The description clearly states the tool computes inequality measures (Gini, percentiles, ratios) with standard errors that respect the survey design. It distinguishes itself from siblings by emphasizing the bootstrap method for complex survey data, making the purpose specific and non-generic.

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 when this tool is appropriate (when Taylor linearization does not apply) and provides guidance on the number of bootstrap replicas (200 to explore, 500+ to publish). However, it does not explicitly mention alternatives or exclusion cases, so it lacks explicit 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?

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses key behavioral details: cuts are weighted quantiles based on population rather than rows, and results are descriptive without standard errors. It also explains the conceptual relationship to the Gini coefficient, adding context not present in structured metadata.

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 purpose in the first sentence and supplemental detail in two short paragraphs. Every sentence earns its place, covering purpose, methodology, limitations, and alternative tools without 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?

Given the tool's moderate complexity, rich schema descriptions, and existing output schema, the description is contextually complete. It explains the core functionality, key methodological nuance, and when to use a sibling tool, while the output schema handles return-value documentation.

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 already provides descriptions for all five parameters (100% coverage), so the description does not need to compensate. It adds methodological context about weighted quantiles but does not elaborate on individual parameter semantics beyond what the schema already offers.

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 'Reparto por deciles con participacion en el total y curva de Lorenz', which clearly and specifically states the tool computes distribution shares and Lorenz curves by weighted quantile groups. This distinguishes it from sibling tools like enaho_desigualdad, which is explicitly mentioned as the alternative for Gini with confidence intervals.

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 explicit guidance on when to use this tool versus enaho_desigualdad: 'para el Gini con intervalo de confianza usa enaho_desigualdad'. It also clarifies that this tool is descriptive and lacks standard errors, advising the alternative for inferential needs.

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?

Las anotaciones ya declaran readOnlyHint=true e idempotentHint=true. La descripción añade contexto valioso: devuelve fragmentos y no documentos completos, y que es la única fuente que permite cambiar llaves de verificado de false a true. Esto va más allá de lo que las anotaciones proporcionan. No contradice las anotaciones; la referencia a 'pasar llaves' es sobre el flujo de trabajo, no una escritura directa.

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 breve pero contiene varias frases de valor. Está bien estructurada: empieza con la acción principal, luego justifica la utilidad, después da instrucciones de uso y finalmente describe el formato de respuesta. Cada oración aporta información útil, aunque podría condensarse sin pérdida.

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 existe un output schema y anotaciones completas, la descripción no necesita explicar los valores de retorno. Cubre el propósito, cuándo usarla, el prerrequisito y el formato de retorno (fragmentos). No menciona posibles errores ni límites, pero eso no es esencial para un buscador con buena cobertura de esquema.

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?

El esquema cubre 60% (termino, exacto, encuesta tienen descripciones; anio y limite no). La descripción de la herramienta no compensa la falta de documentación de anio y limite. Solo aporta contexto general sobre búsqueda de definiciones, que ayuda a entender termino, pero no proporciona semántica para los parámetros sin descripción en el esquema.

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 comienza con un verbo específico ('Responde dudas de definición') y nombra el recurso (documento y página). Además, aclara la diferencia con el índice de variables: 'El índice de variables da el nombre y la etiqueta; esto da lo que dice el diccionario y el manual'. Esto la distingue claramente de herramientas como enaho_buscar_variable.

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 explícitamente cuándo usar la herramienta: 'ANTES de dar por buena la interpretación de una variable rara, y siempre antes de curar el perfil de una encuesta'. También se menciona un prerrequisito ('requiere haber convertido antes con enaho_documentacion_convertir') y un comportamiento a evitar (nunca devuelve documentos enteros). No se nombran alternativas pero se contrasta con el índice de variables.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds behavioral context by revealing that it also converts already-textual content and specifically highlights the value of Stata .do files. It does not contradict annotations, and the performance expectations add useful transparency beyond what annotations provide.

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 with the main purpose. Each sentence adds value—context, usage guidance, timing, and follow-up—but the length is at the upper bound of conciseness. The inclusion of 'por que' material (the Stata .do part) is valuable, so the length is earned.

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 existence of an output schema, the description is quite complete: it explains the tool's purpose, its valuable content, when to narrow with `documentos`, and the recommended next step. It doesn't mention prerequistes like whether PDFs must be downloaded first, but this is a minor gap given sibling tools handle downloading.

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 75%, so the baseline is 3. The description adds real meaning by giving concrete examples for the `documentos` parameter (`['diccionario']`, `['sumaria', 'ficha']`) and explaining the consequence of no filter ('se convierte la ola entera'). It also reinforces the `encuesta` scope by mentioning the ENAHO, but doesn't elaborate on `anio`, which is slightly lacking.

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 starts with 'Pasa a Markdown los PDF de documentacion del INEI para poder buscarlos' which clearly states the verb (convert to Markdown) and resource (INEI documentation PDFs). It differentiates from siblings like enaho_documentacion_buscar (search) and enaho_descargar_documentacion (download) by explicitly being the conversion step before searching.

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

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

It gives explicit when-to-use guidance: 'ACOTA SIEMPRE con `documentos` salvo que el usuario pida la ola entera' and provides timing expectations (1 minute for dictionary, several for all 27 documents). It also recommends the alternative tool after conversion: 'usa enaho_documentacion_buscar en vez de leer los archivos', making the workflow 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavior context: it returns a year breakdown, disk space, and derived datasets, and notes that the short names are accepted by other tools (enaho_perfil, enaho_estimar, enaho_exportar). No contradiction with annotations.

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

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

The description is compact and well-structured: a one-sentence purpose statement followed by a practical usage tip. Every sentence contributes value—it explains what the tool returns and why to use it—without any fluff or 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 read-only cache status tool with no parameters and an output schema, the description fully covers the return content (year breakdown, disk space, derived datasets) and the real-world use case (avoiding unnecessary large downloads). The tool's role in the ecosystem is clear.

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 tool has zero parameters, and the schema coverage is 100% (empty properties). The description doesn't need to add parameter info. Baseline for 0-parameter tools is 4, and the description focuses on the output rather than parameters, which 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 immediately states 'Que hay descargado, cuanto ocupa y que datasets derivados existen' — a specific verb+resource+scope. It clearly distinguishes from siblings like enaho_descargar (download) and enaho_listar_modulos (list modules) by focusing on cache status rather than downloads or listings.

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 instructs when to use: 'Consultala antes de descargar en masa' and explains why (the full ENAHO is several GB, and modules may already be cached). It does not explicitly mention when-not-to-use or name alternatives, but the strong contextual guidance earns a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: the catalog is a fixed snapshot from the publish date, so newer INEI waves are not visible to the server. It also discloses that the response includes the crawl date and a refresh recommendation, enriching the behavioral model without contradiction.

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, each earning its place: first the purpose, then the trigger condition, then the rationale for the stale catalog. It is front-loaded, concise, and well-structured in Spanish.

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 zero-parameter tool with an output schema, the description is complete. It covers what the tool does, when to use it, why the state can be outdated, and what the response provides (crawl date and refresh advice). It also names the related refresh tool, making it contextually whole.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the baseline is 4. The description doesn't need to explain parameters since the input schema is trivially complete, and the description adds no parameter-related confusion.

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 reports the origin and age of the INEI catalog used by the server. It uses a specific resource and a clear state-query intent, and it distinguishes itself from sibling tools by mentioning the refresh counterpart enaho_actualizar_catalogo.

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: 'Consultala cuando una herramienta diga que un anio no existe y el usuario insista en que si.' It also explains why the catalog might be stale and points to enaho_actualizar_catalogo for refreshing, covering both usage 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds substantial behavioral detail: the Taylor linearization method, degrees of freedom, logit-scale confidence intervals for proportions, automatic detection/warning about the universe issue, and the output fields (CV and confiable). This far exceeds annotation coverage.

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 with clear sections: summary, motivation, method, the 'IMPORTANTE' universe caveat, and output interpretation. Each paragraph serves a purpose, though the motivation paragraph could be tightened. The critical usage note is prominently highlighted.

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 (survey design, 11 parameters) and the presence of a rich input schema and output schema, the description covers all essentials: what it does, the method, the main usage pitfall, and how to interpret reliability. It omits nothing critical for basic 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?

Schema coverage is 91%, so baseline is 3. The description adds valuable semantic context for key parameters: it explains that peso_adicional='mieperho' is the correct method for official population figures, and clarifies the role of the factor expansion. This goes beyond the schema's field 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 the tool's purpose: design-weighted estimation with standard error and confidence intervals. It explains the problem it solves (avoiding simple averages on complex survey data). However, it does not explicitly distinguish from sibling tools like enaho_tabla_cruzada or enaho_regresion, which may also perform survey-weighted analyses.

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 clear guidance on when to use the tool: for design-based estimates where factor expansion is mandatory. It also gives a critical usage rule for population indicators (use peso_adicional='mieperho' to reproduce official figures). It does not explicitly mention alternatives or exclusions, but the context is sufficient.

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

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

Beyond the annotations (idempotentHint true, destructiveHint false), the description discloses important behavioral details: the Excel row-limit refusal prevents silent truncation, and etiquetas=True ensures Stata usability. These are significant additional traits not covered by annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value—one for the main conversion function and one for key behavioral caveats. There is no redundancy or fluff.

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 export tool with a full input schema, output schema, and annotations, the description covers the essential usage context and distinctive behaviors (Stata labels, Excel limit). It is sufficiently complete for an agent 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 description coverage is 100%, and the schema already explains formato options, etiquetas, and the Excel limit. The description adds little beyond what the schema provides, though it re-emphasizes the etiquetas behavior for Stata. This meets the baseline for full 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 uses a specific verb ('Convierte') and resource ('dataset preparado') and clearly states the tool's purpose: converting a dataset to a desired output format. This clearly distinguishes it from sibling tools, which focus on data exploration, estimation, and other ENAHO-specific operations.

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 ('to convert a prepared dataset to a format your team uses') and adds practical guidance about etiquetas for Stata and the Excel row limit refusal. However, it does not explicitly state when not to use it or mention alternatives, though no direct alternative exists among 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 discloses non-obvious behaviors beyond annotations: it saves a new dataset and leaves the original intact, and it warns when names are empty due to missing imports. This complements the idempotentHint and destructiveHint annotations without contradicting them.

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 primary action. It uses two short paragraphs: the first states what the tool does, and the second details a key prerequisite and its consequence. 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?

Given the tool's complexity (3 parameters, output schema present), the description covers the main behavior, output columns, side effects (new dataset), and an important prerequisite. It lacks explicit error-handling details, but the output schema and warnings cover most gaps.

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, so the baseline is 3. The description adds value by explaining what the tool produces (cod_<nivel>, dominio_nombre, area) and by clarifying the dependency of the 'nivel' parameter on an external import for provincia/distrito. This deepens the semantic understanding of 'nivel' beyond its schema description.

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: 'Descompone el ubigeo y anade nombres, dominio geografico y area' (decomposes ubigeo and adds names, geographic domain, and area). It clearly distinguishes this from sibling tools like enaho_ubigeo_buscar by focusing on dataset enrichment rather than 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?

It provides clear context on when the tool works (packaged table covers 25 departments) and gives a prerequisite for province/district levels ('hay que importar una tabla oficial una vez'). It also explains the consequence (names come out empty) and that the tool warns, but it does not explicitly name alternative tools for these cases.

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 goes beyond the annotations by disclosing that the server runs the estimations with the full sample design, that numbers don't pass through the agent's context, that each table gets automatic footnotes including CV>15% warnings, and that partial failures are handled gracefully. These are valuable behavioral traits not conveyed by readOnlyHint/idempotentHint.

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, followed by essential mechanics, an illustrative example, and error handling. Each sentence earns its place; there is no fluff. The length is appropriate for the tool's complexity.

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

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

Despite the tool's complexity (multiple section types), the description covers the main workflow, input specs, failure handling, and accuracy rationale. With an output schema present, it doesn't need to detail return values. The description is sufficiently complete for an agent 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?

The input schema has 100% coverage for all 6 parameters, so baseline is 3. The description adds a concrete example of an estimation section, showing fields like 'dataset', 'variable', 'estadistico', 'valor', 'por', 'peso_adicional', which clarifies the JSON structure beyond the schema's general list. It also explains the narrative concept, providing extra meaning.

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 'Redacta un informe ejecutando las estimaciones' (writes a report by running estimations), specifying both the action (redacta) and the resource (informe). It contrasts with copying numbers and distinguishes from sibling tools like enaho_estimar by emphasizing it is a report-generation tool that takes narrative and calculation specs.

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 clear context: you pass a narrative ('NARRATIVA') and a specification of what to calculate, and the server runs the estimations. It explains the input structure and failure behavior. However, it does not explicitly name alternative tools or state when not to use it (e.g., for single estimations, use enaho_estimar), so it lacks explicit 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?

Annotations already establish read-only and idempotent behavior. The description adds context that these datasets are pre-prepared and can save time, plus notes that the `nombre` identifier is integrated with other tools. This goes beyond basic safety traits and provides useful 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 compact, front-loaded with the core purpose, and every sentence adds value. The first sentence states what the tool provides, the second gives usage guidance and cross-tool integration. No fluff or 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?

Given the tool's simplicity (no parameters), rich annotations, and presence of an output schema, the description covers all necessary context. It explains what the datasets contain, when to use the tool, and how to use its output (`nombre`) downstream. This is complete for a 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?

There are zero parameters, so the baseline is 4 per instructions. The description adds clarity about the output by listing the fields (year, source modules, level, size) and explaining the `nombre` identifier's role in other tools, which is useful even though parameters are absent.

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 this tool lists already-prepared datasets with attributes like year, source modules, level, and size. It uses the verb 'listar' implicitly through the resource description, and it distinguishes itself from other tools by focusing on pre-built parquet files rather than downloads or unions.

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 clear guidance to start here when resuming a session, explicitly stating that it can save download and union work. It also mentions that the `nombre` field is accepted by other tools, implying a workflow. However, it does not explicitly name alternatives or give a 'when-not-to-use' scenario.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals that each survey has its own join keys and expansion factor, that verificado=false surveys have inferred keys requiring confirmation, and that catalog surveys without a profile can be downloaded but cannot be joined. These are meaningful behavioral details not present in annotations.

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

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

The description is well-structured: the first sentence states purpose, the second gives usage guidance, and the remaining sentences add important caveats about verification and profiles. Each sentence contributes distinct, non-redundant 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?

For a zero-parameter list tool with an output schema and annotations, the description covers purpose, when to use, output characteristics (verificado flag, profiles), and limitations. It provides sufficient context for an agent to correctly select and invoke 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?

The tool has zero parameters, so the baseline of 4 is appropriate. The description adds no parameter-specific semantics, but none are needed since there are none.

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 immediately states that the tool lists which INEI surveys the server can handle besides ENAHO, with a clear verb and resource. It further distinguishes itself by listing specific survey topics (ENDES, ENAPRE, ENUT, etc.), making it unique from siblings like enaho_listar_modulos and enaho_listar_datasets.

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 instructs to consult this tool when the user asks about topics ENAHO doesn't measure, providing concrete examples. It also recommends a follow-up action (confirm with enaho_perfil) for surveys with inferred keys, clarifying when additional verification is needed.

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

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

Beyond annotations (read-only, idempotent), the description discloses the internal logic of combining catalog and domain data, and warns about inferred levels for curado=false modules. This adds behavioral nuance helpful for the agent, such as the need to verify those modules.

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 primary purpose. The second paragraph adds necessary technical context about data sources and quality caveats, but remains focused and does not waste 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?

Given the tool's simplicity, the existing output schema, and the annotations, the description adequately covers the main behavior and important caveats. It does not discuss edge cases such as empty years, but that falls outside the tool's core purpose and is not critical.

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 already provides full documentation for both parameters (anio, encuesta), with 100% coverage. The description does not add further parameter-level meaning, only referring to the year generically. Therefore, the baseline of 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 lists published modules for a given year, including their unit of analysis and keys. It distinguishes itself from siblings by specifying the combination of INEI catalog and domain table, and the mention of 'curado=false' adds scope.

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 clear context: use this tool to get an overview of modules for a year, with their analysis unit and join keys. It does not explicitly compare with alternatives, but the distinct focus on 'modulos' and the data combination logic imply a specific 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?

The description discloses key behavioral traits beyond annotations: it returns 'unidades por ola, cuantas sobreviven a todas y la tasa de balanceo' and explicitly states it does NOT assign an expansion factor. This adds meaningful context to the readOnlyHint=false and idempotentHint annotations without contradicting them.

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 with the primary purpose, followed by a crucial caveat in a separate paragraph. Every sentence contributes useful information without 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?

Given the rich input schema, annotations, and presence of an output schema, the description appropriately focuses on high-level behavior and the critical expansion-factor caveat. It does not need to restate return fields or parameter details because those are already captured structurally.

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 high (80%), with descriptions for llaves, modulo, salida, and variables. The tool description itself adds no parameter-level detail, so it does not compensate for the undocumented 'anio' parameter or enhance the schema semantics. Baseline of 3 is appropriate because the schema already carries the parameter documentation burden.

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: 'Reestructura el panel de ancho a largo y cuantifica la atricion,' clearly stating both the transformation and the attrition quantification. This distinguishes it from sibling tools like enaho_unir_modulos and enaho_panel_inspeccionar, especially by adding the wide-to-long restructuring behavior.

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 tells the agent when NOT to rely on this tool for expansion factors and directs to `enaho_panel_inspeccionar` and the manual as the correct alternative: 'NO asigna factor de expansion: el del panel hay que identificarlo con enaho_panel_inspeccionar y el manual.' This provides clear when-not and alternative guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds behavioral context by stating it reports actual detected columns without assuming, and lists the categories of outputs (waves, suffixed variables, candidate keys, factor-like columns). No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and then provides crucial background (panel vs annual) and a usage directive. Each sentence adds value; however, the middle paragraph is slightly verbose and could be tightened while preserving the warning.

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 output schema exists and annotations cover safety, the description sufficiently explains the tool's purpose, the panel-specific context, and what outputs to expect (columns, keys, factors). It stops short of detailing error behaviors, but for an inspection tool with good schema/sibling context, it is complete.

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 50%; 'modulo' has a description and default, 'anio' does not. The description does not elaborate on parameter semantics, but the parameter names and schema constraints make them reasonably clear. It neither adds nor detracts, 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 explicitly states the tool inspects a panel module to reveal its actual columns ('Mira que hay de verdad...'), and distinguishes it from annual ENAHO and from panel-building tools by specifying it reports waves, suffixed variables, keys, and factors. This clearly differentiates it from siblings like enaho_describir_modulo and enaho_panel_armar.

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 timing ('Usala antes de armar nada'), warns against using annual factor07 on panel data, and sets context that panel data is wide-format with suffixed variables. The guidance implies not to use annual ENAHO tools interchangeably and to use this as a precursor to enaho_panel_armar, making when-to-use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, which cover safety. The description adds valuable behavioral context: it is intentionally compact, does not load microdata into context, and reports detected expansion factor and inferred analysis unit. This goes beyond the annotations and is consistent with them.

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 very concise: two sentences that front-load the core output and then add purpose and extra returned info. Every sentence earns its place with zero fluff.

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 has an output schema and clear annotations, the description covers the key returned elements and the rationale for using the tool. It does not explain all edge cases, but it is sufficient for a read-only profiling tool with a simple input 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 description coverage is 67%, with dataset and variables documented in the schema. The description adds no extra parameter-level semantics; max_variables lacks a schema description and the description does not compensate. This is a borderline case where the schema does most of the work.

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 output: type, missing values, quartiles, and value labels for each variable. It also mentions reporting the expansion factor and analysis unit, giving a specific resource. However, it does not explicitly name sibling tools to differentiate from, though the purpose is 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?

The description provides clear context: it exists to decide what to do without bringing microdata into the context, implying use for quick exploratory checks. It does not mention when not to use it or name alternatives, but the use case is well implied.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds value beyond them. It reveals that the tool issues a warning when the welfare variable and poverty line are in inconsistent units, which is a notable behavioral trait not captured by the annotations.

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

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

The description is concise at five sentences, each earning its place: a definition, a conceptual explanation of the indices, and a practical warning. It is front-loaded with the core purpose and contains 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?

The description covers the core purpose, index interpretations, and a key common error, while the input schema documents parameters and the output schema presumably covers return values. It could mention additional data preparation steps beyond unit matching, but for a complex statistical tool, this is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 88% schema description coverage, parameters are already well-documented. The description adds conceptual depth by explaining what the alphas parameter represents (0, 1, 2) and reinforces the critical unit-consistency requirement between variable and linea, complementing the schema's parameter details.

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 'Los tres indices FGT con error estandar bajo diseno complejo', clearly identifying the tool as computing FGT poverty indices with standard errors under complex design. It further distinguishes FGT0, FGT1, and FGT2, making it distinct from sibling poverty/inequality 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 explains the meaning of the three indices and why they are reported together, implying use for poverty measurement. However, it never explicitly states when to prefer this tool over alternatives (e.g., enaho_desigualdad) or mentions exclusion scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it warns about meaning changes, states what it returns (years, labels, gaps, alerts), and explains the underlying data issue. No contradiction, and the additional context goes beyond the simple read-only 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?

The description consists of three sentences, each with a clear role: function, when to use with rationale, and output summary. No redundant information exists; every sentence earns its place. It is appropriately sized and 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?

The tool is contextualized well: it addresses the ENAHO time-series error, explains the problem, and states what the tool returns. With annotations and an output schema present, the description need not over-explain. Minor lack of parameter detail slightly reduces 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 description makes no reference to parameters; it only mentions 'variable' in a general sense. Schema coverage is 50% (encuesta and variable have descriptions, anio_min/max do not), and the description does not compensate by adding semantic meaning for the optional year parameters. This is a notable gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Sigue una variable ola por ola y avisa si cambio de significado' (follows a variable wave by wave and warns if its meaning changed). This is a specific verb+resource that distinguishes it from siblings like enaho_serie or enaho_buscar_variable, emphasizing its unique role as a pre-time-series consistency check.

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 says 'Usala ANTES de construir cualquier serie de tiempo' (use it BEFORE building any time series) and explains the risk of variable code recycling. This provides clear when-to-use context without naming alternatives or when-not-to-use, so it falls just short of full explicitness.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses output details: coefficients, standard errors, t, p-value, confidence intervals, design-based degrees of freedom, and log-odds scale for logit. This is substantial behavioral context that annotations do not provide.

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 structured into three focused paragraphs: definition, usage rationale, and output behavior. Every sentence earns its place without redundancy, making it concise yet information-dense for a complex statistical 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?

Given the tool's complexity, the description plus schema and annotations provide a complete picture. It covers input requirements, statistical behavior, output interpretation, and common pitfalls. The output schema further completes the picture, so no critical aspect 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 91%, so the baseline is 3. The description adds meaning by explaining why factor and cluster matter, including the empirical consequence of omitting them (30-60% underestimated standard errors). Other parameters are already well-covered by the schema, so the description doesn't need to elaborate on all of them.

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 survey-weighted regression with design-corrected standard errors, explicitly naming Stata's svy: regress and svy: logit equivalents. It distinguishes itself from running statsmodels on parquet, leaving no ambiguity about its function.

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 instructs to use this tool instead of statsmodels on parquet and explains why (factor for population inference, cluster for correct standard errors). This gives clear when-to-use guidance and names an alternative, even though it doesn't enumerate all sibling 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?

The description goes well beyond the annotations by disclosing internal behaviors: it downloads and merges missing data reusing the cache, estimates with each year's complex design, calculates year-over-year variation, and validates the variable across waves. This provides significant context about side effects and data quality checks that annotations alone do not convey.

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

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

The description is well-structured with the core action front-loaded, followed by process details, a rationale for choosing this tool, and a critical caveat about monetary values. Each sentence earns its place; it is information-dense without redundancy, appropriately sized for a complex 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?

Given the tool's complexity (9 parameters, output schema available), the description is complete: it explains the workflow, the reason for its existence versus a loop, the side effects (download/cache), and a key interpretative warning. The presence of an output schema means return-value details need not be in the description.

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 high (78%) with parameter descriptions already present. The description adds global context (the same estimation is applied each year) but does not provide additional per-parameter meaning beyond what the schema already states. This aligns with the baseline 3 for high 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 opens with a specific verb+resource statement: 'Repite la misma estimacion en cada anio del rango y devuelve la serie.' It clearly explains the tool's core function (produce a temporal series by repeating an estimation) and explicitly contrasts it with calling enaho_estimar in a loop, distinguishing it from its closest sibling.

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 guidance on when to use this tool instead of alternatives: it checks the index for variable existence and label changes, which is stated as the main reason to use it rather than looping over enaho_estimar. It also warns about monetary values requiring deflation, adding caution for interpretation.

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 discloses behavioral traits beyond the annotations: it downloads modules if needed ('Descarga los modulos si hace falta'), examines real data characteristics (cardinality, uniqueness, overlap), and always returns `inferido: true`. This adds context about side effects and output semantics that annotations (readOnlyHint=false, idempotentHint=true) do not specify.

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 longer than the minimal two-sentence example but is front-loaded with purpose and usage. Each sentence provides useful context (when to use, what it does, how to interpret results, when not to use). It is somewhat verbose with stylistic emphasis, but not wasteful.

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 complex inference tool, the description covers the essential decision-making context: why it exists, when to use it, what it does (download and inspect data), what the result always includes (`inferido: true`), and how to validate before publishing. The existence of an output schema means return details don't need to be spelled out. This is complete for the tool's 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?

Schema coverage is 75%, and the description adds limited parameter-specific meaning beyond what's already in the schema. The `modulos` parameter's need for at least two modules is already described in the schema; the description reinforces it but does not add new semantics for `anio` or `corte`. 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 opens with a clear verb+resource: 'Descubre como unir dos modulos de una encuesta que nadie ha curado' (discover how to join two modules of an uncured survey). It further distinguishes itself from sibling `enaho_unir_modulos` by specifying it is for cases where that tool fails due to missing declared keys, and from profile-based tools by saying curated knowledge wins when a profile exists.

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 to use: 'Usala cuando `enaho_unir_modulos` falle porque la encuesta no tiene llaves declaradas' (use when enaho_unir_modulos fails because the survey has no declared keys). Also gives a clear exclusion: 'Para las encuestas que SI tienen perfil, no uses esto' (for surveys with a profile, don't use this), naming the alternative approach.

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 goes beyond the annotations by disclosing specific return values: both uncorrected and corrected statistics, average design effect, and count of cells with expected frequency below 5. This rich output behavior is not implicit in readOnlyHint/idempotentHint and adds valuable transparency. Slightly more could be said about edge cases, but it 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?

The description is well-structured and efficient: first sentence states purpose, second explains the statistical problem, third lists outputs. Every sentence earns its place, and it is front-loaded with the core function. Despite some technical density, it remains concise and scannable.

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 (9 parameters, survey design, statistical correction), the description is complete enough for an agent to understand what it does and what it returns. It covers the methodological rationale and output diagnostics. It doesn't mention every caveat, but the schema and output schema fill the remaining gaps, making a 4 appropriate.

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 does not add explicit parameter-level semantics beyond what the schema already provides; it focuses on the statistical method rather than explaining individual parameters. The context about design effects indirectly informs parameters like estratos/conglomerados, but not enough to raise the 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 starts with 'Cruce ponderado con prueba de independencia corregida por diseno', clearly identifying the tool as a weighted cross-tabulation with a design-corrected independence test. It further specifies the Rao-Scott correction, distinguishing it from generic cross-tab or chi-square tools and from sibling tools like enaho_estimar or enaho_comparar.

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 clear context for when to use this tool: when Pearson's chi-square is inappropriate due to complex survey design (clustering), and a corrected test is needed. It explains why the correction is necessary, but does not explicitly state alternatives or exclusions, earning a 4 rather than 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds behavioral context by explaining that 'la respuesta indica a que nivel corresponde cada acierto' and that the base table covers 25 departments with optional imported tables. This goes beyond annotations without contradicting them.

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, each serving a purpose: stating the core function, providing a practical use case, and explaining the response format and data coverage. It is front-loaded with the primary purpose and contains no unnecessary 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?

For a simple read-only lookup tool with an output schema and strong annotations, the description covers essential context: the reverse search nature, the ubigeo format, and the data coverage limitation. However, it omits any mention of the 'limite' parameter behavior and does not address ambiguous or no-match cases, which keeps it from being fully complete.

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 describes 'nombre' with an example but leaves 'limite' without any description. The tool description does not explain the meaning or effect of 'limite' (e.g., that it controls the number of results). With schema coverage at only 50%, the description does not compensate for the missing parameter semantics, resulting in a clear gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Busqueda inversa: nombre de lugar a codigo de ubigeo' which is a specific verb+resource combination, clearly indicating a reverse lookup. It distinguishes from sibling tools, as no other sibling performs ubigeo lookup. The scope is clear: converting place names to codes, with the added detail about the six-digit structure.

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 statement 'Util para filtrar una region sin salir a buscar el codigo a mano' provides a clear use case. It also notes the prerequisite that provinces and districts appear only if an official table was imported, offering context. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 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?

The description goes well beyond the annotations. It discloses internal merge behavior (base selection, key type normalization, row loss counting), explains the `pasos_union` output block, and warns about interpreting low match rates. This is substantial behavioral context that the annotations (readOnlyHint, destructiveHint, idempotentHint) do not cover. No contradiction found.

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 opens with the core purpose, then explains three critical merge behaviors, then guides the user on interpreting output, and finishes with a clear caveat about microdata. Every sentence carries value and there is 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?

Given the tool's central role, its 7 parameters, and the presence of an output schema, the description is remarkably complete. It explains what is returned (name, shape, warnings), what is not returned (microdata), how to interpret the `pasos_union` block, and why certain match rates are legitimate. The sibling context is also handled by identifying this as the central merge 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 description coverage is high (86%), so the baseline is 3. The description adds meaningful context to parameters like `nivel` (applying the level's keys) and `modulos` (same-year requirement, typical combos), as well as explaining why key normalization matters. It doesn't detail every parameter, but the schema handles those well.

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 clear verb and resource: 'Une modulos aplicando las llaves del nivel pedido y guarda un parquet' (merges modules applying the keys and saves a parquet). It further distinguishes this tool from siblings by detailing its unique merge logic (choosing the most disaggregated base, normalizing key types, counting lost rows) and positioning it as 'la herramienta central'.

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 establishes when to use this tool (for merging modules) and explicitly states a non-usage: 'NO devuelve microdatos: para analisis libre abre el parquet con pandas.' This provides a clear context and a 'when not to' for microdata access, though it doesn't name specific alternative sibling tools.

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