IBGE Brasil MCP

Estados do Brasil

ibge_estados

Read-onlyIdempotent

List all 27 Brazilian states from IBGE, filter by region (N, NE, SE, S, CO), and sort by ID, name, or abbreviation. Use it to retrieve state data as a Markdown table.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`regiao`	No	Filtrar por região: N (Norte), NE (Nordeste), SE (Sudeste), S (Sul), CO (Centro-Oeste)
`ordenar`	No	Campo para ordenação dos resultados	nome

Output Schema

TableJSON Schema

Name	Required	Description
`total`	Yes	Total de estados retornados
`estados`	Yes	Lista de estados
`provenance`	Yes	Bloco de proveniência (contrato v1.0): fonte, URL, período, extração e licença
`attribution`	Yes	URLs canônicas das fontes desta resposta (lista de atribuição)

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.0.0Sep 12, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
Changed4 schema fields changedv4.0.0Aug 29, 2026
- removedOutput schema / properties / provenance / properties / data_vintage / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / provenance / properties / data_vintage / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / provenance / properties / license / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / provenance / properties / license / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedv3.3.0Aug 17, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / properties / attribution

Added value: +{
+  "description": "URLs canônicas das fontes desta resposta (lista de atribuição)",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / provenance

Added value: +{
+  "additionalProperties": false,
+  "description": "Bloco de proveniência (contrato v1.0): fonte, URL, período, extração e licença",
+  "properties": {
+    "citation": {
+      "description": "Citação pronta para uso",
+      "type": "string"
+    },
+    "data_vintage": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Período de referência do dado segundo a fonte; null se a fonte não expõe"
+    },
+    "license": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Regime legal do dado"
+    },
+    "retrieved_at": {
+      "description": "Instante real da extração no upstream (ISO-8601, horário de Brasília)",
+      "type": "string"
+    },
+    "source": {
+      "description": "Fonte oficial do dado (API do IBGE consultada)",
+      "type": "string"
+    },
+    "source_url": {
+      "description": "URL canônica que reproduz a consulta",
+      "type": "string"
+    }
+  },
+  "required": [
+    "source",
+    "source_url",
+    "data_vintage",
+    "retrieved_at",
+    "citation",
+    "license"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "estados",
-  "total"
-]New value: +[
+  "estados",
+  "total",
+  "provenance",
+  "attribution"
+]

Changed1 schema field changedv3.0.0Jun 20, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "estados": {
+      "description": "Lista de estados",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "description": "Código IBGE do estado",
+            "type": "number"
+          },
+          "nome": {
+            "description": "Nome do estado",
+            "type": "string"
+          },
+          "regiao": {
+            "description": "Nome da região",
+            "type": "string"
+          },
+          "sigla": {
+            "description": "Sigla da UF",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "sigla",
+          "nome",
+          "regiao"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total": {
+      "description": "Total de estados retornados",
+      "type": "number"
+    }
+  },
+  "required": [
+    "estados",
+    "total"
+  ],
+  "type": "object"
+}

First observedv1.0.0Jan 23, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context — it is a live GET against the public IBGE Localidades API returning a Markdown table — though the return format is partly redundant given an output schema exists.

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

Conciseness5/5

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

Front-loads the one-line purpose, then uses labeled Features/Examples/routing sections that are scannable and waste-free. Every sentence either defines scope, demonstrates a call, or routes to a sibling.

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

Completeness5/5

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

With annotations covering safety, a full input schema with enums, and an output schema covering return values, the description needs only purpose, examples and routing — all of which are present. Nothing an agent needs to call this correctly is missing.

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

Parameters4/5

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

Schema coverage is 100% and both params are enum-constrained with self-documenting values, so the baseline is 3. The description goes beyond the schema by showing the actual wire values in context (regiao="NE", ordenar="sigla"), which reduces the chance of an agent guessing at an invalid code.

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

Purpose5/5

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

Opens with a specific verb+resource ('Lists all Brazilian states from IBGE') and immediately scopes it with the exact count (27) and the two filter/sort axes. The 'Use a different tool when' section names the sibling tools it is not, so an agent can separate it from ibge_municipios and ibge_localidade without opening a schema.

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

Usage Guidelines5/5

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

Explicitly names the alternatives (ibge_municipios for municipalities, ibge_localidade for single-locality details) and the condition that selects each, plus concrete invocation examples for no-param, region-filtered, and sorted calls. Nothing is left to inference.

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