DATASUS SIH/SUS — Brazil Hospital Admissions (AIH) MCP

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

Annotations already establish readOnly/idempotent behavior, and the description adds valuable semantics beyond them: it discloses that non-ICD-10 input returns is_csap:null with a proper error rather than false, and that notation variants like J18.1 and J181 produce the same result. This prevents serious misinterpretation.

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?

Four sentences, front-loaded with the core classification behavior, followed by notation handling, invalid-input semantics, and scope exclusion. Every sentence carries useful information and there is 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?

The tool has an output schema, so return shape is already covered. The description compensates for the remaining usage risks: invalid inputs, notation equivalence, and ICD-9 exclusion. Nothing needed for correct invocation appears to be missing.

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

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

The input schema already documents cid_codes fully with examples, so the baseline is 3. The description adds actionable extra meaning by explaining that both OMS and SIH notations are accepted, which is not evident from the schema example alone.

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 ('Classifica') and resource ('códigos CID-10'), and clarifies the result: 'Retorna o grupo CSAP correspondente se aplicável'. This clearly distinguishes it from sibling listing/getting tools like list_csap_groups or get_icsap.

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 exclusions: non-ICD-10 codes are not classified, and 6-digit ICD-9 SIH 1992–1997 codes are handled elsewhere ('não por esta ferramenta'). However, it does not name a specific sibling tool as the alternative, so the guidance is clear but not fully complete.

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

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

Annotations already cover read-only/idempotent; description adds valuable data provenance caveats (derived CID-9 list, uf from file, universe definition) that affect result interpretation. 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 dense with multiple sentences, front-loaded with purpose but long due to caveats. Each sentence adds value, but it could be more concise; still well-structured.

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

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

For a 7-parameter tool with output schema, the description covers purpose, parameter nuances, data reliability, and references notes. Missing return details are covered by output schema; complete enough for correct invocation.

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

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

Schema covers all parameters; description adds extra constraints like rate_per_10k requiring population years and universe behavior, plus early-year data limitations, enriching parameter meaning beyond 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 a comparative temporal analysis of ICSAP across UFs or CSAP groups, including calculation of trends, annual variation, and best/worst performance. It distinguishes from siblings like get_icsap or get_hospitalization_trends by focusing on ICSAP and comparison, though it doesn't explicitly name alternatives.

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 data constraints (e.g., rate_per_10k requires population years, 1992-1997 data caveats) but does not explicitly guide when to choose this tool over compare_regions or get_hospitalization_trends. Usage is implied from the purpose, but no exclusions or alternatives are named.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds a useful non-obvious caveat: in 1992–1997, the UF dimension refers to the establishment/file UF rather than residence, and it points to get_available_years.uf_basis and the notes for further detail. It does not explain ranking order or limit behavior, but the output schema reduces the need for that.

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

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

Three sentences with no filler: the first states the action, the second states the output value, and the third delivers an important temporal caveat. Everything is front-loaded and 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 read-only tool with 100% schema coverage, two enums, an output schema, and annotations, the description needs little else. It provides a clear purpose, the kind of results it generates, and the key historical data caveat, making it complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the uf/compare_by semantic changes in 1992–1997, which is not evident from the enum description alone.

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

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

The description states a specific verb and resource: it 'compara internações entre UFs ou regiões do Brasil' and clarifies that it produces rankings and identifies regional variations. This is enough to distinguish it from siblings like compare_icsap_trends, which focus on ICSAP trends rather than general hospitalization comparisons by geography.

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 intended use is implied: use it when comparing hospitalizations across UFs or regions and when rankings are desired. However, it does not explicitly state when not to use it or name sibling alternatives such as get_hospitalizations or compare_icsap_trends, so some routing decisions are left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by enumerating freshness.status values and describing what happens when status is stale, including per-year listing of revised, regenerated, removed, or new partitions. This goes well beyond the 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 core result is front-loaded in the first clause, and every later detail about freshness statuses and era-dependent fields is relevant to interpreting the returned data. However, the description is a dense single paragraph with many semicolons and parentheticals; bulleted structure would improve readability without adding length.

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

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

For a zero-parameter, read-only, idempotent metadata tool with an output schema, the description is complete: it covers year availability, freshness states, stale-partition behavior, and per-year era differences. No additional facts about authentication, rate limits, side effects, or parameters are necessary for an agent to select and invoke 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 zero parameters, so there are no parameter semantics to document; the baseline for zero-parameter tools is 4. The description correctly focuses on output semantics and does not invent or omit parameter guidance.

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 the specific resource and scope: available years in the loaded SIH-SUS data plus cube freshness relative to the healthbr-data mirror. It is clearly distinct from sibling tools like get_hospitalizations or get_icsap, which retrieve data rather than metadata. The verb 'Retorna' makes the read-only retrieval intent explicit.

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 (whenever year availability or cube freshness is needed) but gives no explicit guidance about when not to use it or which sibling alternative to prefer. There are no exclusions, preconditions, or alternative routing statements, so usage guidance is only inferred from the stated purpose.

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 readOnly/idempotent annotations by disclosing the two denominator file sources, the year-dependent age granularity constraints, and the response behavior including population_source and the warning when files are mixed. This is rich contextual behavior not derivable from the annotations or schema.

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

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

The core purpose is front-loaded, and all details about data sources and age constraints are relevant. However, the long parenthetical about the two deno minator files and pre-2000 age limits is dense and could be more cleanly structured without losing 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 10-parameter tool with an output schema and safety annotations, the description supplies the most important missing context: where denominators come from, how age filtering behaves differently across years, and what output signals are included. There are no significant gaps for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by clarifying rate_per configurability, the exact age_min/age_max constraints for pre-2000 years, and the relationship between year and denominator source. It does not need to re-explain each parameter.

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

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

The description clearly states the specific operation: 'Calcula taxas de internação por população (por 100.000 habitantes, configurável)', which distinguishes it from count-based sibling tools like get_hospitalizations. However, it does not explicitly name sibling alternatives, leaving some differentiation to inference.

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 clear context about when this tool applies: it computes population-based rates and relies on denominator files selected via get_available_years.population_years. It also clarifies age-filter limitations before 2000, but stops short of explicitly stating when-not-to-use or naming alternative 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?

As anotações já marcam readOnly/idempotent/não-destrutivo; a descrição adiciona advertências comportamentais substanciais: raça só existe de 2008 em diante, 1992–1997 usa CID-9 com semântica de cid_group/cid_revision, uf refere-se ao local do arquivo e não à residência, value é nominal e exclusion marca o universo não-CSAP. Não há contradição com as anotações.

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 descrição é densa, mas cada frase cumpre função: propósito, dimensões de agregação e depois as ressalvas históricas/dos dados. As ressalvas são compactas e essenciais, sem padding, e a frase mais importante vem no início.

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 o alto número de parâmetros e as peculiaridades históricas, a descrição cobre as ressalvas críticas, referencia get_available_years para metadados complementares e, como existe output schema, a documentação do retorno não é necessária. O agente tem o que precisa para chamar com segurança e interpretar os resultados.

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?

A cobertura do schema é 100%, então a linha de base já é forte. A descrição vai além ao explicar o comportamento nulo de race, o início da série em 1992, o significado de uf e a semântica de agrupamento por exclusion/cid_revision, o que ajuda materialmente o agente a escolher parâmetros corretos.

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?

A descrição abre com verbo e recurso específicos: 'Consulta dados de internações hospitalares do SUS com filtros flexíveis' e lista as dimensões de agregação (UF, CID, sexo, idade, raça, ano/mês). Isso distingue claramente a ferramenta dos siblings focados em taxas e tendências, posicionando-a como a consulta flexível de dados brutos.

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

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

A descrição fornece contexto rico sobre quando os dados são válidos e referencia get_available_years para metadados, mas não afirma explicitamente quando usar esta ferramenta em vez de get_hospitalization_rates ou get_hospitalization_trends. O uso é implícito (agregar contagens brutas), sem exclusões claras.

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?

Although annotations already mark this as read-only/idempotent, the description discloses important behavioral details: series start, UF semantics for 1992-1997, and how missing source dates are bucketed. It also routes to notes and get_available_years for further caveats.

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

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

Three compact sentences put the core behavior and purpose up front, then add only essential historical caveats. There is no filler or repetition of schema content.

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

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

For a complex time-series tool with an output schema, it covers the main pitfalls: date range ambiguity, UF attribution, missing dates, and where to find authoritative notes. The references to get_available_years and notes close the remaining 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?

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining how uf behaves in the 1992-1997 window and linking the monthly/annual choice to the granularity parameter.

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

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

The description uses a concrete verb-resource pair ('Retorna séries temporais de internações') and names the monthly/annual variants plus intended use ('análise de tendências e sazonalidade'). It is clear, though it does not explicitly contrast with sibling tools like get_hospitalizations or compare_icsap_trends.

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

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

It states a use case ('útil para análise de tendências e sazonalidade') and points to get_available_years, but gives no when-to-use/when-not-to-use guidance or exclusions. The usage context is implied rather than explicit.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses notable data behaviors: race is null in 1998–2007 and the filter won't reach those years; ICSAP for 1992–1997 is derived from a non-official CID-9 list, making g03/g05 non-comparable; uf is the file's UF and municipality_code is null in that period; and the default universe excludes obstetric, delivery, and long-stay admissions. This is rich behavioral context that annotations cannot convey.

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

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

The description is a single dense paragraph, but it is tightly organized: purpose first, then filters, then critical data caveats, then the universe calculation. Each sentence carries distinct information and there is no filler or repetition. It remains readable despite the complexity.

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

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

For a 10-parameter tool with historical data caveats, the description covers the major lifetime issues (race availability, ICD-9 revision change, municipality/UF basis) and the calculation universe. It points to get_available_years for additional notes, and an output schema exists so return format is not needed. Still, it could be slightly more explicit about the intended use case versus sibling tools like get_icsap_indicators, but overall it is near 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?

While the schema already describes all 10 parameters (100% coverage), the description adds semantic caveats for parameters: it specifies the meaning of `race` null periods, the `uf` file-basis in 1992–1997, municipality_code null, and the `universe` exclusions. These nuances go beyond the schema's terse descriptions, particularly for uf and municipality_code.

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 'Consulta internações por Condições Sensíveis à Atenção Primária (ICSAP)', a specific verb and resource, and enumerates the available filters. However, it does not explicitly distinguish this tool from siblings like get_icsap_indicators or get_hospitalizations, so it misses the top-tier sibling differentiation.

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

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

The description implies the tool is for querying ICSAP hospitalizations with filters, and it refers to get_available_years for data-revision caveats. It does not state explicit when-to-use vs alternatives, nor when not to use it (e.g., if the user needs indicators or trends). The guidance is mostly implicit through the tool's name and filter list.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses significant behavioral nuances: the universe default that excludes obstetric/long-stay admissions, the fact that race is null before 2008, and that in 1992–1997 the CID-9 list is derived and non-official with uf referring to the file's UF. These are not captured by annotations and are crucial for correct interpretation of results.

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

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

The description is a single dense paragraph that front-loads the main purpose and then packs caveats and specifics. It is efficient—every sentence contributes—but the structure could be improved with bullet points or shorter sentences for readability. Still, it avoids fluff and is appropriately sized for the complexity.

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

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

For a calculation tool with an output schema, the description covers all major pitfalls: data availability by year, race grouping constraints, the universe definition, and file-based uf semantics. It also references notes for further details. Nothing essential for an agent to call the tool correctly is missing.

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

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

Schema coverage is 100%, so each parameter already has a description. The description adds extra semantics for group_by (race only valid from 2008) and uf (in 1992–1997 it's the file's UF), and clarifies the universe parameter's behavior in more detail than the schema, though the schema already explains the 'csapaih' vs 'all' distinction. It enriches the parameter understanding without redundancy.

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

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

The description explicitly states the tool calculates ICSAP indicators as a percentage (ICSAP/Total×100), which is a specific verb+resource. It also provides context that these are key metrics for primary care, making the purpose unambiguous. While it doesn't name a sibling tool directly, the function is clearly distinct from raw-data retrieval tools like get_icsap.

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 on when certain groupings are valid (race only from 2008 onward) and warns about non-comparable data in 1992–1997, plus the default universe. It points to get_available_years.race_available for verification, but it does not explicitly state 'use this tool for percentages and not for raw data' or mention alternatives like compare_icsap_trends. The context is strong but 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 declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value by specifying the exact content returned (22 chapters, codes, ranges) and the mapping file for CID-9 to CID-10, helping set expectations about the data. It does not conflict with any annotation.

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: the first states the primary action and result, the second adds a relevant edge-case about older cubes. Every sentence contributes useful information, and the main purpose 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?

Given the tool's simplicity (no parameters, clear output schema), the description covers the essential usage context. The mention of the CID-9 mapping addresses a likely source of confusion for historical data. No critical information appears to be missing.

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

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

With zero parameters and 100% schema coverage, the description correctly omits parameter details. The baseline of 4 applies because there are no parameters to describe, and the description's focus on output content 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 that the tool lists the 22 ICD-10 chapters with codes and diagnostic ranges, naming the specific resource and scope. It distinguishes itself from siblings like list_csap_groups by focusing on a distinct resource, though it does not explicitly contrast with any sibling. The additional context about CID-9 mapping further clarifies its unique role.

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 contextual usage guidance by noting that 1992–1997 cubes with CID-9 diagnoses use `cid_chapter` as the equivalent ICD-10 chapter and referencing the mapping file. This implies when an agent might need this information, but it stops short of explicitly stating when to choose this tool over other list tools. No exclusions or alternative tool names are mentioned.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the fixed count of 19 groups and the ordinance reference, which is useful context but does not disclose additional traits such as default return behavior or performance. With annotations present, this is adequate but not exceptional.

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

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

Two short, focused sentences with no filler. The verb 'Lista' is front-loaded, and the description efficiently conveys the core action and output 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?

For a simple list tool with an output schema and fully documented parameters, the description is sufficient. It could add a note that this is a reference list and not an indicator tool, but the purpose is clear enough that an agent can call it correctly.

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

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

Schema coverage is 100% and both parameters (group_code, include_cid_codes) are clearly documented in the input schema. The description adds no parameter-specific meaning beyond what the schema already provides, so it 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 clearly states it lists the 19 CSAP groups per Portaria MS/SAS 221/2008, with a specific verb ('Lista') and resource ('grupos CSAP'). It distinguishes itself from siblings like list_cid_chapters by naming the exact resource type and the legal basis.

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?

There is no guidance about when to use this tool versus alternatives like get_icsap, rank_csap_groups, or list_cid_chapters. The description only states what it does, leaving the decision entirely to the agent's inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: the caveat about CID-9 derived data for 1992–1997, the non-comparability of groups g03 and g05, the nominal currency of 'value', and the default universe (csapaih) that excludes obstetric procedures, childbirth, and long-stay admissions. These are important data behaviors an agent should know.

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

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

The description is concise, with the main purpose stated in the first sentence and caveats following. It is not overly verbose and front-loads the core function. The structure is logical: purpose, capability, then data caveats. It could be slightly more streamlined, but it is appropriately sized 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?

Given the tool has 8 optional parameters, an output schema, and the annotations cover safety, the description is fairly complete. It explains the ranking criteria, the data caveats, and the default universe. It does not explicitly mention the output format (e.g., a table), but the presence of an output schema likely covers that. The description is sufficient for an agent to call the tool correctly, though it could mention potential edge cases or the direction of ranking (e.g., descending).

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 add some context, such as the meaning of the 'value' metric being nominal and the explanation of the 'universe' parameter's default behavior. However, it does not delve into other parameters like 'uf', 'sex', 'year', or 'limit' beyond what the schema already states. The added value is marginal, keeping the score at baseline.

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

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

The description states a clear verb ('Gera ranking') and resource ('dos 19 grupos CSAP'), and specifies the ranking criteria (number of hospitalizations, days, or value). It also adds an additional capability ('Identifica principais causas evitáveis'). The purpose is unambiguous and distinct from sibling tools like list_csap_groups or get_icsap, which focus on listing or retrieving data rather than ranking.

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 does not explicitly state when to use this tool versus alternatives or when not to use it. It provides context about the default universe and data caveats, but these are behavioral notes, not usage guidance. An agent might infer the use case from the name, but the description lacks explicit direction on when to prefer this over get_icsap or compare_icsap_trends.

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