SDK em Python e servidor MCP para o cnpjaberto.com.br, cadastro aberto de empresas brasileiras (CNPJ).
Server has 9 tools with complete input schemas and descriptions. Naming follows verb_noun pattern (lookup_cnpj, list_filiais, search_companies). Descriptions are adequate (100-200 chars) but lack LLM-optimized guidance on when to use each tool vs. alternatives. Parameters have types and descriptions, but lack constraints (enums, ranges, patterns). Output schemas are not documented, LLMs cannot predict response structure for chaining. No error handling guidance visible. All tools are READ_ONLY, reducing risk, but composition could be tighter (e.g., lookup_cnpj returns establishments; list_filiais duplicates that capability).
Estatísticas agregadas de um CNAE: total de empresas, top UFs, top municípios.
Empresas que compartilham um endereço específico. CEP exige 8 dígitos.
Acha empresas que compartilham um contato. Informe email OU (ddd E telefone).
Acha empresas onde uma pessoa aparece como sócia. ``cpf`` em dígitos (parcial é aceito) ajuda a desambiguar homônimos.
Lista as filiais de uma matriz. Opcionalmente filtra por UF.
Registro completo de uma empresa pelo CNPJ. Aceita 8, 12 ou 14 dígitos, com ou sem pontuação. No topo retorna razao_social, capital_social, natureza_juridica, simples, socios. A lista estabelecimentos[] traz matriz e filiais, com situacao_cadastral, endereço e CNAEs.
Output schemas not documented. LLMs cannot predict response structure (fields, types, nested objects) for downstream tool chaining or data extraction. Responses from lookup_cnpj, search_companies, and others are opaque.
Parameter constraints missing. search_companies requires 'query' ≥3 chars and per_page ≤20, but these are only documented in description text, not as JSON Schema constraints (minLength, maxLength, enum). LLMs cannot parse text constraints reliably.
No error handling guidance. Tools raise CnpjAbertoError, NotFoundError, RateLimitError, AuthError but descriptions do not explain recovery steps. LLMs cannot self-correct on 404 or 429 without explicit guidance.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | 2026-07-28+ | v2 |
Estatísticas nacionais: total de empresas ativas, top UFs e CNAEs, faixas de capital social, faixas etárias, histórico de 10 anos.
Snapshot anual: aberturas, fechamentos, série mensal, top CNAEs e UFs, fatia MEI.
Busca empresas por razão social, fantasia ou dígitos do CNPJ. A query precisa de no mínimo 3 caracteres; per_page é limitado a 20.
Composition overlap: lookup_cnpj returns 'estabelecimentos' (establishments/filiais); list_filiais duplicates this. LLMs may call both unnecessarily. Consider consolidating or clarifying when each is preferred.
Descriptions lack LLM-optimized guidance. No 'WHEN to use' hints. E.g., companies_by_owner vs companies_at_same_address vs companies_by_contact are similar discovery tools but lack differentiation. LLMs may pick wrong tool.