# IBGE Brasil MCP

> IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.

- name: io.github.SidneyBissoli/ibge-br-mcp
- version: 5.10.0
- connection class: R0 (autonomous)
- trust: 97/100
- quality: 84/100 (good)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/io.github.SidneyBissoli%2Fibge-br-mcp
- tools: https://api.protogrid.dev/v1/servers/io.github.SidneyBissoli%2Fibge-br-mcp/tools

**An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "ibge-br-mcp": {
      "type": "http",
      "url": "https://ibge.sidneybissoli.com/mcp"
    }
  }
}
```


## Trust

- hygiene: 100
- liveness: 99
- freshness: 100
- provenance: 90
- drivers: +repository +namespace-matches-repo +website +reachable +uptime-97% +updated-4d-ago
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 84/100 (good)

### protocol: 88 (weight 25)

- pass `protocol.modern`: supports 2026-07-28 (server/discover)
- pass `protocol.stateless`: answers without a session
- pass `protocol.transport`: streamable HTTP
- warn `protocol.list_ttl`: tools/list declares ttlMs 0, so clients re-fetch it on every use

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 86 (weight 30)

- pass `tools.descriptions`: every tool has a description
- warn `tools.description_length`: 9 tools have descriptions over 1,024 characters, which crowds the context
- pass `tools.schemas`: every tool has an object input schema
- pass `tools.annotations`: 23 of 23 tools declare readOnlyHint or destructiveHint
- pass `tools.directory_hints`: every tool declares readOnlyHint, destructiveHint, idempotentHint and openWorldHint
- warn `tools.token_cost`: about 12,746 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 75 (weight 15)

- warn `stability.changes`: 79 tool changes in 30 days
- pass `stability.rug_pull`: no tool changed its meaning under the same name

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: deps.dev does not know ibge-br-mcp@5.10.0

- tools: 23, about 12,746 tokens to load them all
- tool set hash: a5c1633f62c0b747465e801ef0eda983
- tools last changed: 2026-10-16T09:01:46.344Z
- badge: [![protogrid quality](https://protogrid.dev/badge/io.github.SidneyBissoli/ibge-br-mcp.svg)](https://protogrid.dev/servers/io.github.SidneyBissoli/ibge-br-mcp)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

- 2026-10-16 `ibge_paises` changed (description, inputSchema, outputSchema)
  - before: Queries international country data via IBGE. Features: - List all countries (following UN M49 methodology) - Country details (area, languages, currency, location) - Search countries by name - Filter by region/continent Available regions: americas, europa, africa, asia, oceania Country codes: Use ISO-ALPHA-2 (e.g., BR, US, AR, PT, JP) Examples: - List all: tipo="listar" - Brazil details: tipo="detalhes", pais="BR" - Search: tipo="buscar", busca="Argentina" - Americas countries: tipo="listar", regiao="americas" - Available indicators: tipo="indicadores" Behavior: read-only and idempotent — a live GET against the public IBGE Países API. Returns Markdown.
  - after: Queries international country data via IBGE. Features: - List all countries (following UN M49 methodology) - Country details (area, languages, currency, location) with the latest published value of country indicators — by default population, GDP, GDP per capita, HDI and life expectancy - Pick other indicators with indicadores="<ids or aliases separated by |>" - Indicator catalog as published by IBGE (34 indicators: economy, population, health, environment, networks), with unit and scale - Search countries by name - Filter by region/continent Each indicator value is the most recent one the source publishes for that country, with its year or period (some are 3- or 5-year ranges like "2021-2023"), as text (it can be "<2.5"), plus unit and scale (multiplicador) — null when the source has none. Available regions: americas, europa, africa, asia, oceania Country codes: Use ISO-ALPHA-2 (e.g., BR, US, AR, PT, JP) Examples: - List all: tipo="listar" - Brazil details: tipo="detalhes", pais="BR" - Chosen indicators: tipo="detalhes", pais="AR", indicadores="idh|77852" - Search: tipo="buscar", busca="Argentina" - Americas countries: tipo="listar", regiao="americas" - Indicator catalog: tipo="indicadores" Behavior: read-only and idempotent — a live GET against the public IBGE Países API. Returns Markdown.
- 2026-10-16 `ibge_datasaude` changed (outputSchema)
- 2026-10-16 `ibge_comparar` changed (outputSchema)
- 2026-10-16 `ibge_indicadores` changed (outputSchema)
- 2026-10-16 `ibge_censo` changed (outputSchema)
- 2026-10-16 `ibge_sidra` changed (outputSchema)
- 2026-10-08 `fetch` changed (outputSchema)
- 2026-10-08 `search` changed (outputSchema)
- 2026-10-08 `ibge_cidades` changed (outputSchema)
- 2026-10-08 `ibge_paises` changed (outputSchema)

Full history: https://api.protogrid.dev/v1/servers/io.github.SidneyBissoli%2Fibge-br-mcp/changes

## Dependencies

- npm ibge-br-mcp@5.10.0: unknown

Dependency graphs from deps.dev; advisories from OSV.dev, including the GitHub Advisory Database and the PyPI Advisory Database; all CC BY 4.0.

## Remotes

- https://ibge.sidneybissoli.com/mcp (streamable-http, auth none, reachable true, uptime30d 0.9736842)

## Packages

- npm ibge-br-mcp@5.10.0

## Tools (23)

- `fetch`: Returns the full document for an id obtained from `search`, as { id, title, text, url, metadata }: `text` is the readable content (Markdown) and `url` the canonical public page to cite.

Companion of `search` in the OpenAI Deep Research contract, over the IBGE (Brazilian official statistics: SIDRA tables, municipalities, known indicators) catalog. Only ids returned by `search` are valid; an unknown id returns an error.
The `ibge_*` tools (`ibge_sidra`, `ibge_cidades`, `ibge_indicadores`, `ibge_comparar`…) remain the tools for data queries.

Behavior: read-only and idempotent — a live GET against the public source when the document needs it.
- `ibge_calendario`: Queries IBGE release and collection calendar.

Features:
- List upcoming survey releases
- Filter by product (IPCA, PNAD, GDP, etc.)
- Filter by period
- Distinguish releases from field collections

Event types:
- **Release**: Publication of survey results
- **Collection**: Field research period

Examples:
- Upcoming releases: (no parameters)
- IPCA releases: produto="IPCA"
- 2024 calendar: de="01/01/2024", ate="31/12/2024"
- Field collections: tipo="coleta"

Use a different tool when:
- Already-published news and releases → ibge_noticias

Behavior: read-only and idempotent — a live GET against the public IBGE Calendário API. Returns a Markdown list.
- `ibge_censo`: Queries IBGE Demographic Census data (1970-2022).

Simplified tool to access census data without knowing SIDRA table codes.

Available years: 1970, 1980, 1991, 2000, 2010, 2022

Available themes:
- populacao: Resident population
- alfabetizacao: Literacy rate
- domicilios: Housing characteristics
- idade_sexo: Age pyramid
- religiao: Religion distribution
- cor_raca: Race/color
- rendimento: Monthly income
- educacao: Education level
- trabalho: Employment

Examples:
- Population 2022: ano="2022", tema="populacao"
- Historical series: ano="todos", tema="populacao"
- Literacy 2010 by state: ano="2010", tema="alfabetizacao", nivel_territorial="3"
- List tables: tema="listar"

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions over census data ("which municipality had the largest 2022 population?") use estatisticas=true — full distribution + top/bottom computed over ALL rows before truncation; agruparPor="<column label>" ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.

Use a different tool when:
- One municipality's current panel (estimate, HDI, GDP) → ibge_cidades
- Comparing/ranking localities → ibge_comparar
- An arbitrary SIDRA table → ibge_sidra

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
- `ibge_cidades`: Queries municipal indicators from IBGE (similar to Cidades@ portal).

Features:
- General overview of a municipality (population, HDI, GDP, etc.)
- Query specific indicators
- Historical indicator data over years
- List available surveys and indicators

Available indicators: populacao, area, densidade, pib_per_capita, idh,
escolarizacao, mortalidade, salario_medio, receitas, despesas

Examples:
- São Paulo overview: tipo="panorama", municipio="3550308"
- Population history: tipo="historico", municipio="3550308", indicador="populacao"
- View surveys: tipo="pesquisas"
- Available indicators: tipo="indicador"

This tool is the panel for a SINGLE municipality (Cidades@).
Use a different tool when:
- Census themes / historical series → ibge_censo
- Comparing multiple municipalities → ibge_comparar
- A macro indicator time series → ibge_indicadores

Behavior: read-only and idempotent — a live GET against the public IBGE APIs (Cidades@/agregados). Returns Markdown plus a typed structuredContent payload.
- `ibge_cnae`: Queries CNAE (National Classification of Economic Activities) from IBGE.

CNAE is the official classification for economic activities in Brazil.

Hierarchical structure:
- Section (letter A-U): 21 main categories
- Division (2 digits): 87 divisions
- Group (3 digits): 285 groups
- Class (4-5 digits): 673 classes
- Subclass (7 digits): 1,332 subclasses

Features:
- Search by CNAE code
- Search by activity description
- List by hierarchical level
- Show complete hierarchy

Examples:
- Search software: busca="software"
- Specific code: codigo="6201-5/01"
- View section: codigo="J"
- List divisions: nivel="divisoes"

Behavior: read-only and idempotent — a live GET against the public IBGE CNAE API. Returns Markdown.
- `ibge_comparar`: Compares data between localities (municipalities or states).

Available indicators:
- populacao: Current population estimate
- populacao_censo: Census 2022 population
- pib: GDP per capita
- area: Territorial area (km²)
- densidade: Population density (inhab/km²)
- alfabetizacao: Literacy rate
- domicilios: Number of households

Features:
- Compare up to 10 localities at once
- Calculate statistics (max, min, average, variation)
- Generate ranked output
- Accept municipality codes (7 digits) or state codes (2 digits)

Examples:
- Compare capitals: localidades="3550308,3304557,4106902", indicador="populacao"
- Compare states: localidades="35,33,41", indicador="pib"
- Area ranking: localidades="3550308,3304557", formato="ranking"
- List indicators: indicador="listar"

Use this tool ONLY to rank/compare 2–10 localities on one indicator.
For a single locality, use ibge_cidades (municipal panel), ibge_censo, or ibge_sidra.

Behavior: read-only and idempotent — a live GET against the public IBGE APIs (SIDRA and Localidades). Returns Markdown plus a typed structuredContent payload.
- `ibge_datasaude`: Queries Brazil health indicators, served through IBGE's SIDRA (some originally produced by DataSUS, e.g. mortality and births).

Mortality and Birth:
- mortalidade_infantil: Infant mortality rate
- nascidos_vivos: Live births by location
- obitos: Deaths by residence

Demographic Indicators:
- esperanca_vida: Life expectancy at birth
- fecundidade: Fertility rate

Sanitation:
- saneamento_agua: Water supply
- saneamento_esgoto: Sewage system

Health Coverage:
- plano_saude: Health insurance coverage
- autoavaliacao_saude: Self-rated health status

Territorial levels: 1=Brazil, 2=Region, 3=State, 6=Municipality

Examples:
- Infant mortality: indicador="mortalidade_infantil"
- Life expectancy by state: indicador="esperanca_vida", nivel_territorial="3"
- Deaths in SP: indicador="obitos", nivel_territorial="3", localidade="35"
- List indicators: indicador="listar"

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest infant mortality?", "median life expectancy across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="<column label>" ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.

Use a different tool when:
- A single municipality's general panel (which also includes infant mortality) → ibge_cidades
- Population/demographic counts (not health-specific) → ibge_censo or ibge_sidra

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
- `ibge_estados`: Lists all Brazilian states from IBGE.

Features:
- Lists all 27 states (26 states + Federal District)
- Filter by region (North, Northeast, Southeast, South, Central-West)
- Sort by ID, name, or abbreviation

Examples:
- List all states: (no parameters)
- Northeast states: regiao="NE"
- Sorted by abbreviation: ordenar="sigla"

Use a different tool when:
- Municipalities of a state → ibge_municipios
- Details/hierarchy of one locality by code → ibge_localidade

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown table.
- `ibge_geocodigo`: Decodes IBGE codes or searches codes by locality name.

Features:
- Decode region, state, municipality, or district codes
- Search IBGE code by name
- Show complete geographic hierarchy
- Return related codes

Code structure:
- 1 digit: Region (1=North, 2=Northeast, 3=Southeast, 4=South, 5=Central-West)
- 2 digits: State (11-53)
- 7 digits: Municipality
- 9 digits: District

Examples:
- Decode municipality: codigo="3550308"
- Decode state: codigo="35"
- Search by name: nome="São Paulo"
- Municipality in state: nome="Campinas", uf="SP"

This tool decodes a code's structure and resolves name→code at any level.
Use a different tool when:
- You only need to list/search municipalities → ibge_municipios
- You want the full detailed record of one locality → ibge_localidade

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns Markdown.
- `ibge_indicadores`: Queries IBGE economic and social indicators.

Available indicators:

**Economic:**
- pib: quarterly GDP at current prices, R$ million (Brazil only)
- pib_variacao: quarterly GDP volume change, % over the same quarter of the previous year (Brazil only)
- pib_per_capita: annual GDP per capita at current prices, R$ (Brazil only)
- industria: industrial production index, general industry (2022=100)
- comercio: retail sales volume index (2022=100)
- servicos: services volume index (2022=100, Brazil only)

**Prices:**
- ipca: IPCA monthly change, %
- ipca_acumulado: IPCA accumulated over 12 months, %
- inpc: INPC monthly change, %

**Labor:**
- desemprego: Unemployment rate
- ocupacao: Employed people (thousands)
- rendimento: average real income from all jobs, R$ — each period is a ROLLING quarter (e.g. "jun-jul-ago 2026"), Brazil only
- informalidade: Informality rate

**Population:**
- populacao: Population estimate
- densidade: Population density

Examples:
- GDP: indicador="pib"
- IPCA last 12 months: indicador="ipca", periodos="last 12"
- Unemployment by state: indicador="desemprego", nivel_territorial="3"
- List indicators: indicador="listar"

Each indicator returns ONE variable — the one its name says; for another one of the same table (e.g. the year-to-date change) use ibge_sidra with variaveis.

What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps no earlier version.

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest unemployment?", "median informality rate across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="<column label>" (e.g. "Unidade da Federação", "Trimestre") ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.

Use a different tool when:
- Comparing/ranking localities → ibge_comparar
- Census themes → ibge_censo
- One municipality's panel → ibge_cidades

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
- `ibge_localidade`: Returns details of a specific locality by IBGE code.

Features:
- State information (2-digit code)
- Municipality information (7-digit code)
- District information (9-digit code)
- Complete hierarchy (region, mesoregion, microregion)

Examples:
- São Paulo state: codigo=35
- São Paulo city: codigo=3550308
- District: codigo=355030805

This tool returns the full record of ONE locality you already have the code for.
Use a different tool when:
- You have a name and need the code → ibge_municipios (municipalities) or ibge_geocodigo (any level)
- You want to decompose/understand a code's structure → ibge_geocodigo

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown record.
- `ibge_malhas`: Gets geographic meshes (maps) from IBGE in GeoJSON, TopoJSON, or SVG format.

Features:
- Meshes for Brazil, regions, states, municipalities
- Different resolution levels (internal divisions)
- Different quality levels
- Formats: GeoJSON (data), TopoJSON (compact), SVG (image)

Locality types:
- "BR" or "1" = Entire Brazil
- State abbreviation (e.g., "SP", "RJ")
- State code (e.g., "35" for SP)
- Municipality code (7 digits)

Resolution (internal divisions):
- 0 = Outline only
- 2 = States
- 5 = Municipalities

Examples:
- Brazil with states: localidade="BR", resolucao="2"
- São Paulo with municipalities: localidade="SP", resolucao="5"
- SVG format: localidade="BR", formato="svg"

Use a different tool when:
- Thematic meshes (biomes, Legal Amazon, semi-arid, metropolitan regions) → ibge_malhas_tema

Behavior: read-only and idempotent — a live GET against the public IBGE Malhas API. Returns the mesh in the requested format (GeoJSON, TopoJSON, or SVG).
- `ibge_malhas_tema`: Lists what a THEMATIC territorial recorte of Brazil contains: how many features, with which codes and names, and the URL to download its geometry.

Available recortes:
- biomas: the six continental biomes
- amazonia_legal: Legal Amazon boundary
- semiarido: semi-arid area
- costeiro: coastal municipalities
- fronteira: border-strip municipalities
- metropolitana: metropolitan regions
- ride: Integrated Development Regions
- listar: the catalogue itself, without querying the source

Filtering with `codigo`: only the recortes that have a per-feature code accept it — biomas (the biome code) and the two municipality ones, costeiro and fronteira (the 7-digit IBGE municipality code). Ask without `codigo` to see what exists; biome codes come from the source, not from a fixed table.

GEOMETRY IS NOT IN THE RESPONSE, on purpose: one biome polygon alone is over 9 MB. The response carries the attributes plus a canonical WFS URL that returns the recorte with geometry in GeoJSON.

Use a different tool when:
- Administrative meshes WITH geometry (country/region/state/municipality outlines) → ibge_malhas

Behavior: read-only and idempotent — a live GET against the public IBGE Geosserviços WFS (IBGE Geociências), which is a different service from the Malhas API and the only one that publishes these recortes. Returns Markdown plus a typed structuredContent payload.
- `ibge_municipios`: Lists Brazilian municipalities from IBGE.

Features:
- List municipalities by state (using state abbreviation)
- List all municipalities in Brazil (5,570 municipalities)
- Search by municipality name
- Returns 7-digit IBGE code

Examples:
- São Paulo municipalities: uf="SP"
- Search by name: busca="Campinas"
- MG municipalities containing "Belo": uf="MG", busca="Belo"

Use a different tool when:
- Resolve/decode a code at any level (region, state, district), not just municipalities → ibge_geocodigo
- Full details/hierarchy of one locality by code → ibge_localidade
- Neighboring municipalities → ibge_vizinhos

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown table.
- `ibge_nomes`: Queries name frequency and rankings in Brazil (IBGE).

Features:
1. **Name frequency** (tipo='frequencia'):
   - Birth frequency by decade
   - Multiple names separated by comma
   - Filter by sex and locality

2. **Name ranking** (tipo='ranking'):
   - Most popular names
   - Filter by decade, sex, and locality

Available decades: 1930-2010

Examples:
- Frequency of "Maria": tipo="frequencia", nomes="Maria"
- Compare names: tipo="frequencia", nomes="João,José,Pedro"
- 2000s ranking: tipo="ranking", decada=2000
- Female names: tipo="ranking", sexo="F"

Behavior: read-only and idempotent — a live GET against the public IBGE Nomes (Censo) API. Returns a Markdown table.
- `ibge_noticias`: Searches and lists already-published IBGE news articles and press releases.

Use this to find recent IBGE publications or announcements about a survey or topic — when an indicator was released, or news mentioning a term like "censo". Results are sorted newest-first; with no parameters it returns the 10 most recent items.

Parameters:
- busca: free-text term to match (e.g. "PIB", "censo")
- tipo: "release" (official publication of survey results) or "noticia" (general news); omit for both
- de / ate: date range, format DD/MM/AAAA (e.g. de="01/01/2024", ate="31/12/2024")
- destaque: true to return only featured items
- quantidade: how many to return (default 10, max 100); pagina: page number to page through more

Each item returns: title, type (release/news), publication date, editoria (section), related products/surveys, a featured flag, a plain-text summary, and a link to the full article. The header reports the total count and current page.

Examples:
- Latest 10 news: (no parameters)
- Search census: busca="censo"
- 2024 news: de="01/01/2024", ate="31/12/2024"
- Releases only: tipo="release"

Use a different tool when:
- Scheduled/upcoming release dates (not yet published) → ibge_calendario

Behavior: read-only and idempotent — a live GET against the public IBGE Notícias API. Returns a Markdown list.
- `ibge_paises`: Queries international country data via IBGE.

Features:
- List all countries (following UN M49 methodology)
- Country details (area, languages, currency, location) with the latest published value of
  country indicators — by default population, GDP, GDP per capita, HDI and life expectancy
- Pick other indicators with indicadores="<ids or aliases separated by |>"
- Indicator catalog as published by IBGE (34 indicators: economy, population, health,
  environment, networks), with unit and scale
- Search countries by name
- Filter by region/continent

Each indicator value is the most recent one the source publishes for that country, with its year
or period (some are 3- or 5-year ranges like "2021-2023"), as text (it can be "<2.5"), plus unit
and scale (multiplicador) — null when the source has none.

Available regions: americas, europa, africa, asia, oceania

Country codes: Use ISO-ALPHA-2 (e.g., BR, US, AR, PT, JP)

Examples:
- List all: tipo="listar"
- Brazil details: tipo="detalhes", pais="BR"
- Chosen indicators: tipo="detalhes", pais="AR", indicadores="idh|77852"
- Search: tipo="buscar", busca="Argentina"
- Americas countries: tipo="listar", regiao="americas"
- Indicator catalog: tipo="indicadores"

Behavior: read-only and idempotent — a live GET against the public IBGE Países API. Returns Markdown.
- `ibge_pesquisas`: Lists available IBGE surveys and their tables.

Features:
- List all IBGE surveys (Census, PNAD, GDP, etc.)
- Search by name or code
- Show details and tables of a specific survey
- Categorize surveys by theme

Main surveys:
- **Census**: Demographic, Agricultural, MUNIC
- **PNAD Contínua**: Employment, income, education
- **National Accounts**: GDP, investments
- **Economic Surveys**: Industry, Commerce, Services
- **Price Indices**: IPCA, INPC

Examples:
- List all: (no parameters)
- Search population: busca="população"
- PNAD details: detalhes="pnad"

This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades).

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA/Pesquisas API. Returns a Markdown list.
- `ibge_sidra`: Queries SIDRA tables (IBGE's Automatic Recovery System).

SIDRA contains data from IBGE surveys like Census, PNAD, GDP, etc.

Common tables:
- 6579: Population estimates (annual)
- 9514: Census 2022 population
- 200: Census population (1970-2010)
- 4714: Population, territorial area and density (Census 2022)
- 4099: Unemployment rate (PNAD Contínua, quarterly)
- 5436: Average real income (PNAD Contínua, quarterly)
- 1846: Quarterly GDP at current prices (Brazil)
- 5938: Municipal GDP at current prices (annual, down to municipality)
- 6784: Annual GDP and GDP per capita (Brazil)

Territorial levels:
- 1: Brazil
- 2: Region (North, Northeast, etc.)
- 3: State (UF)
- 6: Municipality
- 7: Metropolitan Region

Examples:
- Brazil population 2023: tabela="6579", periodos="2023"
- Population by state: tabela="6579", nivel_territorial="3"
- Census 2022 by municipality: tabela="9514", nivel_territorial="6", localidades="3550308"

What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps no earlier version.

Statistics mode: for **largest/smallest/mean/median/distribution/ranking** questions ("which municipality has the largest population?", "median GDP by state") use estatisticas=true — it computes min/max/mean/median/std-dev/labeled percentiles over ALL data rows BEFORE pagination and returns top/bottom rankings (default 10, cap 100 via topN), so one call answers what would otherwise require paging thousands of records. With agruparPor="<column label>" (e.g. "Unidade da Federação", "Ano") it ranks groups by descending sum, each with its own mini-distribution. Queries mixing several variables auto-group by "Variável" (units differ). SIDRA absence markers ("-", "..", "...", "X") are excluded from n. In this mode pagina/campos/formato are ignored and registros comes empty. Very large queries are refused by the source (since 2026-09-16 SIDRA tables are read through the Aggregates API, whose ceiling is lower than SIDRA's old 100,000-value cap: all municipalities × 12 yearly periods fails, × 8 works) — narrow periodos (e.g. "last 4") or raise nivel_territorial.

ibge_sidra is the low-level engine. Prefer a friendlier wrapper when it fits:
- Census themes (1970–2022) → ibge_censo
- Economic/social time series → ibge_indicadores
- Rank/compare 2–10 localities → ibge_comparar
- One municipality's panel → ibge_cidades
Use ibge_sidra_tabelas and ibge_sidra_metadados to find a table code and its structure before querying.

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
- `ibge_sidra_metadados`: Returns metadata for a specific SIDRA table.

Features:
- General info (name, survey, subject, periodicity)
- Available territorial levels
- Variable list with units
- Classifications and categories
- Available periods

Use this tool to understand table structure BEFORE querying data with ibge_sidra.

Examples:
- Population table metadata: tabela="6579"
- Census 2022 metadata: tabela="9514"
- PNAD unemployment: tabela="4714"

Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown.
- `ibge_sidra_tabelas`: Lists and searches available SIDRA tables.

Features:
- List all SIDRA tables (aggregates)
- Search by table name: every word must match (AND), accents and case ignored, and everyday Portuguese is resolved to the IBGE's own wording (renda→rendimento, desemprego→desocupação, cidade→município, gênero→sexo); when that happens the response says so in notas_vocabulario
- Filter by survey (Census, PNAD, GDP, etc.)
- Shows code and name of each table

SIDRA contains data from various surveys:
- Demographic Census
- PNAD Contínua (employment, income)
- National Accounts (GDP)
- Industrial Survey
- Agricultural Survey

Examples:
- List tables: (no parameters)
- Search population tables: busca="população"
- Census tables: pesquisa="censo"

This is step 1 of the SIDRA workflow: find a table code → ibge_sidra_metadados (structure) → ibge_sidra (query).
For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades.

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns a Markdown table.
- `ibge_vizinhos`: Finds nearby/neighboring municipalities.

Features:
- Search by IBGE code (7 digits) or municipality name
- Returns municipalities in the same mesoregion (proximity approximation)
- Optionally includes population data

Note: Uses mesoregion as geographic proximity proxy.
For exact spatial neighborhood, mesh processing would be required.

Examples:
- By code: municipio="3550308"
- By name: municipio="Campinas", uf="SP"
- With population: municipio="3550308", incluir_dados=true

Note: proximity is approximated by shared mesoregion (not exact spatial adjacency).
For listing/searching municipalities, use ibge_municipios.

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown list.
- `search`: Searches the IBGE (Brazilian official statistics: SIDRA tables, municipalities, known indicators) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).

This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools `search` and `fetch`. Pass one of the returned ids to `fetch` to read the document.
For direct questions and for data (values, series, rankings) prefer the `ibge_*` tools (`ibge_sidra`, `ibge_cidades`, `ibge_indicadores`, `ibge_comparar`…), which return the actual data with provenance — this is a catalog index, not a data query.

Query: natural language or keywords, Portuguese or English; accents and case are ignored.

Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.