Skip to main content
Glama
radar-cnpj-mcp

radar-cnpj-mcp

by wendersoon

Buscar empresas

buscar_empresas
Read-only

Search and list Brazilian companies by CNAE, location, status, size, and capital filters to retrieve CNPJ, address, activity, and contact details with exact total counts.

Instructions

Lista empresas (estabelecimentos) que atendem aos filtros, com CNPJ, razão social, atividade, endereço e contatos cadastrados na Receita. O campo total é a contagem exata de todas as empresas que atendem aos filtros, sem amostragem nem teto; limite e deslocamento só controlam quais delas vêm na lista.

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

NameRequiredDescriptionDefault
meiNoComo tratar Microempreendedores Individuais (MEI).incluir
ufsNoSiglas das UFs, ex.: ["SP", "MG"].
cepsNoPrefixos de CEP, apenas dígitos, ex.: ["13010", "130"].
cnaesNoCódigos CNAE. Com 7 dígitos busca a subclasse exata; com menos dígitos busca por prefixo (ex.: "4520" = toda a classe). Use buscar_cnae para descobrir os códigos.
limiteNoMáximo de empresas retornadas.
portesNoPorte declarado à Receita.
bairrosNoTrechos do nome do bairro (busca parcial).
situacaoNoSituação cadastral. Padrão: ativa.ativa
com_emailNoSomente empresas com e-mail cadastrado.
municipiosNoNomes dos municípios, sem diferenciar maiúsculas e acentos. Combine com ufs para evitar homônimos.
aberta_aposNoData de abertura a partir de (AAAA-MM-DD).
capital_maxNoCapital social máximo em reais.
capital_minNoCapital social mínimo em reais.
ordenar_porNomais_recentes
aberta_antesNoData de abertura até (AAAA-MM-DD).
com_telefoneNoSomente empresas com telefone cadastrado.
deslocamentoNoQuantas empresas pular (paginação).
somente_matrizNoIgnorar filiais.
ocultar_contatos_meiNoOcultar telefone e e-mail de MEIs, que costumam ser os da própria pessoa física. Use ao compartilhar os resultados.
incluir_cnae_secundarioNoTambém considerar empresas que têm o CNAE como atividade secundária.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare a safe read (readOnlyHint=true) on a closed dataset (openWorldHint=false), so the bar is lower, and the description still adds real behavioral value: 'total' has no sampling or cap while limite/deslocamento only slice the returned page. It does not cover pagination cost or rate limits, which would push it to a 5.

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?

Two sentences, zero filler, with the core capability front-loaded and the counterintuitive 'total vs limite' point placed immediately after. Every clause earns its place.

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

Completeness4/5

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

For a 20-parameter tool with no output schema, the description does the essential work: it names the returned fields and explains the one field ('total') an agent could easily misread. It could go further on result volume or how contacts are sourced when ocultar_contatos_mei is off, but it is callable as written.

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 95%, so baseline 3 applies. The description clarifies the limite/deslocamento/total relationship, which is genuinely useful, but adds no meaning for the other 17 parameters (mei, ufs, ceps, cnaes, portes, situacao, capital ranges), all of which rest on the schema.

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 ('Lista empresas (estabelecimentos) que atendem aos filtros') and enumerates the returned fields (CNPJ, razão social, atividade, endereço, contatos). It hints at a distinction from contar_empresas by stressing that 'total' is the exact count, but never names the sibling, so an agent must infer the boundary.

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?

Usage is only implied: a filtered listing tool. Nothing tells the agent when to prefer it over contar_empresas (count only), exportar_csv/baixar_dados (bulk export), or detalhar_empresa (single record). The pagination clarification helps but is not when-to-use guidance.

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