This server provides MCP tools to query and analyze Brazilian public hospitalizations (SIH/SUS), focusing on ICSAP (primary-care-sensitive conditions), with data from 1992 to 2025, including rates, trends, rankings, and regional comparisons.
List reference data: CSAP groups (Portaria 221/2008), CID-10 chapters, and classify CID-10 codes as CSAP or not.
Query hospitalizations: flexible filters by UF, sex, race, age, year/month, CID chapter, CSAP status, with grouping by multiple dimensions.
Get time series: monthly or yearly hospitalization trends, including seasonality and long-term analysis.
ICSAP analytics: counts, percentages, indicators, rankings of CSAP groups by admissions, days, deaths, or value.
Compare regions/UFs: rankings and regional variation of hospitalizations or deaths, optionally restricted to CSAP.
Rates: hospitalization rates per 100k (or 10k/1k), crude or specific, using IBGE/DATASUS population data.
Comparative ICSAP trends: compare UFs or CSAP groups over time using percentage, count, or rate indicators, with linear trend analysis.
Data awareness: available years, data freshness, CID-9 vs CID-10 era differences, universe definitions (csapAIH vs all), and provenance information.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sih-br-mcp Compare ICSAP hospitalization rates between São Paulo and Rio de Janeiro in 2023."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP (Model Context Protocol) para análise das internações hospitalares do SUS (SIH/SUS, AIH reduzida) com foco em ICSAP — internações por condições sensíveis à atenção primária. Doze ferramentas sobre cubos anuais de 1992 a 2025 (causas por capítulo/grupo CID, séries mensais, ICSAP por município, taxas por 100 mil), com a proveniência da safra em cada resposta.
Este servidor é consumidor do canal público sih/cubos/ do projeto
healthbr-data:
Ministério da Saúde / DATASUS (RD<UF><AAMM>.dbc, FTP)
→ healthbr-data sih/rd/ (Parquet 1:1, manifesto com MD5 e data de download)
→ healthbr-data pipeline sih-cubos (scripts/pipeline/sih-cubos/build-aggregations.R)
→ https://data.sidneybissoli.com/sih/cubos/ (cubos + sidecar por ano + manifest.json + tables/)
→ este servidor (cache local sob demanda, SHA-256 conferido contra o manifesto)Até 08/09/2026 o builder dos cubos vivia aqui (scripts/build-aggregations.R,
rebuild-cubes.yml); desde então o produtor é o healthbr-data e este repositório
não gera nem publica cubo nenhum (CONTEXT.md, decisão 27). A receita completa está
em healthbr-data/scripts/pipeline/sih-cubos/README.md e no card
sih-cubos.
Cubos: baixados por ano, só os que a chamada pede, para
~/.cache/sih-br-mcp/cubos/ (SIH_CACHE_DIR), com o sidecar
sih_provenance_<ano>.json ao lado. SIH_CUBES_BASE_URL aponta outro canal;
SIH_CUBES_CACHE=off desliga (smoke e golden usam).
Frescor: src/freshness.ts compara o sidecar com sih/rd/manifest-summary.json
e avisa quando um cubo está atrás do espelho; quem reconstrói é o produtor
(rebuild-sih-cubes.yml, toda terça e após cada manutenção do espelho).
Tabelas de classificação (src/data/): cópias do contrato publicado em
sih/cubos/tables/; npm run tables:check confere o SHA-256 contra o manifesto
(roda no CI). Nunca edite aqui — a fonte é o produtor.
População (pop_uf.parquet, pop_uf_agregado.parquet, pop_municipios.parquet):
desde a 0.12.0 vem do mesmo canal, assinada no bloco population do manifest.json
(produtor: build-population.R + build-sih-population.yml do healthbr-data — IBGE,
Projeção 2024 por UF; DATASUS POPBR/POPSVS por município). As ferramentas de taxa
(get_hospitalization_rates, compare_icsap_trends com rate_per_10k) e
get_available_years baixam os três arquivos para o cache na primeira chamada,
com SHA-256 conferido; uma pasta de dados que já tenha pop_uf.parquet tem
precedência (fixture, build local). A proveniência da população responde com o
built_at do manifesto.
Related MCP server: cid10-br-mcp
Pacote no npm: sih-br-mcp (Node 22+).
Ele não embarca dado nenhum — cubos, tabelas e população vêm do canal na primeira
chamada e ficam no cache local.
npx -y sih-br-mcp # stdioConfiguração num cliente MCP (Claude Desktop, Claude Code):
{ "mcpServers": { "sih": { "command": "npx", "args": ["-y", "sih-br-mcp"] } } }A partir do código-fonte:
npm install
npm run build
node dist/index.js # stdioVariáveis: SIH_DATA_DIR (pasta com cubos já prontos, em vez do cache),
SIH_CACHE_DIR, SIH_CUBES_BASE_URL, SIH_CUBES_CACHE=off,
SIH_FRESHNESS_CHECK=off.
As mesmas 12 ferramentas por HTTP, para conectores remotos (claude.ai):
npm run start:http # http://localhost:8080/mcp (GET /healthz para sondar)PORT e SIH_HTTP_HOST além das variáveis acima. Sem sessão: cada request
cria servidor e transporte novos, então qualquer instância atende qualquer
chamada. Em produção roda num Cloudflare Container (Dockerfile, população
pré-baixada na imagem) atrás do Worker de borda em worker/, que cuida de
domínio, rate limit, autenticação opcional e medição — desenho e custos em
docs/plan-004-servidor-remoto.md.
npm ci && npm run build
npm run smoke:stdio # superfície das ferramentas × baselines/surface-stdio.json
npm run smoke:http # mesma superfície e chamadas pelo transporte HTTP (dist/http.js)
npm run golden:tools # 12 ferramentas byte a byte × baselines/golden-tools.json (fixture 2023/RR)
npm run freshness:selftest # frescor offline sobre um trecho versionado do manifesto
npm run cache:selftest # cache local (download + SHA-256) contra um canal falso
npm run tables:check # tabelas de src/data × manifesto do canalO CI (.github/workflows/ci.yml) roda tudo isso em Node 22 e 24. A fixture
tests/fixtures/sih/ é uma cópia real dos cubos de 2023/RR gerados pelo builder
(hoje no healthbr-data) — é o que torna medível qualquer bump.
CONTEXT.md — decisões arquiteturais numeradas (a 27 é a migração do produtor; a 29, o servidor remoto).
docs/analise-001 (janela de competências), analise-002 (era CID-9, 1992–1997),
analise-003 (lista ICSAP em CID-9 derivada), plan-002 (DuckDB Node Neo),
plan-003 (rebuild automático, hoje no healthbr-data), plan-004 (servidor remoto
HTTPS para o claude.ai), tool-specifications.md.
MIT (LICENSE). Os dados são do Ministério da Saúde / DATASUS; a redistribuição em
Parquet e os cubos derivados são do healthbr-data (CC-BY-4.0).
Classifica um ou mais códigos CID-10 como CSAP ou não. Retorna o grupo CSAP correspondente se aplicável. Só CID-10: os códigos CID-9 de 6 dígitos do SIH de 1992–1997 são classificados no build pela lista derivada (src/data/csap-groups-cid9.json), não por esta ferramenta.
| Name | Required | Description | Default |
|---|---|---|---|
| cid_codes | Yes | Códigos CID-10 para classificar (ex: ['J18', 'A09', 'K35']) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool only handles CID-10 and returns the CSAP group if applicable, and notes that CID-9 codes are handled elsewhere. However, it does not disclose whether the operation is read-only, how invalid or malformed codes are handled, or any error/edge-case behavior. Given it's a classification tool, this is likely read-only, but the absence of explicit safety or error information leaves gaps.
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 and front-loads the core purpose. The second sentence, while informative, is a bit long and includes a file path, but it still efficiently conveys the CID-9 exclusion. No wasted words, and the key message is clear without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain the return structure. It says 'Retorna o grupo CSAP correspondente se aplicável', which gives some idea but not the exact format (e.g., object with code and group, or just group). It also does not mention handling of empty arrays, invalid codes, or whether it accepts multiple codes (implied by 'um ou mais' but not detailed). For a simple tool it is adequate, but more detail on return structure would make it 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 100% – the parameter cid_codes is clearly described as 'Códigos CID-10 para classificar (ex: [\'J18\', \'A09\', \'K35\'])'. The description adds the return behavior (group if applicable) and the CID-9 exclusion, but these are more about tool behavior than parameter meaning. It does not add extra syntax or format details beyond the schema, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Classifica) and resource (códigos CID-10) and clearly defines the outcome (CSAP or not, with group if applicable). It distinguishes itself from sibling tools like list_csap_groups and rank_csap_groups by focusing on individual code classification, and explicitly excludes CID-9 codes, leaving no ambiguity about its 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 explicitly states when NOT to use this tool: for CID-9 codes from SIH 1992–1997, which are handled by a derived list. This gives clear exclusion criteria. It does not explicitly say 'use for CID-10' but that is implied by the exclusion and the tool's name, so usage context is clear, though it lacks explicit alternatives for CID-10 classification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Análise temporal comparativa de ICSAP entre UFs ou grupos CSAP. Calcula tendências, variação anual e identifica melhores/piores desempenhos. Para percentage e count valem todos os anos do SIH (desde 1992); rate_per_10k exige população e aceita só os anos de get_available_years.population_years. Em 1992–1997 a ICSAP vem de lista CID-9 DERIVADA e não oficial (g03 e g05 não comparáveis com 1998+) e uf é a UF do arquivo — ver as notes. Percentual no universo do pacote R csapAIH por padrão (universe): fora do numerador e do denominador as internações por procedimento obstétrico, parto e longa permanência.
| Name | Required | Description | Default |
|---|---|---|---|
| end_year | Yes | Ano final | |
| universe | No | Universo do % ICSAP: 'csapaih' (padrão) tira do numerador e do denominador as internações por procedimento obstétrico, com diagnóstico de parto (O80-O84) e as AIH de longa permanência, como o pacote R csapAIH (Nedel); 'all' conta todas as internações. | |
| indicator | No | Indicador: percentage (% ICSAP), count (número), rate_per_10k (taxa) | |
| compare_by | No | Comparar por UF ou grupo CSAP | |
| start_year | Yes | Ano inicial | |
| compare_values | No | Valores específicos para comparar (UFs ou grupos CSAP) | |
| include_trend_line | No | Incluir análise de tendência linear (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It transparently explains the tool's calculations (trends, variation, best/worst) and important caveats about ICD-9 derived data for 1992-1997 and the 'uf' definition. It does not detail any side effects or data source specifics beyond those notes, but for a read-only analysis tool this is adequate.
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 is focused and necessary, covering purpose, parameter restrictions, and data caveats. It is slightly verbose but not redundant. It front-loads the purpose and then elaborates on edge cases, which is appropriate for a tool with complex data limitations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, but the description states what the tool calculates (trends, annual variation, best/worst) which is sufficient for expected outputs. It mentions 'ver as notes' for additional details, which is a minor gap but not critical. Overall, it gives enough context for an agent to decide whether to invoke 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 covers all 7 parameters with descriptions (100% coverage). The description adds meaningful context for 'universe' (what is excluded from numerator/denominator) and 'indicator' (restrictions on rate_per_10k). It does not redefine parameters already well-described in the schema, but the additional caveats improve understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: comparative temporal analysis of ICSAP between UFs or CSAP groups, including trend calculation, annual variation, and identification of best/worst performers. This specific verb-noun-resource structure distinguishes it from 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?
The description provides usage guidance for different indicators (percentage/count vs rate_per_10k, which requires population and only certain years) and explains the universe parameter's default behavior. It mentions get_available_years for valid years, but does not explicitly contrast with sibling tools like get_icsap_indicators or compare_regions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compara internações entre UFs ou regiões do Brasil. Gera rankings e identifica variações regionais. Em 1992–1997 uf é a UF do arquivo (estabelecimento), não de residência — ver get_available_years.uf_basis e as notes.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Anos para consultar | |
| limit | No | Número de resultados (default: 10) | |
| metric | No | Métrica para ranking (default: n) | |
| is_csap | No | Filtrar apenas CSAP | |
| compare_by | No | Comparar por UF ou região (default: uf) | |
| cid_chapter | No | Capítulo CID-10 específico |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Sem annotations, a descrição carrega o peso de revelar comportamento. Ela menciona o detalhe importante sobre a base do parâmetro 'uf' nos anos 1992-1997, o que é um aviso comportamental relevante. No entanto, não informa se a operação é somente leitura, não descreve formato de retorno nem possíveis limitações de dados. Há transparência parcial, mas não completa.
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 é curta (duas frases), front-loaded com o propósito principal e inclui apenas o caveat essencial sobre o significado de 'uf'. Não há redundância nem detalhes desnecessários. Cada palavra contribui para o entendimento.
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?
Para uma ferramenta com 6 parâmetros, sem output schema e sem annotations, a descrição fornece a finalidade e uma advertência crucial. Ela menciona que gera rankings, dando uma ideia do tipo de retorno. No entanto, não descreve a estrutura exata do resultado nem outros detalhes de saída, o que seria útil. A referência a get_available_years ajuda, mas ainda há espaço para mais especificidade.
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?
O schema cobre 100% dos parâmetros com descrições, dando baseline 3. A descrição adiciona valor além do schema ao explicar que o significado de 'uf' varia por ano, o que afeta diretamente o parâmetro compare_by. Isso é informação semântica útil que não está no schema. Portanto, nota 4 é apropriada.
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 afirma claramente que a ferramenta compara internações entre UFs ou regiões do Brasil, gera rankings e identifica variações regionais. Isso é específico e distingue de outras ferramentas de comparação, embora não mencione explicitamente alternativas como compare_icsap_trends. A menção ao significado especial de 'uf' em certos anos adiciona precisão ao propósito.
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 indica quando usar (para comparar internações e gerar rankings) e referencia get_available_years para esclarecimentos, mas não fornece diretrizes explícitas sobre quando NÃO usar esta ferramenta em favor de outras, como compare_icsap_trends ou get_hospitalization_rates. Há contexto implícito de uso, mas falta orientação explícita sobre alternativas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retorna os anos disponíveis nos dados do SIH-SUS carregados e o frescor dos cubos em relação ao espelho healthbr-data (freshness.status: current, stale, unknown, pending ou disabled; quando stale, lista por ano as partições reeditadas pelo MS, regeneradas, retiradas ou novas na janela). Por ano, o que muda entre as eras do SIH: race_available (raça/cor só de 2008), cid_revision (9 = CID-9 de 6 dígitos em 1992–1997, 10 = CID-10; 1997 tem as duas), icsap_list_revision (cid9-derivada, não oficial, em 1992–1997), uf_basis (arquivo em 1992–1997, residencia de 1998), municipality_available, currency e records_date_imputed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the freshness status values and the per-year attribute differences, providing rich context. It does not specify the exact return structure (list vs object), but the content is thoroughly described.
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 with extensive technical detail. While it covers necessary information for a metadata tool, it is not front-loaded or easily scannable, and could be restructured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description explains the main output: available years, freshness, and per-year differences. It omits the exact response format, but for a listing tool this is likely inferable. It is otherwise complete for the tool's purpose.
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 an empty schema, so there is nothing to explain. The baseline score of 4 applies, and the description appropriately does not add unnecessary 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 clearly states it returns available years in the loaded SIH-SUS data, plus freshness status and per-year differences. This distinct purpose differentiates it from sibling tools focused on analytics or list operations, and uses a specific verb ('Retorna') and resource ('anos disponíveis').
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?
No explicit guidance on when to use this tool versus alternatives. However, the nature of the tool (listing available years) implies it is a prerequisite for filtering by year in other queries. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calcula taxas de internação por população (por 100.000 habitantes, configurável). Denominador lido de dois arquivos, informados em get_available_years.population_years: projeções do IBGE por idade simples de 2000 em diante (pop_uf.parquet) e, de 1991 a 1999, população por faixa etária quinquenal somada dos municípios (pop_uf_agregado.parquet) — antes de 2000 o recorte por idade só vale nos limites das faixas (age_min múltiplo de 5, age_max terminado em 4 ou 9, ou 80+). A resposta diz qual arquivo serviu a cada ano (population_source) e avisa quando mistura os dois.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | UFs para filtrar | |
| sex | No | Filtrar por sexo | |
| year | No | Anos para calcular | |
| age_max | No | Idade máxima | |
| age_min | No | Idade mínima | |
| is_csap | No | Filtrar apenas CSAP | |
| group_by | No | Dimensões para agrupamento | |
| rate_per | No | Taxa por X habitantes (default: 100000) | |
| rate_type | No | Tipo de taxa: crude (bruta) ou specific (específica por filtro) | |
| cid_chapter | No | Capítulos CID-10 (1-22) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details: the denominator is sourced from two different files depending on the year, and age filtering before 2000 only works within specific ranges. It also states that the response indicates the source file per year and warns when mixing, providing full transparency about the tool's behavior and potential pitfalls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that packs a lot of information, but it remains coherent and readable. It is not overly verbose, but the complexity of the caveat makes it slightly long. The structure is logical, moving from the main function to the denominator logic and finally to the response details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description mentions what the response includes (population_source and a warning), which helps an agent understand the expected output. Combined with the parameter descriptions, this provides a fairly complete picture for using the tool. Some details like the exact format of the warning are omitted, but overall it is sufficiently complete for a complex 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 already has 100% coverage with descriptions for all 10 parameters. The description adds meaningful clarification about the age_min and age_max parameters (the pre-2000 caveat), enhancing understanding beyond the schema. It also clarifies the rate_per default and rate_type, though these are already in the schema. The added context justifies a score above the baseline of 3.
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: calculating hospitalization rates per population (taxas de internação por população). It specifies the denominator source and the age filter caveat, making the intent unambiguous. While it doesn't explicitly differentiate from siblings, the core function is distinct and well-defined.
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 context on the calculation logic (denominator from two files) and the age filter limitation, but does not explicitly state when to use this tool versus alternatives like get_hospitalizations or get_hospitalization_trends. The guidance is implicit rather than explicit, leaving some ambiguity for an agent deciding between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consulta dados de internações hospitalares do SUS com filtros flexíveis. Permite agregar por múltiplas dimensões (UF, CID, sexo, idade, raça, ano/mês). Raça/cor só existe de 2008 em diante: em 1998–2007 race é nulo (ver get_available_years.race_available). Série desde 1992: em 1992–1997 o diagnóstico é CID-9 decodificado por tabela (cid_group = categoria de 3 dígitos, cid_chapter = capítulo CID-10 equivalente; agrupar por cid_revision separa 9 e 10 — 1997 tem os dois), uf é a UF do ARQUIVO (estabelecimento), não de residência, e value é nominal na moeda da época — ver get_available_years (uf_basis, currency) e as notes da resposta. exclusion (agrupável) marca as internações fora do universo do % ICSAP do csapAIH (procedimento_obstetrico, parto, longa_permanencia; nula = dentro).
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | Lista de UFs (ex: ['SP', 'RJ']). Se omitido, todas. | |
| sex | No | Filtrar por sexo | |
| race | No | Raça/cor (branca, preta, parda, amarela, indigena, ignorado). Só existe de 2008 em diante: em 1998–2007 race é nulo e o filtro não alcança esses anos. | |
| year | No | Anos para consultar (ex: [2023, 2024]); série de 1992 em diante | |
| limit | No | Limitar número de resultados | |
| month | No | Meses (1-12). Se omitido, todos. | |
| age_max | No | Idade máxima em anos | |
| age_min | No | Idade mínima em anos | |
| is_csap | No | Filtrar apenas CSAP (true) ou não-CSAP (false) | |
| group_by | No | Dimensões para agrupamento | |
| cid_chapter | No | Capítulos CID-10 (1-22). Se omitido, todos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It uses the verb 'Consulta' (query), which implies a read-only operation, and does not mention any side effects or data modifications. However, it does not explicitly state that no changes are made or address potential rate limits or other behavioral aspects.
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 packs many essential caveats. While it is long, the information is necessary and not redundant. It is structured logically, starting with the core purpose and then detailing specific data limitations, making it efficient for the complexity it covers.
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 (11 parameters, many historical nuances), the description is complete. It covers all parameters, explains edge cases (race, CID revisions, UF interpretation), and directs users to get_available_years for further details. No output schema is present, but that is not required for 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 schema provides 100% coverage of parameter descriptions, but the description adds significant meaning beyond the schema. It clarifies important nuances: race only exists from 2008 onward, CID-9 vs CID-10 distinction, UF refers to establishment not residence, and value is nominal in the local currency. These details are critical for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: querying SUS hospital admission data with flexible filters and aggregation across multiple dimensions. It specifies the resource (hospitalizations) and the main capabilities, making it distinct from other tools like trends or comparisons.
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 the sibling tools. It references get_available_years for more details but does not clarify the selection criteria among the many related functions (e.g., when to use get_hospitalization_trends instead). 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.
Retorna séries temporais de internações (mensal ou anual). Útil para análise de tendências e sazonalidade. Série desde 1992; em 1992–1997 uf é a UF do arquivo (estabelecimento) e as internações sem data na fonte (1992-01..04 e 1993-01) entram no mês de faturamento — ver get_available_years e as notes.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | UFs para filtrar | |
| year_end | Yes | Ano final | |
| year_start | Yes | Ano inicial | |
| cid_chapter | No | Capítulo CID-10 específico | |
| granularity | No | Granularidade temporal (default: yearly) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden. It discloses specific data quirks (UF interpretation in 1992–1997 and attribution of missing dates to billing month) and references get_available_years and notes for further details, which is above average but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three sentences to convey purpose, key caveats, and references. It is well organized and free of redundancy, though it could slightly benefit from explicit output description.
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 does not detail the output structure (e.g., fields in the returned series), but it points to get_available_years and notes, which may fill that gap. Given the absence of an output schema, this is a minor shortfall but 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 schema already provides descriptions for all 5 parameters (100% coverage), and the description adds valuable context, particularly the special meaning of `uf` for early years and the default granularity. This enriches understanding beyond the schema 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 clearly states the tool returns time series of hospitalizations ('séries temporais de internações') with optional monthly/yearly granularity, effectively distinguishing it from sibling tools like get_hospitalizations (raw records) or get_hospitalization_rates.
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 mentions usefulness for trend and seasonality analysis, and provides important caveats about pre-1998 data. However, it does not explicitly contrast with alternative tools, though the time-series focus is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consulta internações por Condições Sensíveis à Atenção Primária (ICSAP). Permite filtros por grupo CSAP, UF, município, sexo, idade e raça. Raça/cor só existe de 2008 em diante: em 1998–2007 race é nulo (ver get_available_years.race_available). Série desde 1992: em 1992–1997 a ICSAP vem de lista CID-9 DERIVADA e não oficial (g03 e g05 não comparáveis com 1998+), uf é a UF do arquivo e municipality_code é nulo — ver get_available_years (icsap_list_revision, uf_basis) e as notes. Percentual no universo do pacote R csapAIH por padrão (universe): fora do numerador e do denominador as internações por procedimento obstétrico, parto e longa permanência.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | UFs para filtrar | |
| sex | No | Filtrar por sexo | |
| race | No | Raça/cor (branca, preta, parda, amarela, indigena, ignorado). Só existe de 2008 em diante: em 1998–2007 race é nulo e o filtro não alcança esses anos. | |
| year | No | Anos para consultar | |
| age_max | No | Idade máxima | |
| age_min | No | Idade mínima | |
| group_by | No | Dimensões para agrupamento | |
| universe | No | Universo do % ICSAP: 'csapaih' (padrão) tira do numerador e do denominador as internações por procedimento obstétrico, com diagnóstico de parto (O80-O84) e as AIH de longa permanência, como o pacote R csapAIH (Nedel); 'all' conta todas as internações. | |
| csap_group | No | Grupos CSAP (ex: ['g01', 'g05']) | |
| municipality_code | No | Código IBGE do município (6 dígitos) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description exposes important behavioral nuances: race is absent for 1998–2007, municipality_code is null for 1992–1997, and the default universe for percentage calculation excludes obstetric and long-stay hospitalizations. These details go beyond the basic schema and help set expectations, though the return format is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that packs many caveats (race availability, series revision, universe definition) without clear structure or bullet points. While the information is relevant, it could be more organized for quick agent consumption.
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 hints at output by mentioning percentages but does not explain the return format, grouping behavior, or whether the result is aggregated by group_by. Without an output schema, this missing information leaves the agent to infer the 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?
Every parameter has a Portuguese description that adds context beyond the schema's types and enums. For example, the race parameter explains the temporal limitation, and the universe parameter clarifies the default behavior. This goes beyond the baseline schema coverage, providing meaningful semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries hospitalizations for CSAP (ambulatory care sensitive conditions) and lists filter options. However, it does not explicitly distinguish this from similar sibling tools like get_hospitalizations or get_icsap_indicators, which slightly reduces clarity.
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 provide guidance on when to use this tool versus the many sibling tools. It references get_available_years for additional details on data limitations, but does not explain scenarios where this tool is preferred over alternatives such as get_icsap_indicators 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.
Calcula indicadores de ICSAP: percentual (ICSAP/Total×100). Métricas-chave para avaliar a Atenção Primária. Agrupar por raça só faz sentido de 2008 em diante: em 1998–2007 race é nulo (ver get_available_years.race_available). Em 1992–1997 a ICSAP vem de lista CID-9 DERIVADA e não oficial (g03 e g05 não comparáveis com 1998+) e uf é a UF do arquivo — ver as notes. Percentual no universo do pacote R csapAIH por padrão (universe): fora do numerador e do denominador as internações por procedimento obstétrico, parto e longa permanência.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | UFs para calcular | |
| sex | No | Filtrar por sexo | |
| year | No | Anos para calcular | |
| age_max | No | Idade máxima | |
| age_min | No | Idade mínima | |
| group_by | No | Dimensões para agrupamento | |
| universe | No | Universo do % ICSAP: 'csapaih' (padrão) tira do numerador e do denominador as internações por procedimento obstétrico, com diagnóstico de parto (O80-O84) e as AIH de longa permanência, como o pacote R csapAIH (Nedel); 'all' conta todas as internações. | |
| municipality_code | No | Código IBGE do município |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that the default universe excludes obstetric procedures, childbirth, and long-stay hospitalizations, and notes that UF in 1992-1997 refers to the file's UF. It also warns about comparability issues across years. These are critical behavioral 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 dense but well-organized. It leads with the core calculation, then flows into year-specific caveats and the universe default. Each sentence adds value; no fluff. It's 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?
For a tool with 8 parameters, no output schema, and no annotations, the description covers the most critical aspects: the calculation formula, default behavior, and critical data caveats. It also references get_available_years for further details. However, it doesn't describe the output format or how to interpret results, which could be a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful context beyond the schema. It explains the 'universe' parameter's default and what it excludes, and warns about 'race' parameter validity only from 2008. This is genuinely useful guidance that the schema alone doesn't provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact purpose: 'Calcula indicadores de ICSAP: percentual (ICSAP/Total×100)' with a clear verb and resource. It distinguishes itself from siblings like get_icsap (which likely returns raw counts) by focusing on the percentage indicator, and mentions key metrics for primary care evaluation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage constraints: grouping by race only from 2008 onward, year-specific caveats (1992-1997 non-official CID-9 list), and default universe behavior. References get_available_years for race availability. While it doesn't explicitly name alternatives, it gives enough context to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista os 22 capítulos da CID-10 com seus códigos e faixas de diagnóstico. Os cubos de 1992–1997 (diagnóstico em CID-9) trazem cid_chapter como o capítulo CID-10 equivalente (mapa por categoria em src/data/cid9-chapters.json).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for conveying behavior. It states what the tool lists but does not explicitly mention that it is a read-only operation or its output format. Since it is a straightforward listing, the behavior is largely implied, but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that convey the core functionality and additional mapping context without unnecessary detail. It is well-structured and easy to parse.
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 no-parameter, no-output-schema tool, the description provides sufficient context about what the tool returns (chapter list with codes and ranges) and why it is relevant (mapping for older cubes). It could optionally mention the output format, but given the simplicity, 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 tool has no parameters, and the description does not discuss any. Since the baseline for zero parameters is 4, and the description adds no conflicting or additional parameter information, this score 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 their codes and diagnostic ranges, which is a specific and unambiguous purpose. It also provides additional context about mapping older CID-9 cubes to CID-10 chapters, distinguishing it from simple lookup tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for referencing ICD-10 chapters or mapping CID-9 data, but does not explicitly state when to use this tool versus the sibling tools. It mentions the mapping file but does not provide direct instructions like 'use this to get chapter names' or 'use this for CID-9 to CID-10 mapping'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista os 19 grupos de Condições Sensíveis à Atenção Primária (CSAP) conforme Portaria MS/SAS 221/2008. Retorna código, nome e códigos CID-10 de cada grupo.
| Name | Required | Description | Default |
|---|---|---|---|
| group_code | No | Código do grupo específico (ex: 'g01'). Se omitido, retorna todos. | |
| include_cid_codes | No | Se true, inclui lista de códigos CID-10 (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It accurately describes the read-only nature (listing data) and the return format, but does not mention potential side effects, authentication requirements, or any behaviors beyond returning the list. For a simple read operation, this is adequate but not thorough.
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, clear sentence with no redundant words. It is well-structured and directly states the function and output.
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 operation, the description sufficiently covers the purpose, source ordinance, and return fields. It lacks explicit mention of ordering, filtering, or potential edge cases, but these are not critical for a straightforward 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?
Schema coverage is 100% with both parameters described in detail (e.g., group_code shows example 'g01' and behavior when omitted). The description itself does not add extra semantics beyond the schema, so the baseline of 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's purpose: listing the 19 CSAP groups according to a specific ordinance, and specifies the returned fields (code, name, CID-10 codes). It is distinct from sibling tools that retrieve indicators or classify conditions.
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 over alternatives (e.g., get_icsap or classify_as_csap). It provides factual information about the output but lacks guidance on selection criteria or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gera ranking dos 19 grupos CSAP por número de internações, dias de internação ou valor. Identifica principais causas evitáveis. Em 1992–1997 a ICSAP vem de lista CID-9 DERIVADA e não oficial (g03 e g05 não comparáveis com 1998+) e value é nominal na moeda da época — ver as notes. Universo do pacote R csapAIH por padrão (universe): fora as internações por procedimento obstétrico, parto e longa permanência.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | UFs para filtrar | |
| sex | No | Filtrar por sexo | |
| year | No | Anos para consultar | |
| limit | No | Número de grupos no ranking (default: 19) | |
| metric | No | Métrica para ranking (default: n) | |
| age_max | No | Idade máxima | |
| age_min | No | Idade mínima | |
| universe | No | Universo do % ICSAP: 'csapaih' (padrão) tira do numerador e do denominador as internações por procedimento obstétrico, com diagnóstico de parto (O80-O84) e as AIH de longa permanência, como o pacote R csapAIH (Nedel); 'all' conta todas as internações. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses important data quirks: the 1992–1997 ICSAP uses a derived non-official ICD-9 list, g03 and g05 are not comparable with 1998+, and `value` is nominal in the currency of the time. It also explains the default universe exclusion. It does not mention sorting order or tie-breaking, but the disclosed caveats are substantial and valuable.
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 primary purpose, then presents caveats in a compact manner. It is not overly verbose and each sentence adds value. The structure is logical, starting with the main action and then detailing edge cases and defaults.
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 8 parameters, no output schema, and moderate complexity, the description covers the core purpose, key metrics, historical caveats, and universe behavior. It lacks an explicit description of the output format (e.g., ordering, ties, or the 'notes' field it references), but the schema covers limits and filters. Overall, it is sufficiently complete for an agent to call correctly, with minor 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for two parameters: it clarifies that `value` is nominal currency (affecting interpretation) and explains the `universe` default and what it excludes. This goes beyond the schema's brief descriptions, warranting a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Gera ranking'), the resource ('19 grupos CSAP'), and the metrics used (number of hospitalizations, days, or value). It also adds that it identifies main avoidable causes, distinguishing it from raw data retrieval tools like get_hospitalizations. The purpose is unambiguous and differentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about the default universe and historical caveats, but it does not explicitly state when to use this tool versus alternatives such as list_csap_groups or get_icsap. It implies usage for ranking, but no exclusions or routing guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.12.1classify_as_csapcompare_icsap_trendscompare_regionsget_available_yearsget_hospitalization_ratesget_hospitalization_trendsget_hospitalizationsget_icsapget_icsap_indicatorslist_cid_chapterslist_csap_groupsrank_csap_groupsScored across 12 tools
Each tool has a clearly distinct purpose, covering data retrieval, rankings, lists, trends, rates, indicators, classification, and metadata. Even overlapping concepts like ICSAP and hospitalizations are separated into specific functions (e.g., get_icsap vs. get_hospitalizations), with detailed descriptions preventing confusion.
Names follow a verb_noun pattern with verbs like get, list, rank, compare, and classify. Minor inconsistencies exist in number usage (e.g., get_hospitalizations vs. get_hospitalization_trends), but overall the pattern is predictable and readable.
With 12 tools, the set is well-scoped for a domain-specific health data server—not too sparse to cover essential operations, and not bloated with redundant functions. Each tool serves a distinct analytical or informational purpose.
The tool surface comprehensively covers the domain: metadata discovery, raw data queries, trend analysis, rate computation, comparative analytics, classification, and indicator calculation. It includes both general hospitalizations and ICSAP-specific views, with no obvious missing operations for typical use cases.
Conselho Federal de Medicina: Estabelecimentos de Saúde, official-source lookup. Platform-hosted, pa
Pay-per-call US healthcare data: hospital financials, prices, quality, exclusions, wages.
WHO GHO MCP — World Health Organization Global Health Observatory (free, no auth)
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).