cemis-directorio

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

Beyond the readOnly/not-destructive annotations, the description discloses meaningful behavior: the unusual empty-list-with-explanatory-note case for sectors with no assigned companies, the default and maximum limit behavior, the total_encontrado field, and the summary-card output. 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 core purpose and uses a compact bulleted list for the five parameters. Every sentence adds necessary detail; there is no filler or repetition of schema defaults beyond useful behavioral context like the default limit.

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 five optional combinable filters, no output schema, and no parameter descriptions in the schema, the description is complete enough to guide invocation: it covers filter sources, edge-case returns, limits, and output granularity. It also names ficha_empresa() for the full profile, closing the main follow-up question.

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

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

Schema description coverage is 0%, so the description fully carries parameter meaning. It explains each parameter's source domain, matching semantics (e.g. 'coincidencia parcial'), edge cases, defaults, and the special None behavior for verificada. This is exemplary compensation for the absent schema 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 'Busca empresas del directorio CEMIS combinando filtros con AND', giving a specific verb, resource, and combination semantics. It also distinguishes itself from ficha_empresa() by explicitly stating it returns a summary card, not the full profile, so an agent can tell tools apart.

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

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

The description gives clear context: all filters are optional, combined with AND, and valid values for sector/provincia come from listar_sectores() and listar_provincias(). It explicitly directs full-profile needs to ficha_empresa(), though it does not explicitly contrast with sibling search tools like empresas_por_oportunidad.

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 important behavioral details beyond the annotations: results are ordered with hand-curated companies first and automatically matched ones second, and automatic matching is based on keyword sector matching with the opportunity text. This gives the agent a clear expectation of result composition and ordering.

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

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

The description is a single, well-structured sentence that front-loads the input and main action, then uses a colon and 'primero...luego' to convey ordering. Every phrase adds value without unnecessary 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 one-parameter, read-only tool with no output schema, the description provides adequate completeness: it defines the input, the output domain, the result ordering, and the matching mechanism. No critical information is missing for selecting and invoking this tool.

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

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

The schema has zero description coverage for the 'oportunidad' parameter, but the description fully compensates by specifying that it accepts an id (e.g., 'opp-001') or an exact/approximate title. This is essential for correct invocation and far exceeds schema-only information.

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

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

The description states a specific verb ('devuelve'), a specific resource ('empresas del directorio CEMIS'), and a clear input criterion ('un id o título de una oportunidad'). It also distinguishes itself from sibling tools like 'buscar_empresas' and 'oportunidades_por_sector' by focusing on opportunity-to-company mapping.

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 clearly implies when to use this tool: when you have an opportunity id or title and want related companies. However, it does not explicitly mention alternatives or when not to use it, so it lacks a direct exclusion 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?

Las anotaciones ya cubren readOnly, idempotente y no destructivo. La descripción añade valor al revelar que limite recorta el array 'empresas' pero que 'total' siempre refleja el conteo real, y que el default es 50. No contradice las anotaciones.

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?

Tres bloques con propósito claro: qué devuelve, en qué se diferencia de buscar_empresas, y significado del parámetro. No hay relleno ni repetición del schema, y cada oración aporta información útil.

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

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

Aunque no hay output schema, la descripción menciona los campos clave ('empresas' y 'total') y explica el comportamiento de limite. Para una tool de solo lectura con un único parámetro, es suficiente para invocarla correctamente.

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?

Con cobertura de esquema 0%, la descripción compensa completamente: define limite como máximo de empresas en 'empresas', su default 50, y aclara que total no se trunca. Es la única propiedad y queda totalmente aclarada.

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 abre con verbo claro ('Devuelve') y recurso específico (empresas cubanas del sector TICs y economía digital), e identifica el dataset del hub público. Además distingue explícitamente esta tool de buscar_empresas al señalar el cruce con el Eje 21 y las oportunidades de negocio.

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?

Nombra explícitamente a buscar_empresas(sector='TICs y economía digital') y explica la diferencia clave: el cruce regulatorio con reformas y oportunidades. No formula un 'cuándo no usar' directo, pero el contraste es claro y suficiente para orientar la selección.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior, lowering the bar. The description adds useful behavioral context beyond that: it accepts exact/approximate names and returns approximate suggestions when no match is found. There is no contradiction with 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?

A single dense sentence with no filler: the main purpose is front-loaded, followed by the identification options, the contents of the response, and the fallback behavior. Every clause adds relevant 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?

There is no output schema, so the description must explain what the tool returns; it does so by listing the structured profile, related opportunities, and transformations, plus not-found suggestions. This is sufficient for a one-parameter read-only tool, though 'perfil estructurado completo' remains somewhat vague about the exact response structure.

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 has one required parameter, 'slug', with zero description coverage. The description compensates by explaining that the slug identifies the company and that an exact or approximate name can be supplied if the slug is unknown. It adds real semantic meaning without providing format examples.

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

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

States a specific action and resource: returns the complete structured company profile from the CEMIS directory, identified by slug or approximate name. It also includes related business opportunities and transformations, which clearly differentiates it from sibling search-oriented tools.

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

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

The description gives clear context for when to use this tool: to retrieve a company's full profile with related opportunities and reforms, and it explains that a slug is preferred but approximate name matching is allowed. It does not explicitly mention alternative sibling tools or exclusions, 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?

The description goes far beyond the readOnly/idempotent annotations: it details type-of-company versus sector matching, the 'alcance': 'transversal' behavior, explicit non-application messages instead of empty arrays, accent normalization behavior, and the inclusion of oportunidades_directas and regulatory implementation state. No contradiction with 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 purpose is front-loaded and the bulleted structure makes a complex set of behaviors scannable. Some internal code references and the dated normalization footnote add length, but they carry meaningful behavioral detail rather than filler.

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

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

Given the absence of an output schema, the description explains response variants, the no-empty-array guarantee, and the included fields reasonably well. It does not spell out the exact response envelope or the not-found case, but for a one-parameter tool it is largely 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 only provides a bare 'transformacion' string with no description. The tool description compensates fully by explaining that it accepts the exact or approximate number/title of a 2026 reform and even illustrates fuzzy matching with the 'turis'/'turística' normalization fix.

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

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

The first sentence states a clear action ('devuelve su impacto sobre el directorio CEMIS') and a specific input ('número o título ... de una transformación/reforma de 2026'). It clearly differs from siblings like buscar_empresas, but it never names or directly contrasts them.

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: this is the main tool for reform-impact queries and explains how impact criteria vary by reform type. It does not explicitly list exclusions or alternative sibling tools, but the intended usage is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that provinces are 'derivadas de los datos reales del directorio', implying the list is dynamic and reflects actual data, which is useful context beyond annotations. However, it does not describe return format or other behavioral details, so 3 is appropriate.

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, each earning its place. The first sentence states the purpose and data source; the second gives direct usage guidance. No unnecessary repetition or fluff, and the key information is front-loaded.

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

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

For a zero-parameter, read-only list tool with annotations covering safety, the description is complete. It explains what it returns and when to call it. No output schema exists, but the return type (list of provinces) is implied, and no additional information is critical for an agent to use this 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 0 parameters, so there is nothing to document. Per the rubric, a zero-parameter tool gets a baseline of 4. The description appropriately focuses on the tool's purpose rather than parameters.

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

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

The description uses a specific verb ('Devuelve') and resource ('provincias válidas para filtrar empresas'), clearly stating the tool's purpose. It also distinguishes itself from siblings by focusing on provinces as opposed to other list tools like 'listar_sectores', and links its role to 'buscar_empresas'.

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

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

The description explicitly states when to use it: 'Usalo antes de llamar a buscar_empresas() con un filtro de provincia.' This provides clear context for usage, though it does not mention when not to use it or alternative tools explicitly. The intended workflow is clear, so it 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the data source (real directory data vs. web form) but does not describe return format or other behavioral details. This is adequate but not rich, matching the baseline for annotation-covered read-only tools.

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 concise sentences with no filler. The primary purpose is front-loaded, followed by the data-source nuance and usage directive. Every sentence earns its place.

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

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

For a 0-parameter tool with no output schema, the description tells the agent what it returns, why the data is authoritative, and when to use it. The context is complete and sufficient for correct invocation.

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

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

The tool has zero parameters and the schema coverage is 100%, so the description does not need to explain parameter meaning. The baseline of 4 applies because the absence of parameters makes semantic explanation unnecessary. The description correctly focuses on the output rather than inputs.

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

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

The description clearly states that the tool returns the valid sectors for filtering companies, with a specific verb and resource. It also differentiates the data source ('datos reales del directorio') from the possibly outdated web form. This distinguishes it from sibling tools like buscar_empresas or oportunidades_por_sector.

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 before calling buscar_empresas() or oportunidades_por_sector() with a sector filter. This gives clear when-to-use guidance and names the relevant alternatives. No further exclusions are needed for a simple 0-parameter lookup.

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 (read-only, idempotent, non-destructive), the description discloses ordering behavior and the important edge case where sectors without assigned companies yield an empty 'oportunidades_curadas' while automatic matches can still appear. This adds meaningful 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 information-dense but structured as one long run-on sentence with nested parentheticals. All content is relevant, but it would be easier to parse if split into clearer sentences or bullets.

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 a single parameter and no output schema, the description covers the input source, result ordering, and the empty-case behavior. It is sufficiently complete for an agent to invoke the tool correctly and interpret the response shape.

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 only defines 'sector' as a string with 0% description coverage. The tool description compensates by explaining that the sector should come from listar_sectores() or from the reform-matching taxonomy, giving the agent concrete guidance on valid values.

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: given a sector, it returns relevant business opportunities. It also specifies the result structure—curated opportunities first, then automatic keyword matches—which distinguishes it from sibling tools like empresas_por_oportunidad and buscar_empresas.

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 concrete guidance on valid inputs: use listar_sectores() or a sector from the reform-matching taxonomy via impacto_de_reforma(). It implies when to use the tool, though it does not explicitly say when not to use it or name alternatives.

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