sih-br-mcp
Summary: sih-br-mcp answers aggregate questions about Brazil's SUS hospital admissions (SIH/SUS, 1992–2025) directly inside an AI assistant — no TabNet, no .dbc downloads, no SQL — with provenance and citation in every answer.
Query hospitalizations (
get_hospitalizations) with flexible filters — UF, year, month, sex, age range, race, CID-10 chapter, CSAP status — and aggregate by year, month, UF, CID chapter/revision/group, sex, age, race, ICSAP group or exclusion; returns counts, length of stay, SUS-paid value and deaths.Get time series (
get_hospitalization_trends) of admissions and deaths, monthly or yearly, filtered by UF and CID chapter.Compare regions (
compare_regions) ranking UFs or regions by admissions or deaths, with mortality rates.Analyze ICSAP (ambulatory care sensitive conditions) via
get_icsap(by CSAP group, municipality, sex, age, race),get_icsap_indicators(ICSAP % with selectable universe: csapAIH or all),rank_csap_groups(rank the 19 groups by admissions/days/value/deaths with concentration metrics) andcompare_icsap_trends(annual series by UF or CSAP group with linear trend and best/worst performer, indicator = percentage, count or rate per 10k).Compute rates (
get_hospitalization_rates): crude or specific admission rates per 1k/10k/100k inhabitants by UF, sex and year, using IBGE/DATASUS population denominators (with per-year population source noted).Classify diagnoses (
classify_as_csap): check whether ICD-10 codes (OMSJ18.1or SIHJ181notation) are sensitive conditions and which CSAP group they fall in.Explore the classification reference:
list_csap_groups(19 CSAP groups, Portaria MS/SAS 221/2008, optional CID-10 code lists) andlist_cid_chapters(22 ICD-10 chapters with ranges and names).Check data availability and freshness (
get_available_years): years present, per-year caveats (CID-9 vs CID-10 era, race/cor only from 2008, municipality availability, UF-of-establishment vs residence, currency of the year, CSAP universe), population coverage, cube channel and staleness vs the healthbr-data mirror.Run it wherever needed: npm package
npx -y sih-br-mcpover stdio, or the same 12 tools over remote Streamable HTTP for claude.ai connectors, with on-demand Parquet cube caching and SHA-256/manifest verification.Every response is auditable: tool answers carry a provenance block (source, URL, vintage, retrieval timestamp, citation, license) plus attribution URLs, and warnings (
notes) qualifying the numbers.Not for: individual AIH records, variables outside the cubes (procedure, CNES, secondary diagnosis), or other DATASUS systems (SIM, SINASC, SIA, SINAN) — those need microdatasus, PySUS or the Parquet mirror.
Click on "Deploy 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-mcpCompare 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.
DATASUS SIH/SUS — MCP Server de internações hospitalares (AIH) do Brasil, 1992–2025
Servidor MCP (Model Context Protocol) que responde perguntas sobre as internações
hospitalares do SUS — o SIH/SUS do DATASUS, AIH reduzida — dentro do assistente de
IA, sem TabNet, sem baixar .dbc do FTP e sem escrever SQL. Doze ferramentas sobre
34 anos (1992 a 2025, 420.103.883 internações): causas por capítulo e grupo da
CID-10 (CID-9 antes de 1998), séries mensais, ICSAP — internações por condições
sensíveis à atenção primária, lista brasileira — e taxas brutas, específicas ou
padronizadas por idade, por UF e por município. Cada estrato traz internações, dias de
permanência, valor pago pelo SUS e óbitos, com a proveniência da safra e a citação
da fonte em cada resposta.
In English. MCP server for Brazilian hospital admissions (DATASUS SIH/SUS, "AIH" records), 1992–2025: causes by ICD-10 chapter and group (ICD-9 before 1998), monthly series, ambulatory care sensitive conditions (ICSAP/ACSC, Brazilian list) and crude, age-specific or age-standardized rates by state and municipality — answered inside Claude, ChatGPT or any MCP client, with provenance and a citation in every answer. No FTP download, no DBC decoding, no SQL:
npx -y sih-br-mcp.
Perguntas que ele responde
Em linguagem comum, no cliente MCP: quem escolhe a ferramenta e os parâmetros é o assistente.
"Quantas internações por pneumonia houve no Espírito Santo em 2024, por faixa de idade?" (
get_hospitalizations)"A taxa de ICSAP de Roraima caiu entre 2010 e 2023?" (
get_icsap_indicators)"Compare a internação por 100 mil habitantes entre Norte e Sudeste em 2023, padronizada por idade." (
get_hospitalization_rates,compare_regions)"Quais condições sensíveis à atenção primária mais internam no meu município?" (
rank_csap_groups)"Série mensal de internações por dengue desde 1998." (
get_hospitalization_trends)"J18.9 é condição sensível à atenção primária?" (
classify_as_csap)
Related MCP server: mcp-sinim
Comparação com as alternativas
Quem trabalha com SIH/SUS em R ou Python já tem ferramentas consolidadas, e este
servidor não substitui nenhuma delas — ele ocupa um lugar diferente da cadeia:
responde a pergunta agregada no ponto onde ela é feita, dentro do assistente, sem
ETL e sem download de microdado. Detalhe, exemplos lado a lado e os números medidos
em docs/comparativo-alternativas.md.
Ferramenta | O que faz | Quando preferir |
sih-br-mcp (este) | Responde agregados de 34 anos direto no assistente de IA, com ICSAP, taxas padronizadas e proveniência por resposta | A pergunta é agregada (UF, município, ano, mês, CID, idade, sexo, raça, ICSAP) e a resposta tem de ser auditável |
microdatasus 3.0.0 (R, CRAN) | Baixa e processa microdados do DATASUS (SIH, SIM, SINASC, SIA, CNES, SINAN): trata o DBC e rotula as variáveis | Você precisa do registro individual da AIH, de variáveis fora dos cubos ou de outro sistema do DATASUS |
PySUS 2.11.2 (Python) | Ferramentas para os dados públicos de saúde brasileiros; lê DBC/DBF do FTP do DATASUS | Seu pipeline é Python e você quer ETL próprio sobre o microdado |
read.dbc 1.2.0 (R, CRAN) | Lê e descomprime o formato | Você já tem os arquivos e só precisa abri-los |
csapAIH (R, GitHub) | Classifica AIH em ICSAP pela lista brasileira (é a referência que este servidor confere) | A classificação é sobre o seu microdado, em R |
brpop 0.7.0 (R, CRAN) | Estimativas populacionais brasileiras por município, UF, sexo e faixa | Você calcula as próprias taxas e quer o denominador em R |
healthbR 0.4.0 (R, CRAN) | Irmão em R deste servidor: acessa dados públicos de saúde do Brasil pelo mesmo espelho Parquet | Você está em R e quer o dado numa |
Não use este servidor quando a pergunta exigir o registro individual da AIH,
variáveis que os cubos não carregam (procedimento realizado, CNES do estabelecimento,
caráter de atendimento, diagnóstico secundário) ou outro sistema do DATASUS (SIM,
SINASC, SIA, SINAN) — nesses casos o caminho é microdatasus, PySUS ou o espelho
Parquet do healthbr-data. O que os
cubos carregam por estrato está em
docs/tool-specifications.md: internações, dias de
permanência, valor pago (R$) e óbitos, por ano, mês, UF, município, capítulo e grupo
CID, sexo, idade, raça/cor e grupo ICSAP.
De onde vêm os dados
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 sidecarsih_provenance_<ano>.jsonao lado.SIH_CUBES_BASE_URLaponta outro canal;SIH_CUBES_CACHE=offdesliga (smoke e golden usam).Rede: toda ida ao canal passa por
src/upstream.ts(fetch comum do portfólio,@sbissoli/mcp-upstream, desde a 1.1.0): User-Agent, 15 s por tentativa até os cabeçalhos, 2 retries em 429/5xx/rede com backoff, corpo em stream sob o prazo do arquivo; a política foi medida contra o canal (55 MB em 1,2 s) e está documentada no cabeçalho do módulo. O bloco de proveniência de cada resposta trazretrieval(contrato v1.1): quantas idas, tentativas e anomalias a chamada custou ao canal —nullquando a resposta veio do disco.Frescor:
src/freshness.tscompara o sidecar comsih/rd/manifest-summary.jsone 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).Pré-agregados (blocos
icsap_summary, desde a 0.14.0, ecausas_summary, desde a 0.15.0): atalhos DERIVADOS dos cubos publicados, no mesmo canal. O da ICSAP é um resumo de 276 KB mais os estratos por ano; o de causas é o grão A (sih_causas_resumo.parquet, 569 KB com os 34 anos:year × uf × cid_chapter × cid_revision × is_csap × exclusioncom internações, dias, valor e óbitos) mais o grão B por ano, que acrescenta sexo, faixa etária quinquenal e raça. Uma chamada que cabe no grão responde sem baixar cubo nenhum — "internações e gasto por ano desde 1992" custa 569 KB em vez de 1,25 GB. O roteamento é conservador: o que não cabe (mês, categoria CID de 3 dígitos, grupo CSAP, idade fora das faixas quinquenais) cai no cubo e sai exato. Cada ano só usa o pré-agregado se oderived_fromdo manifesto ainda bater com o SHA-256 do cubo publicado; rebuild sem nova derivação devolve aquele ano ao caminho lento, nunca ao número errado.Tabelas de classificação (
src/data/): cópias do contrato publicado emsih/cubos/tables/;npm run tables:checkconfere 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 blocopopulationdomanifest.json(produtor:build-population.R+build-sih-population.ymldo healthbr-data — IBGE, Projeção 2024 por UF; DATASUS POPBR/POPSVS por município). As ferramentas de taxa (get_hospitalization_rates,compare_icsap_trendscomrate_per_10k) eget_available_yearsbaixam os três arquivos para o cache na primeira chamada, com SHA-256 conferido; uma pasta de dados que já tenhapop_uf.parquettem precedência (fixture, build local). A proveniência da população responde com obuilt_atdo manifesto.
Uso
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.
Servidor remoto (Streamable HTTP)
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.
Verificação
npm ci && npm run build
npm test # vitest: decisão de rota (puro) + envelope e outputSchema das 12 (caso cheio e caso magro)
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 canal
npm run equiv:summary # pré-agregados da ICSAP × caminho clássico, byte a byte
npm run equiv:series # roteamento para o cubo leve de séries
npm run equiv:causas # pré-agregados de causas (grão A e B) × cubo, byte a byteO 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.
A divisão de trabalho entre as duas famílias: os scripts em scripts/*.mjs
pinam VALORES (mudou um número, o baseline acusa); a suíte de tests/*.test.ts
afirma INVARIANTES (qual cubo responde a pergunta; toda resposta sai com
proveniência, com o texto igual à estrutura e obedecendo ao outputSchema que
o tools/list publica — validado com o mesmo validador do SDK), e por isso
republicar um cubo não a move. Cada ferramenta tem ali um caso CHEIO e um caso
MAGRO — a resposta com os campos opcionais ausentes, que o golden, sempre com
fixture cheia, não alcança — e o caminho de erro-mole ("ano sem dado") também
é validado. Os esquemas de saída estão em src/output-schemas.ts, escritos à
mão a partir das formas medidas, como os de entrada.
Documentação
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),plan-005(série pré-agregada da ICSAP),plan-006(cubo de causas pré-agregado),tool-specifications.md.
Licença
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).
Available Tools
12 toolsclassify_as_csapClassificar CID-10 como CSAPARead-onlyIdempotentInspect
Classifica um ou mais códigos CID-10 como CSAP ou não. Retorna o grupo CSAP correspondente se aplicável. Aceita as duas notações do mesmo código — J18.1 (OMS) e J181 (SIH) — com a mesma resposta. Código que NÃO é CID-10 não é classificado: volta com is_csap: null e error próprio, nunca false (que afirmaria que a condição existe e não é sensí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']) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | Só quando houver código não classificado: quantos foram e para onde olhar |
| summary | No | |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| classifications | No | Uma entrada por código, na ordem informada |
TDQS
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.
compare_icsap_trendsTendências comparativas de ICSAPARead-onlyIdempotentInspect
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) |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Sempre vazio: só aparece no caminho de erro-mole do funil |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| period | No | |
| series | No | Pontos em ordem cronológica |
| trends | No | Tendência por valor comparado; só com `include_trend_line` e ao menos dois anos — ausente quando desligada |
| summary | No | |
| indicator | No | Indicador das séries |
| compare_by | No | Eixo comparado: uf, csap_group ou total (sem eixo) |
| provenance | Yes | Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| population_years | No | Cobertura populacional; só no erro-mole de `rate_per_10k` fora do intervalo |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
compare_regionsComparação entre UFs e regiõesARead-onlyIdempotentInspect
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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Sempre vazio: só aparece no caminho de erro-mole do funil |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| metric | No | Métrica que ordena o ranking |
| ranking | No | Ranking em ordem decrescente da métrica |
| compare_by | No | Eixo da comparação (hoje ambos agrupam por UF) |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| total_locations | No | Quantas localidades no ranking |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
get_available_yearsAnos disponíveis e frescor dos cubosARead-onlyIdempotentInspect
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 | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| note | No | Aviso sobre o que `years` significa |
| error | No | Falha ao listar os anos |
| years | No | Anos com cubos Parquet presentes localmente |
| currency | No | Moeda de `value` — chave é o ano (string) |
| uf_basis | No | Base do eixo `uf` — chave é o ano (string) |
| freshness | No | Frescor dos cubos locais frente ao espelho healthbr-data |
| data_range | No | Intervalo dos anos locais |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| years_cid9 | No | Anos em que o cubo usa CID-9 (1992–1997) |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| cid_revision | No | Internações por revisão da CID — chave é o ano (string) |
| csap_universe | No | Universo do % ICSAP — chave é o ano (string) |
| cubes_channel | No | Canal público dos cubos e cache local |
| race_available | No | Raça/cor disponível — chave é o ano (string) |
| icsap_available | No | ICSAP disponível — chave é o ano (string) |
| population_years | No | Cobertura dos arquivos de população por UF: o que as ferramentas de taxa aceitam |
| years_uf_arquivo | No | Anos em que `uf` é a do estabelecimento (1992–1997) |
| years_without_race | No | Anos sem raça/cor (1998–2007) |
| icsap_list_revision | No | Lista ICSAP por revisão da CID — chave é o ano (string) |
| records_date_imputed | No | Datas imputadas — chave é o ano (string) |
| municipality_available | No | Município disponível — chave é o ano (string) |
TDQS
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.
get_hospitalization_ratesTaxas de internação por populaçãoARead-onlyIdempotentInspect
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) |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Um estrato por linha (vazio quando não há internação no recorte) |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| summary | No | |
| metadata | No | |
| truncated | No | Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro |
| provenance | Yes | Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| population_years | No | Cobertura dos arquivos de população por UF: o que as ferramentas de taxa aceitam |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
get_hospitalizationsInternações do SUS com filtrosARead-onlyIdempotentInspect
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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Linhas agrupadas (vazio no caminho de erro-mole) |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| summary | No | Totais do recorte inteiro (não do trecho devolvido, quando truncado) |
| truncated | No | Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| filters_applied | No | Os argumentos recebidos, ecoados |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
get_hospitalization_trendsSéries temporais de internaçõesARead-onlyIdempotentInspect
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) |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Sempre vazio: só aparece no caminho de erro-mole do funil |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| period | No | Intervalo pedido |
| series | No | Um ponto por ano ou por mês, em ordem cronológica |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| granularity | No | Grão da série |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
get_icsapInternações por condições sensíveis (ICSAP)ARead-onlyIdempotentInspect
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) |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Linhas agrupadas (vazio no caminho de erro-mole) |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| summary | No | Totais do recorte inteiro, calculados sem agrupamento |
| truncated | No | Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro |
| provenance | Yes | Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| filters_applied | No | Os argumentos recebidos, ecoados |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
get_icsap_indicatorsIndicadores de ICSAPARead-onlyIdempotentInspect
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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Um estrato por linha (vazio no caminho de erro-mole) |
| note | No | Fórmula do indicador — ou, no caminho de erro-mole, como obter o dado |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| truncated | No | Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro |
| provenance | Yes | Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
| indicators_calculated | No | Indicadores presentes nas linhas (icsap_percentage) |
TDQS
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.
list_cid_chaptersCapítulos da CID-10ARead-onlyIdempotentInspect
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 | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| chapters | No | Os capítulos, na ordem da CID |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| total_chapters | No | Número de capítulos (22) |
TDQS
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.
list_csap_groupsGrupos CSAP (Portaria 221/2008)ARead-onlyIdempotentInspect
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) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | Grupo CSAP não encontrado |
| group | No | O grupo pedido por `group_code` |
| groups | No | Os 19 grupos, na ordem da Portaria |
| source | No | Norma que define a lista (Portaria MS/SAS 221/2008) |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| total_groups | No | Número de grupos na lista (19) |
TDQS
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.
rank_csap_groupsRanking dos grupos CSAPARead-onlyIdempotentInspect
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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | Sempre vazio: só aparece no caminho de erro-mole do funil |
| note | No | Como obter o dado (por exemplo, consultar get_available_years) |
| error | No | Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta) |
| notes | No | Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento |
| metric | No | Métrica que ordena |
| ranking | No | Ranking em ordem decrescente da métrica |
| provenance | Yes | Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) |
| total_groups | No | Quantos grupos no ranking |
| concentration | No | |
| published_years | No | Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado |
| available_sih_years | No | Anos com dados SIH atendíveis por este servidor |
| years_not_available | No | Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos |
TDQS
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v1.0.1- Changed
compare_icsap_trends1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
compare_regions1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
get_hospitalization_rates1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
get_hospitalization_trends1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
get_hospitalizations1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
get_icsap1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
get_icsap_indicators1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
- Changed
rank_csap_groups1 field changed- added
Output schema / properties / published_yearsAdded value: +{ + "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado", + "items": { + "type": "number" + }, + "type": "array" +}
12 tool updates
v0.17.0- Changed
classify_as_csap1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "classifications", + "summary" + ] + } + ], + "description": "Cada código CID-10 informado classificado como sensível (com o grupo) ou não; `is_csap` é null no código que não é CID-10, que não recebe classificação", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "classifications": { + "description": "Uma entrada por código, na ordem informada", + "items": { + "additionalProperties": false, + "properties": { + "cid": { + "description": "Código como foi informado", + "type": "string" + }, + "csap_group": { + "description": "Grupo CSAP g01–g19; null quando não é sensível ou não foi classificado", + "type": [ + "string", + "null" + ] + }, + "csap_name": { + "description": "Nome do grupo; null quando não é sensível ou não foi classificado", + "type": [ + "string", + "null" + ] + }, + "error": { + "description": "Só nas entradas não classificadas: por que o código não é CID-10", + "type": "string" + }, + "is_csap": { + "description": "true quando o código cai em algum grupo CSAP; false quando é CID-10 e não cai; null quando não é um código CID-10 (não classificado — veja `error` da entrada)", + "type": [ + "boolean", + "null" + ] + } + }, + "required": [ + "cid", + "is_csap", + "csap_group", + "csap_name" + ], + "type": "object" + }, + "type": "array" + }, + "error": { + "description": "Só quando houver código não classificado: quantos foram e para onde olhar", + "type": "string" + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "summary": { + "additionalProperties": false, + "properties": { + "csap": { + "description": "Quantos são sensíveis", + "type": "number" + }, + "non_csap": { + "description": "Quantos são CID-10 e não são sensíveis (não inclui os não classificados)", + "type": "number" + }, + "not_classified": { + "description": "Só quando houver: quantos não são CID-10", + "type": "number" + }, + "total": { + "description": "Códigos informados", + "type": "number" + } + }, + "required": [ + "total", + "csap", + "non_csap" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
compare_icsap_trends1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "indicator", + "period", + "compare_by", + "series", + "notes", + "summary" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Séries anuais do indicador ICSAP por UF ou grupo CSAP, com tendência linear e melhor/pior desempenho; `error` quando o intervalo está fora da cobertura", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "compare_by": { + "description": "Eixo comparado: uf, csap_group ou total (sem eixo)", + "type": "string" + }, + "data": { + "description": "Sempre vazio: só aparece no caminho de erro-mole do funil", + "items": {}, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "indicator": { + "description": "Indicador das séries", + "enum": [ + "percentage", + "count", + "rate_per_10k" + ] + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "period": { + "additionalProperties": false, + "properties": { + "end": { + "description": "Ano final pedido", + "type": "number" + }, + "start": { + "description": "Ano inicial pedido", + "type": "number" + } + }, + "required": [ + "start", + "end" + ], + "type": "object" + }, + "population_years": { + "additionalProperties": false, + "description": "Cobertura populacional; só no erro-mole de `rate_per_10k` fora do intervalo", + "properties": { + "first_year": { + "description": "Primeiro ano com população", + "type": "number" + }, + "last_year": { + "description": "Último ano com população", + "type": "number" + } + }, + "required": [ + "first_year", + "last_year" + ], + "type": "object" + }, + "provenance": { + "description": "Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem", + "items": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "type": "array" + }, + "series": { + "description": "Pontos em ordem cronológica", + "items": { + "additionalProperties": { + "description": "Valor do indicador para esta UF, grupo ou `total`", + "type": "number" + }, + "description": "Um ponto por ano: `year` mais uma chave por valor comparado (UF, grupo ou `total`) com o indicador", + "properties": { + "year": { + "description": "Ano", + "type": "number" + } + }, + "required": [ + "year" + ], + "type": "object" + }, + "type": "array" + }, + "summary": { + "additionalProperties": false, + "properties": { + "best_performer": { + "description": "Valor comparado com a melhor evolução; só com mais de uma tendência", + "type": "string" + }, + "note": { + "description": "Como ler o indicador; só para `percentage`", + "type": "string" + }, + "worst_performer": { + "description": "Valor comparado com a pior evolução; só com mais de uma tendência", + "type": "string" + } + }, + "required": [], + "type": "object" + }, + "trends": { + "additionalProperties": { + "additionalProperties": false, + "properties": { + "avg_annual_change": { + "description": "Variação média anual", + "type": "number" + }, + "change_pct": { + "description": "Variação relativa entre as pontas, %", + "type": "number" + }, + "direction": { + "description": "Sentido da tendência", + "enum": [ + "increasing", + "decreasing", + "stable" + ] + }, + "end_value": { + "description": "Valor no último ano", + "type": "number" + }, + "slope": { + "description": "Inclinação da regressão linear (indicador por ano)", + "type": "number" + }, + "start_value": { + "description": "Valor no primeiro ano", + "type": "number" + } + }, + "required": [ + "slope", + "direction", + "avg_annual_change", + "start_value", + "end_value", + "change_pct" + ], + "type": "object" + }, + "description": "Tendência por valor comparado; só com `include_trend_line` e ao menos dois anos — ausente quando desligada", + "type": "object" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
compare_regions1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "compare_by", + "metric", + "ranking", + "total_locations" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Ranking de UFs por internações ou óbitos; `error` quando nenhum ano pedido tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "compare_by": { + "description": "Eixo da comparação (hoje ambos agrupam por UF)", + "enum": [ + "uf", + "region" + ] + }, + "data": { + "description": "Sempre vazio: só aparece no caminho de erro-mole do funil", + "items": {}, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "metric": { + "description": "Métrica que ordena o ranking", + "enum": [ + "n", + "deaths" + ] + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "ranking": { + "description": "Ranking em ordem decrescente da métrica", + "items": { + "additionalProperties": false, + "properties": { + "deaths": { + "description": "Óbitos", + "type": "number" + }, + "mortality_rate": { + "description": "Óbitos / internações × 100, duas casas", + "type": "number" + }, + "n_hospitalizations": { + "description": "Internações", + "type": "number" + }, + "rank": { + "description": "Posição, 1 = maior", + "type": "number" + }, + "uf": { + "description": "UF", + "type": "string" + } + }, + "required": [ + "rank", + "uf", + "n_hospitalizations", + "deaths", + "mortality_rate" + ], + "type": "object" + }, + "type": "array" + }, + "total_locations": { + "description": "Quantas localidades no ranking", + "type": "number" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
get_available_years1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "years", + "data_range", + "note", + "race_available", + "years_without_race", + "cid_revision", + "years_cid9", + "icsap_available", + "icsap_list_revision", + "uf_basis", + "years_uf_arquivo", + "municipality_available", + "currency", + "records_date_imputed", + "csap_universe", + "population_years", + "cubes_channel", + "freshness" + ] + }, + { + "required": [ + "error", + "years" + ] + } + ], + "description": "Anos com cubo local, o que cada ano carrega (revisão da CID, raça/cor, município, moeda, universo ICSAP), cobertura da população, canal de cubos e frescor", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "cid_revision": { + "additionalProperties": { + "additionalProperties": { + "description": "Internações naquela revisão; null quando o sidecar não traz o total", + "type": [ + "number", + "null" + ] + }, + "description": "Revisão da CID (\"9\" ou \"10\") → internações", + "type": "object" + }, + "description": "Internações por revisão da CID — chave é o ano (string)", + "type": "object" + }, + "csap_universe": { + "additionalProperties": { + "additionalProperties": false, + "description": "Universo do % ICSAP como o csapAIH; null em cubo anterior ao builder 2.6.0", + "properties": { + "excluded": { + "additionalProperties": { + "description": "Internações fora do universo por este motivo", + "type": "number" + }, + "description": "Motivo de exclusão → internações", + "type": "object" + }, + "method": { + "description": "Método (csapAIH)", + "type": "string" + }, + "records_in_universe": { + "description": "Internações dentro do universo", + "type": [ + "number", + "null" + ] + } + }, + "required": [ + "method", + "records_in_universe", + "excluded" + ], + "type": [ + "object", + "null" + ] + }, + "description": "Universo do % ICSAP — chave é o ano (string)", + "type": "object" + }, + "cubes_channel": { + "additionalProperties": false, + "description": "Canal público dos cubos e cache local", + "properties": { + "base_url": { + "description": "URL do canal público de cubos", + "type": "string" + }, + "cache_dir": { + "description": "Pasta do cache local; null quando desligado", + "type": [ + "string", + "null" + ] + }, + "enabled": { + "description": "false quando o cache de cubos está desligado", + "type": "boolean" + }, + "manifest_generated_at": { + "description": "Quando o manifesto foi gerado; null sem manifesto", + "type": [ + "string", + "null" + ] + }, + "manifest_source": { + "description": "De onde veio o manifesto", + "enum": [ + "remote", + "disk", + "none", + "disabled" + ] + }, + "note": { + "description": "Como o cache baixa os anos pedidos", + "type": "string" + }, + "published_years": { + "description": "Anos publicados no manifesto do canal", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "enabled", + "base_url", + "published_years", + "cache_dir", + "manifest_source" + ], + "type": "object" + }, + "currency": { + "additionalProperties": { + "description": "Moeda de `value` por competência; null quando o sidecar não informa", + "items": { + "additionalProperties": false, + "properties": { + "code": { + "description": "Código ISO 4217 (BRE, BRR, BRL)", + "type": "string" + }, + "from": { + "description": "Primeira competência (AAAA-MM)", + "type": "string" + }, + "name": { + "description": "Nome da moeda", + "type": "string" + }, + "symbol": { + "description": "Símbolo (Cr$, CR$, R$)", + "type": "string" + }, + "to": { + "description": "Última competência (AAAA-MM)", + "type": "string" + } + }, + "required": [ + "from", + "to", + "code", + "symbol", + "name" + ], + "type": "object" + }, + "type": [ + "array", + "null" + ] + }, + "description": "Moeda de `value` — chave é o ano (string)", + "type": "object" + }, + "data_range": { + "additionalProperties": false, + "description": "Intervalo dos anos locais", + "properties": { + "first_year": { + "description": "Primeiro ano local; ausente quando não há cubo", + "type": "number" + }, + "last_year": { + "description": "Último ano local; ausente quando não há cubo", + "type": "number" + }, + "total_years": { + "description": "Quantos anos", + "type": "number" + } + }, + "required": [ + "total_years" + ], + "type": "object" + }, + "error": { + "description": "Falha ao listar os anos", + "type": "string" + }, + "freshness": { + "additionalProperties": false, + "description": "Frescor dos cubos locais frente ao espelho healthbr-data", + "properties": { + "checked_at": { + "description": "Instante (UTC) da última checagem; null se nunca terminou", + "type": [ + "string", + "null" + ] + }, + "cubes": { + "description": "Cubos atrasados frente ao espelho", + "items": { + "additionalProperties": false, + "properties": { + "behind": { + "description": "true quando alguma lista acima tem item", + "type": "boolean" + }, + "cube_year": { + "description": "Ano do cubo", + "type": "number" + }, + "new_in_window": { + "description": "Competências publicadas depois do build", + "items": { + "type": "string" + }, + "type": "array" + }, + "reedited": { + "description": "Partições cujo .dbc de origem mudou (reedição do MS)", + "items": { + "type": "string" + }, + "type": "array" + }, + "removed": { + "description": "Partições que saíram do manifesto", + "items": { + "type": "string" + }, + "type": "array" + }, + "reprocessed": { + "description": "Partições regeneradas pelo espelho", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "cube_year", + "reedited", + "reprocessed", + "removed", + "new_in_window", + "behind" + ], + "type": "object" + }, + "type": "array" + }, + "error": { + "description": "Erro da checagem; null quando não houve", + "type": [ + "string", + "null" + ] + }, + "manifest_last_updated_local": { + "description": "Manifesto com que os cubos foram gerados", + "type": [ + "string", + "null" + ] + }, + "manifest_last_updated_remote": { + "description": "Manifesto público lido agora", + "type": [ + "string", + "null" + ] + }, + "manifest_url": { + "description": "URL do manifesto do espelho", + "type": [ + "string", + "null" + ] + }, + "method": { + "description": "Como checou: sonda parcial ou manifesto inteiro", + "enum": [ + "range", + "full", + null + ] + }, + "status": { + "description": "Frescor dos cubos frente ao espelho", + "enum": [ + "disabled", + "pending", + "current", + "stale", + "unknown" + ] + } + }, + "required": [ + "status", + "checked_at", + "method", + "manifest_url", + "manifest_last_updated_local", + "manifest_last_updated_remote", + "cubes", + "error" + ], + "type": "object" + }, + "icsap_available": { + "additionalProperties": { + "description": "true quando o cubo tem a marcação ICSAP", + "type": "boolean" + }, + "description": "ICSAP disponível — chave é o ano (string)", + "type": "object" + }, + "icsap_list_revision": { + "additionalProperties": { + "additionalProperties": { + "description": "Lista usada (portaria-221-2008 ou cid9-derivada)", + "type": "string" + }, + "description": "Revisão → lista", + "type": "object" + }, + "description": "Lista ICSAP por revisão da CID — chave é o ano (string)", + "type": "object" + }, + "municipality_available": { + "additionalProperties": { + "description": "false quando `municipality_code` é nulo em todas as linhas", + "type": "boolean" + }, + "description": "Município disponível — chave é o ano (string)", + "type": "object" + }, + "note": { + "description": "Aviso sobre o que `years` significa", + "type": "string" + }, + "population_years": { + "additionalProperties": false, + "description": "Cobertura dos arquivos de população por UF: o que as ferramentas de taxa aceitam", + "properties": { + "aggregated": { + "additionalProperties": false, + "description": "pop_uf_agregado.parquet — faixa etária quinquenal por UF e sexo (1991–1999)", + "properties": { + "age": { + "description": "Grão etário do arquivo", + "type": "string" + }, + "age_groups": { + "description": "Faixas etárias quinquenais (só no arquivo agregado)", + "items": { + "type": "string" + }, + "type": "array" + }, + "first_year": { + "description": "Primeiro ano coberto", + "type": "number" + }, + "last_year": { + "description": "Último ano coberto", + "type": "number" + }, + "source": { + "description": "Arquivo parquet que serve o intervalo", + "type": "string" + } + }, + "required": [ + "first_year", + "last_year", + "source", + "age" + ], + "type": [ + "object", + "null" + ] + }, + "detailed": { + "additionalProperties": false, + "description": "pop_uf.parquet — idade simples por UF e sexo (projeções IBGE, 2000+)", + "properties": { + "age": { + "description": "Grão etário do arquivo", + "type": "string" + }, + "age_groups": { + "description": "Faixas etárias quinquenais (só no arquivo agregado)", + "items": { + "type": "string" + }, + "type": "array" + }, + "first_year": { + "description": "Primeiro ano coberto", + "type": "number" + }, + "last_year": { + "description": "Último ano coberto", + "type": "number" + }, + "source": { + "description": "Arquivo parquet que serve o intervalo", + "type": "string" + } + }, + "required": [ + "first_year", + "last_year", + "source", + "age" + ], + "type": [ + "object", + "null" + ] + }, + "first_year": { + "description": "Primeiro ano com população por UF (união dos dois arquivos)", + "type": "number" + }, + "last_year": { + "description": "Último ano com população por UF", + "type": "number" + } + }, + "required": [ + "first_year", + "last_year", + "detailed", + "aggregated" + ], + "type": [ + "object", + "null" + ] + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "race_available": { + "additionalProperties": { + "description": "true quando o cubo tem raça/cor", + "type": "boolean" + }, + "description": "Raça/cor disponível — chave é o ano (string)", + "type": "object" + }, + "records_date_imputed": { + "additionalProperties": { + "description": "Internações que entraram com data imputada", + "type": "number" + }, + "description": "Datas imputadas — chave é o ano (string)", + "type": "object" + }, + "uf_basis": { + "additionalProperties": { + "description": "Base do eixo `uf`", + "enum": [ + "residencia", + "arquivo" + ] + }, + "description": "Base do eixo `uf` — chave é o ano (string)", + "type": "object" + }, + "years": { + "description": "Anos com cubos Parquet presentes localmente", + "items": { + "type": "number" + }, + "type": "array" + }, + "years_cid9": { + "description": "Anos em que o cubo usa CID-9 (1992–1997)", + "items": { + "type": "number" + }, + "type": "array" + }, + "years_uf_arquivo": { + "description": "Anos em que `uf` é a do estabelecimento (1992–1997)", + "items": { + "type": "number" + }, + "type": "array" + }, + "years_without_race": { + "description": "Anos sem raça/cor (1998–2007)", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
get_hospitalization_rates1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "data", + "summary", + "metadata" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Taxa de internação por população (IBGE por UF), bruta ou específica; `error` quando o ano está fora da cobertura populacional ou nenhum ano pedido tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "data": { + "description": "Um estrato por linha (vazio quando não há internação no recorte)", + "items": { + "additionalProperties": false, + "properties": { + "deaths": { + "description": "Óbitos", + "type": "number" + }, + "mortality_rate": { + "description": "Óbitos / internações × 100, duas casas", + "type": "number" + }, + "n_hospitalizations": { + "description": "Internações", + "type": "number" + }, + "population": { + "description": "População do estrato (denominador)", + "type": "number" + }, + "population_source": { + "description": "Arquivo de população que serviu o ano", + "enum": [ + "detailed", + "aggregated", + null + ] + }, + "rate_per": { + "description": "Base da taxa (1000, 10000 ou 100000)", + "type": "number" + }, + "rate_per_100k": { + "description": "Internações por `rate_per` habitantes (o nome do campo é histórico; a base está em `rate_per`)", + "type": "number" + }, + "uf": { + "description": "UF (quando agrupado por UF ou mais de uma UF)", + "type": "string" + }, + "year": { + "description": "Ano (quando agrupado por ano ou mais de um ano)", + "type": "number" + } + }, + "required": [ + "n_hospitalizations", + "deaths", + "population", + "rate_per_100k", + "rate_per", + "population_source", + "mortality_rate" + ], + "type": "object" + }, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "metadata": { + "additionalProperties": false, + "properties": { + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "filters_applied": { + "additionalProperties": false, + "description": "Os argumentos, com UFs normalizadas e só os anos atendidos", + "properties": { + "age_max": { + "description": "Idade máxima", + "type": "integer" + }, + "age_min": { + "description": "Idade mínima", + "type": "integer" + }, + "cid_chapter": { + "description": "Capítulos CID-10 (1-22)", + "items": { + "type": "integer" + }, + "type": "array" + }, + "group_by": { + "description": "Dimensões para agrupamento", + "items": { + "enum": [ + "year", + "uf", + "sex" + ], + "type": "string" + }, + "type": "array" + }, + "is_csap": { + "description": "Filtrar apenas CSAP", + "type": "boolean" + }, + "rate_per": { + "description": "Taxa por X habitantes (default: 100000)", + "enum": [ + 1000, + 10000, + 100000 + ], + "type": "integer" + }, + "rate_type": { + "description": "Tipo de taxa: crude (bruta) ou specific (específica por filtro)", + "enum": [ + "crude", + "specific" + ], + "type": "string" + }, + "sex": { + "description": "Filtrar por sexo", + "enum": [ + "M", + "F" + ], + "type": "string" + }, + "uf": { + "description": "UFs para filtrar", + "items": { + "type": "string" + }, + "type": "array" + }, + "year": { + "description": "Anos para calcular", + "items": { + "type": "integer" + }, + "type": "array" + } + }, + "type": "object" + }, + "note": { + "description": "Presente quando nenhuma internação casou o recorte", + "type": "string" + }, + "population_notes": { + "description": "Avisos sobre o denominador (faixa quinquenal antes de 2000; mistura de fontes)", + "items": { + "type": "string" + }, + "type": "array" + }, + "population_source": { + "additionalProperties": { + "description": "Arquivo que serviu o ano", + "enum": [ + "detailed", + "aggregated", + null + ] + }, + "description": "Fonte da população — chave é o ano (string)", + "type": "object" + } + }, + "required": [ + "population_source", + "filters_applied" + ], + "type": "object" + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "population_years": { + "additionalProperties": false, + "description": "Cobertura dos arquivos de população por UF: o que as ferramentas de taxa aceitam", + "properties": { + "aggregated": { + "additionalProperties": false, + "description": "pop_uf_agregado.parquet — faixa etária quinquenal por UF e sexo (1991–1999)", + "properties": { + "age": { + "description": "Grão etário do arquivo", + "type": "string" + }, + "age_groups": { + "description": "Faixas etárias quinquenais (só no arquivo agregado)", + "items": { + "type": "string" + }, + "type": "array" + }, + "first_year": { + "description": "Primeiro ano coberto", + "type": "number" + }, + "last_year": { + "description": "Último ano coberto", + "type": "number" + }, + "source": { + "description": "Arquivo parquet que serve o intervalo", + "type": "string" + } + }, + "required": [ + "first_year", + "last_year", + "source", + "age" + ], + "type": [ + "object", + "null" + ] + }, + "detailed": { + "additionalProperties": false, + "description": "pop_uf.parquet — idade simples por UF e sexo (projeções IBGE, 2000+)", + "properties": { + "age": { + "description": "Grão etário do arquivo", + "type": "string" + }, + "age_groups": { + "description": "Faixas etárias quinquenais (só no arquivo agregado)", + "items": { + "type": "string" + }, + "type": "array" + }, + "first_year": { + "description": "Primeiro ano coberto", + "type": "number" + }, + "last_year": { + "description": "Último ano coberto", + "type": "number" + }, + "source": { + "description": "Arquivo parquet que serve o intervalo", + "type": "string" + } + }, + "required": [ + "first_year", + "last_year", + "source", + "age" + ], + "type": [ + "object", + "null" + ] + }, + "first_year": { + "description": "Primeiro ano com população por UF (união dos dois arquivos)", + "type": "number" + }, + "last_year": { + "description": "Último ano com população por UF", + "type": "number" + } + }, + "required": [ + "first_year", + "last_year", + "detailed", + "aggregated" + ], + "type": "object" + }, + "provenance": { + "description": "Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem", + "items": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "type": "array" + }, + "summary": { + "additionalProperties": false, + "properties": { + "overall_rate": { + "description": "Taxa do conjunto, na base `rate_per`", + "type": "number" + }, + "rate_per": { + "description": "Base da taxa", + "type": "number" + }, + "rate_type": { + "description": "Bruta ou específica", + "enum": [ + "crude", + "specific" + ] + }, + "total_hospitalizations": { + "description": "Internações somadas", + "type": "number" + }, + "total_population": { + "description": "População somada", + "type": "number" + } + }, + "required": [ + "total_hospitalizations", + "total_population", + "overall_rate", + "rate_per", + "rate_type" + ], + "type": "object" + }, + "truncated": { + "additionalProperties": false, + "description": "Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro", + "properties": { + "returned": { + "description": "Linhas devolvidas (o teto)", + "type": "number" + }, + "total": { + "description": "Linhas que a consulta produziu", + "type": "number" + } + }, + "required": [ + "returned", + "total" + ], + "type": "object" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
get_hospitalization_trends1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "granularity", + "period", + "series" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Série temporal de internações, anual (`year`) ou mensal (`year_month`); `error` quando nenhum ano do intervalo tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "data": { + "description": "Sempre vazio: só aparece no caminho de erro-mole do funil", + "items": {}, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "granularity": { + "description": "Grão da série", + "enum": [ + "yearly", + "monthly" + ] + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "period": { + "additionalProperties": false, + "description": "Intervalo pedido", + "properties": { + "end": { + "description": "Ano (anual) ou AAAA-MM (mensal) final", + "type": [ + "number", + "string" + ] + }, + "start": { + "description": "Ano (anual) ou AAAA-MM (mensal) inicial", + "type": [ + "number", + "string" + ] + } + }, + "required": [ + "start", + "end" + ], + "type": "object" + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "series": { + "description": "Um ponto por ano ou por mês, em ordem cronológica", + "items": { + "anyOf": [ + { + "additionalProperties": false, + "description": "Ponto anual", + "properties": { + "deaths": { + "description": "Óbitos no ano", + "type": "number" + }, + "n_hospitalizations": { + "description": "Internações no ano", + "type": "number" + }, + "year": { + "description": "Ano", + "type": "number" + } + }, + "required": [ + "year", + "n_hospitalizations", + "deaths" + ], + "type": "object" + }, + { + "additionalProperties": false, + "description": "Ponto mensal", + "properties": { + "deaths": { + "description": "Óbitos no mês", + "type": "number" + }, + "n": { + "description": "Internações no mês", + "type": "number" + }, + "year_month": { + "description": "Competência AAAA-MM", + "type": "string" + } + }, + "required": [ + "year_month", + "n", + "deaths" + ], + "type": "object" + } + ] + }, + "type": "array" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
get_hospitalizations1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "data", + "summary", + "filters_applied" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Internações do cubo de causas, agrupadas conforme `group_by`, com totais do recorte inteiro; `error` quando nenhum ano pedido tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "data": { + "description": "Linhas agrupadas (vazio no caminho de erro-mole)", + "items": { + "additionalProperties": false, + "description": "Uma linha por combinação de `group_by` (só as colunas pedidas aparecem)", + "properties": { + "age": { + "description": "Idade em anos (group_by: age)", + "type": "number" + }, + "cid_chapter": { + "description": "Capítulo da CID, 1–22 (group_by: cid_chapter)", + "type": "number" + }, + "cid_group": { + "description": "Categoria CID de 3 dígitos (group_by: cid_group)", + "type": "string" + }, + "cid_revision": { + "description": "Revisão da CID do diagnóstico: 9 ou 10 (group_by: cid_revision)", + "type": "number" + }, + "csap_group": { + "description": "Grupo CSAP g01–g19; null quando a internação não é sensível (group_by: csap_group)", + "type": [ + "string", + "null" + ] + }, + "deaths": { + "description": "Óbitos; null quando o recorte não tem nenhuma linha", + "type": [ + "number", + "null" + ] + }, + "exclusion": { + "description": "Motivo de exclusão do universo csapAIH; null quando dentro do universo (group_by: exclusion)", + "type": [ + "string", + "null" + ] + }, + "is_csap": { + "description": "Internação por condição sensível à atenção primária (group_by: is_csap)", + "type": "boolean" + }, + "month": { + "description": "Mês, 1–12 (group_by: month)", + "type": "number" + }, + "n_hospitalizations": { + "description": "Internações; null quando o recorte não tem nenhuma linha", + "type": [ + "number", + "null" + ] + }, + "race": { + "description": "Raça/cor; null em 1998–2007, quando a AIH não trazia o campo (group_by: race)", + "type": [ + "string", + "null" + ] + }, + "sex": { + "description": "Sexo: M ou F (group_by: sex)", + "type": "string" + }, + "total_days": { + "description": "Dias de permanência; null quando o recorte não tem nenhuma linha", + "type": [ + "number", + "null" + ] + }, + "total_value": { + "description": "Valor total pago (R$); null quando o recorte não tem nenhuma linha", + "type": [ + "number", + "null" + ] + }, + "uf": { + "description": "UF de residência — do estabelecimento em 1992–1997 (group_by: uf)", + "type": "string" + }, + "year": { + "description": "Ano (group_by: year)", + "type": "number" + } + }, + "required": [ + "n_hospitalizations", + "total_days", + "total_value", + "deaths" + ], + "type": "object" + }, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "filters_applied": { + "additionalProperties": false, + "description": "Os argumentos recebidos, ecoados", + "properties": { + "age_max": { + "description": "Idade máxima em anos", + "type": "integer" + }, + "age_min": { + "description": "Idade mínima em anos", + "type": "integer" + }, + "cid_chapter": { + "description": "Capítulos CID-10 (1-22). Se omitido, todos.", + "items": { + "type": "integer" + }, + "type": "array" + }, + "group_by": { + "description": "Dimensões para agrupamento", + "items": { + "enum": [ + "year", + "month", + "uf", + "cid_chapter", + "cid_revision", + "cid_group", + "sex", + "age", + "race", + "exclusion", + "is_csap", + "csap_group" + ], + "type": "string" + }, + "type": "array" + }, + "is_csap": { + "description": "Filtrar apenas CSAP (true) ou não-CSAP (false)", + "type": "boolean" + }, + "limit": { + "description": "Limitar número de resultados", + "type": "integer" + }, + "month": { + "description": "Meses (1-12). Se omitido, todos.", + "items": { + "type": "integer" + }, + "type": "array" + }, + "race": { + "description": "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.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sex": { + "description": "Filtrar por sexo", + "enum": [ + "M", + "F" + ], + "type": "string" + }, + "uf": { + "description": "Lista de UFs (ex: ['SP', 'RJ']). Se omitido, todas.", + "items": { + "type": "string" + }, + "type": "array" + }, + "year": { + "description": "Anos para consultar (ex: [2023, 2024]); série de 1992 em diante", + "items": { + "type": "integer" + }, + "type": "array" + } + }, + "type": "object" + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "summary": { + "additionalProperties": false, + "description": "Totais do recorte inteiro (não do trecho devolvido, quando truncado)", + "properties": { + "deaths": { + "description": "Óbitos", + "type": "number" + }, + "hospital_mortality_rate": { + "description": "Óbitos / internações × 100, duas casas", + "type": "number" + }, + "records_returned": { + "description": "Linhas em `data`", + "type": "number" + }, + "total_days": { + "description": "Dias de permanência", + "type": "number" + }, + "total_hospitalizations": { + "description": "Internações no recorte inteiro", + "type": "number" + }, + "total_value": { + "description": "Valor pago (R$), duas casas", + "type": "number" + } + }, + "required": [ + "total_hospitalizations", + "total_days", + "total_value", + "deaths", + "hospital_mortality_rate", + "records_returned" + ], + "type": "object" + }, + "truncated": { + "additionalProperties": false, + "description": "Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro", + "properties": { + "returned": { + "description": "Linhas devolvidas (o teto)", + "type": "number" + }, + "total": { + "description": "Linhas que a consulta produziu", + "type": "number" + } + }, + "required": [ + "returned", + "total" + ], + "type": "object" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
get_icsap1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "data", + "notes", + "summary", + "filters_applied" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Internações por condições sensíveis à atenção primária, agrupadas conforme `group_by`, com totais e a nota do universo; `error` quando nenhum ano pedido tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "data": { + "description": "Linhas agrupadas (vazio no caminho de erro-mole)", + "items": { + "additionalProperties": false, + "description": "Uma linha por combinação de `group_by` (só as colunas pedidas aparecem)", + "properties": { + "age": { + "description": "Idade em anos (group_by: age)", + "type": "number" + }, + "cid_revision": { + "description": "Revisão da CID: 9 ou 10 (group_by: cid_revision)", + "type": "number" + }, + "csap_group": { + "description": "Grupo CSAP g01–g19 (group_by: csap_group)", + "type": [ + "string", + "null" + ] + }, + "deaths": { + "description": "Óbitos nas ICSAP", + "type": "number" + }, + "icsap_percentage": { + "description": "n_icsap / n_total × 100, duas casas", + "type": "number" + }, + "municipality_code": { + "description": "Código IBGE do município de residência (6 dígitos); null em 1992–1997 (group_by: municipality_code)", + "type": [ + "string", + "null" + ] + }, + "n_icsap": { + "description": "Internações por condições sensíveis à atenção primária no universo escolhido", + "type": "number" + }, + "n_total": { + "description": "Total de internações no universo escolhido (denominador)", + "type": "number" + }, + "race": { + "description": "Raça/cor; null em 1998–2007 (group_by: race)", + "type": [ + "string", + "null" + ] + }, + "sex": { + "description": "Sexo: M ou F (group_by: sex)", + "type": "string" + }, + "total_days": { + "description": "Dias de permanência das ICSAP", + "type": "number" + }, + "total_value": { + "description": "Valor pago das ICSAP (R$)", + "type": "number" + }, + "uf": { + "description": "UF de residência — do estabelecimento em 1992–1997 (group_by: uf)", + "type": "string" + }, + "year": { + "description": "Ano (group_by: year)", + "type": "number" + } + }, + "required": [ + "n_icsap", + "n_total", + "icsap_percentage", + "total_days", + "total_value", + "deaths" + ], + "type": "object" + }, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "filters_applied": { + "additionalProperties": false, + "description": "Os argumentos recebidos, ecoados", + "properties": { + "age_max": { + "description": "Idade máxima", + "type": "integer" + }, + "age_min": { + "description": "Idade mínima", + "type": "integer" + }, + "csap_group": { + "description": "Grupos CSAP (ex: ['g01', 'g05'])", + "items": { + "type": "string" + }, + "type": "array" + }, + "group_by": { + "description": "Dimensões para agrupamento", + "items": { + "enum": [ + "year", + "uf", + "municipality_code", + "cid_revision", + "csap_group", + "sex", + "age", + "race" + ], + "type": "string" + }, + "type": "array" + }, + "municipality_code": { + "description": "Código IBGE do município (6 dígitos)", + "type": "string" + }, + "race": { + "description": "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.", + "items": { + "type": "string" + }, + "type": "array" + }, + "sex": { + "description": "Filtrar por sexo", + "enum": [ + "M", + "F" + ], + "type": "string" + }, + "uf": { + "description": "UFs para filtrar", + "items": { + "type": "string" + }, + "type": "array" + }, + "universe": { + "description": "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.", + "enum": [ + "csapaih", + "all" + ], + "type": "string" + }, + "year": { + "description": "Anos para consultar", + "items": { + "type": "integer" + }, + "type": "array" + } + }, + "type": "object" + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "provenance": { + "description": "Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem", + "items": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "type": "array" + }, + "summary": { + "additionalProperties": false, + "description": "Totais do recorte inteiro, calculados sem agrupamento", + "properties": { + "deaths": { + "description": "Óbitos nas ICSAP", + "type": "number" + }, + "icsap_percentage": { + "description": "total_icsap / total_hospitalizations × 100, duas casas", + "type": "number" + }, + "records_returned": { + "description": "Linhas em `data`", + "type": "number" + }, + "total_days": { + "description": "Dias de permanência das ICSAP", + "type": "number" + }, + "total_hospitalizations": { + "description": "Internações no universo (denominador)", + "type": "number" + }, + "total_icsap": { + "description": "ICSAP no recorte inteiro", + "type": "number" + }, + "total_value": { + "description": "Valor pago das ICSAP (R$)", + "type": "number" + } + }, + "required": [ + "total_icsap", + "total_hospitalizations", + "icsap_percentage", + "total_days", + "total_value", + "deaths", + "records_returned" + ], + "type": "object" + }, + "truncated": { + "additionalProperties": false, + "description": "Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro", + "properties": { + "returned": { + "description": "Linhas devolvidas (o teto)", + "type": "number" + }, + "total": { + "description": "Linhas que a consulta produziu", + "type": "number" + } + }, + "required": [ + "returned", + "total" + ], + "type": "object" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
get_icsap_indicators1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "data", + "notes", + "indicators_calculated", + "note" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Percentual de ICSAP por estrato de `group_by`, com a fórmula e a nota do universo; `error` quando nenhum ano pedido tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "data": { + "description": "Um estrato por linha (vazio no caminho de erro-mole)", + "items": { + "additionalProperties": false, + "description": "Uma linha por combinação de `group_by` (só as colunas pedidas aparecem)", + "properties": { + "age": { + "description": "Idade em anos (group_by: age)", + "type": "number" + }, + "cid_revision": { + "description": "Revisão da CID: 9 ou 10 (group_by: cid_revision)", + "type": "number" + }, + "csap_group": { + "description": "Grupo CSAP g01–g19 (group_by: csap_group)", + "type": [ + "string", + "null" + ] + }, + "deaths": { + "description": "Óbitos nas ICSAP", + "type": "number" + }, + "icsap_percentage": { + "description": "n_icsap / n_total × 100, duas casas", + "type": "number" + }, + "municipality_code": { + "description": "Código IBGE do município de residência (6 dígitos); null em 1992–1997 (group_by: municipality_code)", + "type": [ + "string", + "null" + ] + }, + "n_icsap": { + "description": "Internações por condições sensíveis à atenção primária no universo escolhido", + "type": "number" + }, + "n_total": { + "description": "Total de internações no universo escolhido (denominador)", + "type": "number" + }, + "race": { + "description": "Raça/cor; null em 1998–2007 (group_by: race)", + "type": [ + "string", + "null" + ] + }, + "sex": { + "description": "Sexo: M ou F (group_by: sex)", + "type": "string" + }, + "total_days": { + "description": "Dias de permanência das ICSAP", + "type": "number" + }, + "total_value": { + "description": "Valor pago das ICSAP (R$)", + "type": "number" + }, + "uf": { + "description": "UF de residência — do estabelecimento em 1992–1997 (group_by: uf)", + "type": "string" + }, + "year": { + "description": "Ano (group_by: year)", + "type": "number" + } + }, + "required": [ + "n_icsap", + "n_total", + "icsap_percentage", + "total_days", + "total_value", + "deaths" + ], + "type": "object" + }, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "indicators_calculated": { + "description": "Indicadores presentes nas linhas (icsap_percentage)", + "items": { + "type": "string" + }, + "type": "array" + }, + "note": { + "description": "Fórmula do indicador — ou, no caminho de erro-mole, como obter o dado", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "provenance": { + "description": "Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem", + "items": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "type": "array" + }, + "truncated": { + "additionalProperties": false, + "description": "Presente só quando `data` foi truncado no teto de linhas; os totais em `summary` são do conjunto inteiro", + "properties": { + "returned": { + "description": "Linhas devolvidas (o teto)", + "type": "number" + }, + "total": { + "description": "Linhas que a consulta produziu", + "type": "number" + } + }, + "required": [ + "returned", + "total" + ], + "type": "object" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
list_cid_chapters1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "total_chapters", + "chapters" + ] + } + ], + "description": "Os 22 capítulos da CID-10 (versão 2019), com intervalo de códigos e nomes", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "chapters": { + "description": "Os capítulos, na ordem da CID", + "items": { + "additionalProperties": false, + "properties": { + "code": { + "description": "Capítulo em algarismo romano (chave usada em `cid_chapter` é o número, 1–22)", + "type": "string" + }, + "name_en": { + "description": "Nome em inglês", + "type": "string" + }, + "name_pt": { + "description": "Nome em português", + "type": "string" + }, + "range": { + "description": "Intervalo de códigos CID-10 (ex.: A00-B99)", + "type": "string" + }, + "roman": { + "description": "Capítulo em algarismo romano", + "type": "string" + } + }, + "required": [ + "code", + "roman", + "range", + "name_pt", + "name_en" + ], + "type": "object" + }, + "type": "array" + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "total_chapters": { + "description": "Número de capítulos (22)", + "type": "number" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
list_csap_groups1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "total_groups", + "source", + "groups" + ] + }, + { + "required": [ + "group" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Os 19 grupos CSAP (lista completa) ou um grupo só, quando `group_code` é informado; `error` quando o código não existe", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "error": { + "description": "Grupo CSAP não encontrado", + "type": "string" + }, + "group": { + "additionalProperties": false, + "description": "O grupo pedido por `group_code`", + "properties": { + "cid_codes": { + "description": "Todos os códigos CID-10 do grupo; só com `include_cid_codes: true`", + "items": { + "type": "string" + }, + "type": "array" + }, + "code": { + "description": "Código do grupo, g01–g19", + "type": "string" + }, + "diagnoses": { + "description": "Diagnósticos que compõem o grupo, com seus códigos", + "items": { + "additionalProperties": false, + "properties": { + "cid10": { + "description": "Códigos CID-10 do diagnóstico", + "items": { + "type": "string" + }, + "type": "array" + }, + "name": { + "description": "Diagnóstico", + "type": "string" + } + }, + "required": [ + "name", + "cid10" + ], + "type": "object" + }, + "type": "array" + }, + "id": { + "description": "Número do grupo na Portaria, 1–19", + "type": "number" + }, + "name_en": { + "description": "Nome em inglês", + "type": "string" + }, + "name_pt": { + "description": "Nome em português", + "type": "string" + } + }, + "required": [ + "id", + "code", + "name_pt", + "name_en", + "diagnoses" + ], + "type": "object" + }, + "groups": { + "description": "Os 19 grupos, na ordem da Portaria", + "items": { + "additionalProperties": false, + "properties": { + "cid_codes": { + "description": "Códigos CID-10 do grupo; só com `include_cid_codes: true`", + "items": { + "type": "string" + }, + "type": "array" + }, + "cid_count": { + "description": "Quantos códigos CID-10 compõem o grupo", + "type": "number" + }, + "code": { + "description": "Código do grupo, g01–g19", + "type": "string" + }, + "name": { + "description": "Nome do grupo em português", + "type": "string" + } + }, + "required": [ + "code", + "name", + "cid_count" + ], + "type": "object" + }, + "type": "array" + }, + "provenance": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "source": { + "description": "Norma que define a lista (Portaria MS/SAS 221/2008)", + "type": "string" + }, + "total_groups": { + "description": "Número de grupos na lista (19)", + "type": "number" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
- Changed
rank_csap_groups1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "metric", + "ranking", + "notes", + "concentration", + "total_groups" + ] + }, + { + "required": [ + "error" + ] + } + ], + "description": "Os grupos CSAP ordenados pela métrica, com participação de cada um e concentração nos primeiros; `error` quando nenhum ano pedido tem dado", + "properties": { + "attribution": { + "description": "URLs canônicas das fontes desta resposta (lista de atribuição)", + "items": { + "type": "string" + }, + "type": "array" + }, + "available_sih_years": { + "description": "Anos com dados SIH atendíveis por este servidor", + "items": { + "type": "number" + }, + "type": "array" + }, + "concentration": { + "additionalProperties": false, + "properties": { + "top_3_percentage": { + "description": "Soma da participação dos 3 primeiros, %", + "type": "number" + }, + "top_5_percentage": { + "description": "Soma dos 5 primeiros, %", + "type": "number" + } + }, + "required": [ + "top_3_percentage", + "top_5_percentage" + ], + "type": "object" + }, + "data": { + "description": "Sempre vazio: só aparece no caminho de erro-mole do funil", + "items": {}, + "type": "array" + }, + "error": { + "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)", + "type": "string" + }, + "metric": { + "description": "Métrica que ordena", + "enum": [ + "n", + "days", + "value", + "deaths" + ] + }, + "note": { + "description": "Como obter o dado (por exemplo, consultar get_available_years)", + "type": "string" + }, + "notes": { + "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento", + "items": { + "type": "string" + }, + "type": "array" + }, + "provenance": { + "description": "Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem", + "items": { + "additionalProperties": false, + "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença", + "properties": { + "citation": { + "description": "Citação pronta para uso", + "type": "string" + }, + "data_vintage": { + "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "Regime legal do dado (id SPDX quando há)", + "type": [ + "string", + "null" + ] + }, + "retrieved_at": { + "description": "Instante REAL da extração na origem (ISO-8601)", + "type": "string" + }, + "source": { + "description": "Fonte oficial do dado", + "type": "string" + }, + "source_url": { + "description": "URL canônica que reproduz a consulta ou localiza a fonte", + "type": "string" + } + }, + "required": [ + "source", + "source_url", + "data_vintage", + "retrieved_at", + "citation", + "license" + ], + "type": "object" + }, + "type": "array" + }, + "ranking": { + "description": "Ranking em ordem decrescente da métrica", + "items": { + "additionalProperties": false, + "properties": { + "csap_group": { + "description": "Grupo CSAP g01–g19", + "type": "string" + }, + "csap_name": { + "description": "Nome do grupo", + "type": "string" + }, + "deaths": { + "description": "Óbitos", + "type": "number" + }, + "metric_value": { + "description": "Valor da métrica escolhida", + "type": "number" + }, + "n_hospitalizations": { + "description": "Internações do grupo", + "type": "number" + }, + "pct_of_total": { + "description": "Participação do grupo no total da métrica, %", + "type": "number" + }, + "rank": { + "description": "Posição, 1 = maior", + "type": "number" + }, + "total_days": { + "description": "Dias de permanência", + "type": "number" + }, + "total_value": { + "description": "Valor pago (R$)", + "type": "number" + } + }, + "required": [ + "rank", + "csap_group", + "csap_name", + "metric_value", + "pct_of_total", + "n_hospitalizations", + "total_days", + "total_value", + "deaths" + ], + "type": "object" + }, + "type": "array" + }, + "total_groups": { + "description": "Quantos grupos no ranking", + "type": "number" + }, + "years_not_available": { + "additionalProperties": false, + "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos", + "properties": { + "note": { + "description": "Quais anos ficaram fora e quais os números cobrem", + "type": "string" + }, + "years": { + "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado", + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "years", + "note" + ], + "type": "object" + } + }, + "required": [ + "provenance", + "attribution" + ], + "type": "object" +}
12 tool updates
v0.15.4- Changed
classify_as_csap1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
compare_icsap_trends1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
compare_regions1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
get_available_years1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
get_hospitalization_rates1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
get_hospitalization_trends1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
get_hospitalizations1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
get_icsap1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
get_icsap_indicators1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
list_cid_chapters1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
list_csap_groups1 field changed- added
Input schema / additionalPropertiesAdded value: +false
- Changed
rank_csap_groups1 field changed- added
Input schema / additionalPropertiesAdded value: +false
12 tool updates
v0.12.1- First observed
classify_as_csap - First observed
compare_icsap_trends - First observed
compare_regions - First observed
get_available_years - First observed
get_hospitalization_rates - First observed
get_hospitalization_trends - First observed
get_hospitalizations - First observed
get_icsap - First observed
get_icsap_indicators - First observed
list_cid_chapters - First observed
list_csap_groups - First observed
rank_csap_groups
TDQS
Scored across 12 tools
The tools separate metadata, classification, raw queries, and analytical views fairly well, and the detailed descriptions clarify intent. The main ambiguity risk is between compare_regions and compare_icsap_trends, since both compare UFs, though one is general hospitalizations and the other is ICSAP-specific temporal analysis.
Tool names consistently use snake_case and mostly follow a verb_noun pattern such as list_csap_groups, get_hospitalizations, and rank_csap_groups. Minor inconsistency exists between list_ and get_ for metadata tools, and some names use acronyms like get_icsap, but overall the pattern is predictable.
Twelve tools is well-scoped for a specialized read-only SIH-SUS/ICSAP analysis server: metadata, classification, queries, trends, comparisons, indicators, ranking, and rates each serve a distinct purpose. No tool feels redundant or like padding.
The surface covers the domain thoroughly: CSAP group metadata, CID chapters, data availability and freshness, CID classification, general hospitalization queries, ICSAP-specific queries, trends, regional comparisons, indicators, rankings, and population rates. There are no significant dead ends for the intended analytical workflows.
Maintenance
Related MCP Connectors
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).
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
Related MCP Servers
- AlicenseAqualityFmaintenanceMCP server for Brazilian ICD-10 (CID-10) that enables search, lookup, hierarchy navigation, statistics, and validation of disease codes from official DATASUS data.61,182 npm1MIT
- AlicenseAqualityAmaintenanceEnables querying and retrieving municipal data from Chile's SINIM system, including 480 variables across 9 areas for 345 municipalities from 2001-2025.95MIT
- FlicenseNot gradedqualityCmaintenanceRead-only MCP server for querying Brazilian CNES health establishment data in PostgreSQL, enabling AI-assisted database exploration and analysis.-
- AlicenseAqualityAmaintenanceMCP server for loading and querying public data from the Brazilian National Registry of Health Establishments (CNES). It enables natural language searches for health facilities by municipality, CNES code, or state, along with statistics and data loading.6MIT