cnpj.ia.br — Brazilian companies (CNPJ)

Buscar empresas

buscar_empresas

Read-only

Busca empresas por filtros. Página de até 20, paginação por meta.next_cursor (repassar em cursor). Custa 1 crédito por empresa retornada; página vazia custa 0. Ferramenta de plano pago: no plano Free responde insufficient_plan.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "buscar_empresas"
  }
}

Input Schema

Name	Required	Description
`uf`	No	UFs por vírgula. Nível 1.
`cep`	No	Prefixo de CEP, 1 a 8 dígitos. Nível 2.
`mei`	No
`cnae`	No	CNAEs de 2, 3, 5 ou 7 dígitos por vírgula. Nível 1.
`nome`	No	Texto contido na razão social ou nome fantasia. Nível 2.
`porte`	No	Portes por vírgula. Nível 1.
`bairro`	No	Bairro exato. Nível 2.
`cursor`	No
`regime`	No	Regimes tributários por vírgula. Nível 2.
`simples`	No
`cep_raio`	No	CEP com coordenada conhecida; exige raio_metros. Nível 3.
`com_site`	No	Exige site; false exige ausência. Nível 2.
`natureza`	No	Naturezas jurídicas por vírgula. Nível 1.
`situacao`	No	Situações cadastrais por vírgula. Nível 1.
`com_email`	No	Exige e-mail; false exige ausência. Nível 2.
`municipio`	No	Municípios IBGE por vírgula. Nível 1.
`explicacao`	No	Texto de gerar_filtro para o usuário; aceito e ignorado, não filtra e não vai à API.
`socio_cnpj`	No	CNPJ de sócio PJ, alfanumérico; aceita pontuação, nunca CPF. Nível 3.
`socio_nome`	No	Texto contido no nome de sócio. Nível 3.
`abertura_de`	No
`capital_max`	No
`capital_min`	No
`com_celular`	No	Exige celular; false exige ausência. Nível 2.
`faturamento`	No	Faixas de faturamento por vírgula, como no perfil full. Nível 3.
`filiais_max`	No	Número máximo de filiais. Nível 2.
`filiais_min`	No	Número mínimo de filiais. Nível 2.
`raio_metros`	No	Raio em metros; exige cep_raio, no mesmo município. Nível 3.
`abertura_ate`	No
`com_telefone`	No	Exige telefone; false exige ausência. Nível 2.
`matriz_filial`	No	Matriz ou filial. Nível 2.
`cnae_secundario`	No	Inclui CNAEs secundários; exige cnae. Nível 2.
`motivo_situacao`	No	Motivos da situação, 2 dígitos por vírgula. Nível 2.
`funcionarios_max`	No	Máximo de funcionários esperados arredondados. Nível 3.
`funcionarios_min`	No	Mínimo de funcionários esperados arredondados. Nível 3.
`situacao_data_de`	No	Data inicial da situação (YYYY-MM-DD). Nível 2.
`municipio_excluir`	No	Municípios IBGE a excluir por vírgula. Nível 2.
`situacao_data_ate`	No	Data final da situação (YYYY-MM-DD). Nível 2.
`situacao_especial`	No	Situações especiais por vírgula. Nível 2.
`natureza_categoria`	No	Categorias de natureza jurídica por vírgula. Nível 2.
`socio_qualificacao`	No	Qualificações de sócio por vírgula. Nível 3.

Schema Changelog

Changes observed during successful MCP inspections.

Changed38 schema fields changedOct 13, 2026

addedInput schema / properties / bairro

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 100,
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Bairro exato. Nível 2."
+}

addedInput schema / properties / cep

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[0-9]{1,8}$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Prefixo de CEP, 1 a 8 dígitos. Nível 2."
+}

addedInput schema / properties / cep_raio

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[0-9]{8}$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "CEP com coordenada conhecida; exige raio_metros. Nível 3."
+}

changedInput schema / properties / cnae / anyOf

Previous value: -[
-  {
-    "pattern": "^[0-9]{2}$|^[0-9]{3}$|^[0-9]{5}$|^[0-9]{7}$",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^([0-9]{2}|[0-9]{3}|[0-9]{5}|[0-9]{7})(,([0-9]{2}|[0-9]{3}|[0-9]{5}|[0-9]{7}))*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / cnae / description

Added value: +"CNAEs de 2, 3, 5 ou 7 dígitos por vírgula. Nível 1."

addedInput schema / properties / cnae_secundario

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Inclui CNAEs secundários; exige cnae. Nível 2."
+}

addedInput schema / properties / com_celular

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Exige celular; false exige ausência. Nível 2."
+}

addedInput schema / properties / com_email

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Exige e-mail; false exige ausência. Nível 2."
+}

addedInput schema / properties / com_site

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Exige site; false exige ausência. Nível 2."
+}

addedInput schema / properties / com_telefone

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Exige telefone; false exige ausência. Nível 2."
+}

addedInput schema / properties / faturamento

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^(ATE_360MIL|DE_360MIL_A_4_8MI|ACIMA_4_8MI)(,(ATE_360MIL|DE_360MIL_A_4_8MI|ACIMA_4_8MI))*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Faixas de faturamento por vírgula, como no perfil full. Nível 3."
+}

addedInput schema / properties / filiais_max

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Número máximo de filiais. Nível 2."
+}

addedInput schema / properties / filiais_min

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Número mínimo de filiais. Nível 2."
+}

addedInput schema / properties / funcionarios_max

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Máximo de funcionários esperados arredondados. Nível 3."
+}

addedInput schema / properties / funcionarios_min

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Mínimo de funcionários esperados arredondados. Nível 3."
+}

addedInput schema / properties / matriz_filial

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "MATRIZ",
+        "FILIAL"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Matriz ou filial. Nível 2."
+}

addedInput schema / properties / motivo_situacao

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[0-9]{2}(,[0-9]{2})*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Motivos da situação, 2 dígitos por vírgula. Nível 2."
+}

changedInput schema / properties / municipio / anyOf

Previous value: -[
-  {
-    "pattern": "^[0-9]{7}$",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^[0-9]{7}(,[0-9]{7})*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / municipio / description

Added value: +"Municípios IBGE por vírgula. Nível 1."

addedInput schema / properties / municipio_excluir

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[0-9]{7}(,[0-9]{7})*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Municípios IBGE a excluir por vírgula. Nível 2."
+}

changedInput schema / properties / natureza / anyOf

Previous value: -[
-  {
-    "pattern": "^[0-9]{4}$",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^[0-9]{4}(,[0-9]{4})*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / natureza / description

Added value: +"Naturezas jurídicas por vírgula. Nível 1."

addedInput schema / properties / natureza_categoria

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[1-5](,[1-5])*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Categorias de natureza jurídica por vírgula. Nível 2."
+}

addedInput schema / properties / nome

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 100,
+      "minLength": 3,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Texto contido na razão social ou nome fantasia. Nível 2."
+}

changedInput schema / properties / porte / anyOf

Previous value: -[
-  {
-    "enum": [
-      "ME",
-      "EPP",
-      "DEMAIS"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^(ME|EPP|DEMAIS)(,(ME|EPP|DEMAIS))*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / porte / description
```
Added value: +"Portes por vírgula. Nível 1."
```

addedInput schema / properties / raio_metros

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 20000,
+      "minimum": 100,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Raio em metros; exige cep_raio, no mesmo município. Nível 3."
+}

addedInput schema / properties / regime

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^(LUCRO_PRESUMIDO|LUCRO_REAL|LUCRO_ARBITRADO|IMUNE|ISENTA)(,(LUCRO_PRESUMIDO|LUCRO_REAL|LUCRO_ARBITRADO|IMUNE|ISENTA))*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Regimes tributários por vírgula. Nível 2."
+}

changedInput schema / properties / situacao / anyOf

Previous value: -[
-  {
-    "enum": [
-      "ATIVA",
-      "SUSPENSA",
-      "INAPTA",
-      "BAIXADA",
-      "NULA"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^(ATIVA|SUSPENSA|INAPTA|BAIXADA|NULA)(,(ATIVA|SUSPENSA|INAPTA|BAIXADA|NULA))*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / situacao / description

Added value: +"Situações cadastrais por vírgula. Nível 1."

addedInput schema / properties / situacao_data_ate

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Data final da situação (YYYY-MM-DD). Nível 2."
+}

addedInput schema / properties / situacao_data_de

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Data inicial da situação (YYYY-MM-DD). Nível 2."
+}

addedInput schema / properties / situacao_especial

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[1-8](,[1-8])*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Situações especiais por vírgula. Nível 2."
+}

addedInput schema / properties / socio_cnpj

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[0-9A-Za-z./-]{14,18}$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "CNPJ de sócio PJ, alfanumérico; aceita pontuação, nunca CPF. Nível 3."
+}

addedInput schema / properties / socio_nome

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 100,
+      "minLength": 3,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Texto contido no nome de sócio. Nível 3."
+}

addedInput schema / properties / socio_qualificacao

Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^[0-9]{1,2}(,[0-9]{1,2})*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Qualificações de sócio por vírgula. Nível 3."
+}

changedInput schema / properties / uf / anyOf

Previous value: -[
-  {
-    "pattern": "^[A-Z]{2}$",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^[A-Z]{2}(,[A-Z]{2})*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / uf / description
```
Added value: +"UFs por vírgula. Nível 1."
```

Changed1 schema field changedSep 21, 2026

addedInput schema / properties / explicacao

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Texto de gerar_filtro para o usuário; aceito e ignorado, não filtra e não vai à API."
+}

First observedSep 20, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the bar is lower. The description adds genuinely useful behavior beyond them: 20-item page size, cursor pagination through meta.next_cursor, per-company credit cost, zero cost for empty pages, and the free-plan failure mode.

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?

Four short sentences, front-loaded with purpose then pagination, cost, and plan gating. Every clause carries operational information an agent needs; nothing is wasted.

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

Completeness3/5

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

For a 40-parameter, zero-required tool with no output schema, the description covers pagination, cost, and plan gating well but says nothing about how the numerous filters interact, mutual requirements (e.g. cep_raio with raio_metros), or result shape. It is minimally adequate rather than complete.

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

Parameters3/5

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

Schema coverage is 83%, above the 80% threshold, so the schema documents the filters itself. The description adds only cursor semantics (repassar em cursor), which is the one param the schema leaves undescribed; the 'Nível 1/2/3' filter tiers are never explained.

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

Purpose4/5

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

States a specific verb and resource ('Busca empresas por filtros') that clearly distinguishes it from the single-record sibling consultar_cnpj. It doesn't explicitly name alternatives like gerar_filtro, but the purpose is unambiguous.

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

Usage Guidelines3/5

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

It gives one strong usage precondition — paid plan required, Free returns insufficient_plan — which tells the agent when the tool is usable. However, it never states when to prefer this over a sibling such as gerar_filtro, and gives no guidance on how filters should be combined.

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

All cnpj.ia.br — Brazilian companies (CNPJ) tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?