Enables discovery and collection of public Facebook profiles and mentions associated with the investigated company and its key people.
Enables discovery and collection of public Instagram profiles and mentions associated with the investigated company and its key people.
Enables discovery and collection of public TikTok profiles and mentions associated with the investigated company and its key people.
Enables discovery and collection of public YouTube profiles and mentions associated with the investigated company and its key people.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@company-investigator-mcp Investigate Nubank by CNPJ and map its partners and related companies."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for public company intelligence, corporate relationships and evidence-based investigation.
An MCP server that lets an LLM client (Claude, or any other MCP-compatible client) look up a Brazilian company by CNPJ or name, walk its corporate network, and pull together public evidence — official registry data, corporate relationships, news, social/LinkedIn profiles, public judicial proceedings and Politically Exposed Person (PEP) checks — into one structured, source-attributed result.
Looking up a company usually means checking half a dozen disconnected sources by hand and manually piecing together who runs it and what else they are involved in. This server does the collection:
Company/CNPJ → Partners → Related companies → Related people
→ News / LinkedIn / public profiles → Public proceedings → PEP
→ Relationship graph → Structured investigation (read in pages by the client)The server collects and structures the evidence; it does not interpret it. Deciding what to dig into, cross-checking sources and writing the final analysis is the job of the MCP client / AI agent (Claude, a local Qwen, …). There is deliberately no LLM inside this server.
MCP Client / AI Agent → Company Investigator MCP → structured investigation
→ MCP Client / AI Agent → analysisRelated MCP server: mcp-fiscal-brasil
Company intelligence — official registry data (CNPJ, razão social, nome fantasia, status) via BrasilAPI.
Corporate relationships — discovers other companies a partner is associated with, and expands the network to a configurable depth (0–2).
People intelligence — partners, administrators and LinkedIn key people (CEO, founders, directors and other leadership roles).
News and public sources — public mentions of the company, each with title, URL, source and confidence.
LinkedIn / social profiles — company page and key people on LinkedIn, plus Instagram, Facebook, YouTube, X/Twitter and TikTok.
Public proceedings — public mentions of judicial processes, with official confirmation by process number where possible.
PEP identification — checks partners against the official Politically Exposed Person registry, distinguishing a confirmed match from a homonym.
Relationship graph — companies and people connected by typed, sourced
edges (socio_de, relacionada_por_socio), without duplicating entities.
Large investigations without blowing the client's context — the result is handed over as a small index plus paginated sections. Nothing is truncated.
Pick one; all of them run the same Python server over stdio.
Method | Command | Requires |
uvx (recommended) |
| uv — downloads Python 3.14 automatically if missing |
npx |
| Node.js 18+ and uv |
pip |
| Python 3.14+ |
company-investigator-mcp --version # prints 1.0.0The older company-investigator command is kept as an alias.
About the npm package: it is only a launcher, with no server code. It finds
uvx and runs uvx company-investigator-mcp@<its own version>, so npm 1.0.0
always runs exactly PyPI 1.0.0 — never @latest. Pin it the usual way
(npx -y company-investigator-mcp@1.0.0) to lock a version. If your MCP client
cannot find uvx (desktop apps often start with a minimal PATH), the launcher
also looks in uv's default install directories; you can set UVX_PATH to the
uvx executable explicitly.
buscar_informacoes_publicas)Installing the package does not download a browser — no large downloads or
side effects at install time. The buscar_informacoes_publicas tool uses
browser automation (Playwright) and needs Chromium, installed once:
uvx --from company-investigator-mcp playwright install chromium # uvx / npx users
playwright install chromium # pip (same environment)
uv run playwright install chromium # from a git cloneOn Linux, add --with-deps if system libraries are missing. Every other tool
works without it; if Chromium is missing, this tool returns an error with exactly
the commands above. No restart is needed after installing.
git clone https://github.com/CalebePrates/company-investigator-mcp.git
cd company-investigator-mcp
uv sync
uv run company-investigator-mcpNo environment variable is required to start the server — ping,
buscar_empresa and buscar_informacoes_publicas never depend on them. Without a
key, the parts of investigar_empresa that need it (search discovery, official
process confirmation, PEP checks) return an empty result with an explanation in
limitacoes instead of failing.
Variable | Enables | Where to get it |
| News, social profiles, LinkedIn, corporate network discovery, name search | Free tier at serper.dev — 2,500 queries, no card |
| Official confirmation of a judicial process by its number (CNJ) | Public shared key published at the DataJud wiki — no personal signup needed |
| Official PEP (Politically Exposed Person) verification | Free email signup at Portal da Transparência |
.env.example lists them. The server does not auto-load .env
files: pass the variables through your MCP client's env block (below) or export
them in the shell that launches the server.
mcpServers JSONMost clients (Claude Desktop's claude_desktop_config.json, Cursor, Windsurf,
…) accept this shape. With uvx:
{
"mcpServers": {
"company-investigator": {
"command": "uvx",
"args": ["company-investigator-mcp"],
"env": {
"SEARCH_PROVIDER": "serper",
"SEARCH_API_KEY": "your-serper-key",
"DATAJUD_API_KEY": "the-public-datajud-key",
"PORTAL_TRANSPARENCIA_API_KEY": "your-cgu-key"
}
}
}
}With npx, replace the command:
"command": "npx",
"args": ["-y", "company-investigator-mcp"]With pip, use "command": "company-investigator-mcp" (or its absolute path
inside your virtualenv) and no args. All env entries are optional.
If the client reports that uvx was not found, use its absolute path
(which uvx / where uvx) as command.
claude mcp add company-investigator \
-e SEARCH_PROVIDER=serper -e SEARCH_API_KEY=your-serper-key \
-- uvx company-investigator-mcpor add the JSON above to .mcp.json at your project root. Reload/reconnect the
MCP servers after changing the configuration or the variables.
If the server runs inside WSL while the client runs on Windows:
{
"mcpServers": {
"company-investigator": {
"command": "wsl.exe",
"args": ["-e", "bash", "-lc", "uvx company-investigator-mcp"]
}
}
}bash -lc is a non-interactive login shell: export the API keys in ~/.profile,
not ~/.bashrc — Ubuntu's default ~/.bashrc returns early for non-interactive
shells, so anything exported there is silently ignored.
Tool | Purpose |
| Health check |
| Official registry data for one CNPJ |
| Title and visible text of a public web page (needs Chromium) |
| Full investigation; returns an |
| The index again (also for any related company's id) |
| One page (max 50 items) of a section |
Resource | Same as the two tools above, as an MCP Resource ( |
Every tool self-describes its input schema, so the client discovers them via
tools/list. Invalid input (bad CNPJ check digits, malformed URL, unknown
section, page out of range, unknown or expired investigation_id) returns a
readable tool error.
ping:
// input
{}
// output
{ "status": "ok", "message": "MCP funcionando" }buscar_empresa — accepts the CNPJ with or without punctuation:
// input
{ "cnpj": "19.131.243/0001-97" }
// output
{
"cnpj": "19131243000197",
"razao_social": "OPEN KNOWLEDGE BRASIL",
"nome_fantasia": "REDE PELO CONHECIMENTO LIVRE",
"situacao": "ATIVA"
}buscar_informacoes_publicas:
// input
{ "url": "https://example.com/" }
// output
{ "url": "https://example.com/", "titulo": "Example Domain", "texto": "Example Domain This domain is for use in ..." }investigar_empresa — a CNPJ or a company name; profundidade is how many levels
of the corporate network to expand (default 1, max 2). An ambiguous name returns
candidatos instead of guessing. The answer is a small index (field names
exact, values illustrative):
// input
{ "identificador": "19.131.243/0001-97", "profundidade": 1 }
// output
{
"investigation_id": "3f9c0d…",
"identificador_usado": "19.131.243/0001-97",
"empresa": { "cnpj": "...", "razao_social": "...", "situacao": "ATIVA" },
"processos_status": { "status": "realizada", "motivo": null },
"secoes": [
{ "nome": "socios", "tipo": "lista", "total_itens": 4 },
{ "nome": "noticias", "tipo": "lista", "total_itens": 45 },
{ "nome": "empresas_relacionadas", "tipo": "lista", "total_itens": 2 }
]
}obter_secao_investigacao — read the content page by page:
// input
{ "investigation_id": "3f9c0d…", "secao": "noticias", "pagina": 1, "tamanho_pagina": 20 }
// output
{
"secao": "noticias", "pagina": 1, "tamanho_pagina": 20,
"total_itens": 45, "total_paginas": 3,
"itens": [
{ "titulo": "...", "url": "https://...", "fonte": "...", "resumo": "...",
"consultado_em": "...", "data_publicacao": null, "confianca": "media" }
]
}A real investigation with a corporate network can run past 100,000 characters — more than a single tool response should carry. So collection and delivery are separate: the server keeps the complete result in memory and the client pulls it in pages. Paging through every section listed in the index returns 100% of what was collected.
Sections: empresa, candidatos, socios, pessoas_chave, linkedin,
redes_sociais, noticias, contatos, processos_confirmados,
processos_referencias, processos_status, movimentos_processuais, fontes,
empresas_relacionadas, pessoas_relacionadas, relacionamentos,
possiveis_relacoes_familiares, peps, limitacoes.
Related companies are references, not nested copies. Each item of
empresas_relacionadas holds the relationship (origem_socio, fonte,
confianca) plus that company's own investigation_id; walk it recursively
with the same tools. A company reached through several partners appears once,
with one socio_de edge per partner.
A process's movements (an old lawsuit can have thousands) live in
movimentos_processuais, each item pointing back to its numero_processo;
processos_confirmados only carries total_movimentos.
Memory only, no database. The store lives in the server process, is capped
at 500 records (the least recently used whole investigation tree is discarded
first) and disappears when the server restarts. An unknown or expired
investigation_id gets a clear error; just run investigar_empresa again.
Every item preserves, when available: source (BrasilAPI, Serper, DataJud,
Portal da Transparência, LinkedIn via search), URL, discovery date
(consultado_em), publication date, confidence (alta / media /
baixa — how strong the match is, never a claim of certainty) and, for possible
family relationships, the evidence itself (a shared surname token, or the
snippet that mentioned a relationship explicitly).
Judicial proceedings separate processos_confirmados (official DataJud data,
retrieved by process number) from processos_referencias (a public mention, not
confirmed). No official, public, CAPTCHA-free source allows searching processes by
party (CNPJ/CPF/name), and DataJud never discloses parties — so confirming a
process number is not the same as confirming who is involved in it.
This project:
uses only publicly available information;
never accesses private data;
never bypasses CAPTCHA, anti-bot mechanisms, authentication, paywalls or rate limits;
never treats a matching name as proof of identity;
never treats a matching surname as proof of a family relationship — it is only ever a possible relationship, with low confidence unless a public source mentions an explicit kinship term;
never interprets appearing in a judicial process as guilt or wrongdoing;
treats PEP matches with explicit caution: a name match alone never becomes a confirmed PEP — that requires the visible digits of the partner's masked CPF to match the official record; otherwise the result is a possible homonym;
never fabricates a fact when a source cannot verify it — it reports the
limitation instead (limitacoes).
Known limitations: search-based discovery depends on what the search provider indexes, so the corporate network and news coverage are not exhaustive; free API tiers have quotas; data is only as current as each public source.
You are responsible for using the results lawfully, including under Brazil's LGPD (Lei Geral de Proteção de Dados) and each source's terms of use. Results are leads to verify, not conclusions.
Clean Architecture with an explicit Ports & Adapters boundary:
MCP Client
↓
MCP Tools (interface/mcp_server/tools — validate input, call a use case, shape output)
↓
Use Cases (application/use_cases — orchestrate a single MCP-level operation)
↓
Services (application/services — identification, partner/company/news/social/
LinkedIn/process/PEP/family-relationship search, investigation storage)
↓
Ports (domain/ports — small ABCs: one capability each)
↓
Adapters (infrastructure — concrete implementations of a port)
↓
External Sources (BrasilAPI, Serper, DataJud, Portal da Transparência, Playwright)The dependency rule always points inward: domain depends on nothing external
(not even Pydantic); application depends only on domain abstractions;
infrastructure and interface depend on domain. Every external capability
sits behind a small port, so swapping Serper for another search provider means
writing one new adapter class. See CLAUDE.md for the full
rationale and how each tool's flow works end to end.
src/company_investigator/
├── domain/ # entities, value objects (Cnpj), ports
├── application/ # use cases and services
├── infrastructure/ # BrasilAPI, Playwright, Serper, DataJud, Portal da Transparência,
│ # in-memory investigation store
└── interface/mcp_server/
├── server.py # composition root
├── tools/ # the six MCP tools
└── resources/ # investigation://{investigation_id}/{secao}
npm/ # npx launcher (Node, no dependencies, no server logic)uv sync
uv run pytest # test suite (no network, no browser, no paid API)
uv run ruff check . # lint
uv run ruff format . # format
(cd npm && npm test) # npm launcher tests
uv build # sdist + wheel in dist/Every behavior is written test-first. tests/unit covers domain and application
logic with fakes for every port; tests/integration exercises the real
MCPServer composition, including one test that launches the server as a child
process and talks to it over stdio with the official MCP client. CI runs all of
this on every push and pull request.
Release process and versioning policy: RELEASING.md. Changes: CHANGELOG.md.
Persistence (database, cache, history). The only state is the in-memory investigation store, which lives and dies with the server process.
An LLM inside the server. Analysis is the MCP client's / AI agent's job.
MIT © Calebe Prates
Busca dados cadastrais reais de uma empresa a partir do CNPJ, consultando a BrasilAPI (fonte publica e oficial de dados de CNPJ da Receita Federal). Parametro 'cnpj' (string, obrigatorio): aceita com ou sem pontuacao, por exemplo '12.345.678/0001-90' ou '12345678000190'. Retorna um objeto com 'cnpj' (normalizado, apenas digitos), 'razao_social', 'nome_fantasia' e 'situacao'. Erros possiveis: CNPJ vazio, com letras, com quantidade errada de digitos, com digitos verificadores matematicamente invalidos, falha ao consultar a BrasilAPI, ou CNPJ valido porem sem empresa cadastrada.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it identifies the data source and its authority, states that the output CNPJ is normalized, lists the returned fields, and enumerates specific failure modes (empty, alphabetic, wrong length, invalid check digits, upstream failure, unregistered CNPJ). It stops short of noting rate limits, authentication needs, or latency characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one dense paragraph of four sentences, front-loaded with purpose, then parameter, return shape, and error modes. Every sentence carries information, though the error enumeration makes it slightly long for a single-parameter lookup.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup, this covers purpose, input format, output fields, and error conditions, which is close to complete. Since an output schema already exists, the return-field enumeration is partly redundant, and it omits operational details such as whether authentication is needed. Nothing critical for a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it declares the parameter required, its type (string), that punctuation is optional, and gives concrete examples in both formats ('12.345.678/0001-90' and '12345678000190'). It also documents the normalization behavior applied on the way out, which the schema does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Busca dados cadastrais reais de uma empresa a partir do CNPJ') and even names the upstream source (BrasilAPI/Receita Federal), so an agent knows exactly what it retrieves. It does not, however, distinguish itself from plausible siblings such as 'investigar_empresa' or 'buscar_informacoes_publicas', which sound closely related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over the overlapping siblings ('investigar_empresa', 'buscar_informacoes_publicas'), nor any stated prerequisites or exclusions. The description only explains the mechanics of a single call, leaving routing entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Abre uma URL publica com um navegador headless e extrai informacoes basicas da pagina: titulo e texto visivel. Nao interage com formularios nem executa acoes na pagina, apenas le o conteudo apos o carregamento. Parametro 'url' (string, obrigatorio): precisa ser uma URL http/https valida e publicamente acessivel. Retorna um objeto com 'url', 'titulo' (pode ser nulo se a pagina nao tiver a tag ou ela estiver vazia) e 'texto' (texto visivel extraido da pagina, sem scripts/estilos). Erros possiveis: URL invalida, timeout ao carregar a pagina, ou falha de navegacao.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the headless-browser read-only behavior, that no forms/actions are executed, that 'titulo' can be null, and enumerates failure modes (invalid URL, timeout, navigation failure). It omits auth/rate-limit or redirect/cookie handling details, so not a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then constraints, then return shape and errors; every sentence is substantive. The return-value sentence is partly redundant given an output schema exists, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter fetch tool with an output schema, the description covers what it does, what it refuses to do, the input constraint, the nullability of 'titulo', and the error surface. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate and it does: it marks 'url' as required and adds a hard constraint beyond the bare 'string' type (valid, publicly accessible http/https URL). It does not give format examples or query-string guidance, so 4 rather than 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('abre uma URL publica com um navegador headless e extrai informacoes basicas') and scopes exactly what is extracted (titulo e texto visivel). This is clearly distinguishable from siblings like ping or buscar_empresa without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly frames the operating context: it only reads loaded content and explicitly does not interact with forms or execute page actions, plus the url must be publicly accessible http/https. It does not name an alternative tool or an explicit when-not-to-use-this case, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Investiga uma empresa a partir de um CNPJ ou de um nome (razao social/nome fantasia), combinando dados cadastrais oficiais (BrasilAPI) com buscas publicas (via uma Search API) por noticias, perfis em redes sociais (LinkedIn, Instagram, Facebook, YouTube, X/Twitter, TikTok), pessoas-chave no LinkedIn, processos judiciais publicos, rede societaria (outras empresas dos socios) e verificacao de PEP. Parametro 'identificador' (string, obrigatorio): um CNPJ (com ou sem pontuacao) ou um nome de empresa. Parametro 'profundidade' (inteiro, padrao 1, maximo 2): quantos niveis de 'socio -> nova empresa' sao expandidos; 0 investiga so a empresa pedida. IMPORTANTE: esta tool NAO devolve os dados completos da investigacao — ela coleta e guarda tudo, e devolve um INDICE pequeno: um 'investigation_id' e, para cada secao (socios, noticias, empresas_relacionadas, processos, peps, etc.), quantos itens existem. Nenhum dado e descartado; para ler o conteudo de uma secao (com todos os seus itens, paginado se for grande), use a tool 'obter_secao_investigacao' com esse investigation_id, ou o resource MCP 'investigation://{investigation_id}/{secao}'. Empresas relacionadas tambem tem sua propria sub-investigacao completa, acessivel pelo investigation_id que aparece dentro da secao 'empresas_relacionadas' — percorra recursivamente para ver 100% da rede.
| Name | Required | Description | Default |
|---|---|---|---|
| profundidade | No | ||
| identificador | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does so well: it discloses the non-obvious return behavior (small index of investigation_id plus per-section counts), that nothing is discarded, that related companies spawn sub-investigations, and how to read them. This is exactly the behavioral context an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and identifier semantics, and every sentence carries information. It is somewhat dense and long, with minor repetition about section reading, but nothing is wasted given the unusual index-return design.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a rich output schema existing, the return value here is non-obvious (an index, not data), and the description explains it fully along with pagination, resource access, and recursive expansion. Nothing an agent needs to invoke or consume the result correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: 'identificador' is required and accepts CNPJ with or without punctuation or a company name; 'profundidade' is an integer defaulting to 1, max 2, and 0 means only the requested company. Semantics of the depth levels are spelled out beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (investiga) and resource (empresa) plus the accepted identifiers (CNPJ or nome), and enumerates the data domains it aggregates. It also explicitly distinguishes itself from the sibling 'obter_secao_investigacao', so an agent can route between them without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says this tool does NOT return the full data and directs the agent to 'obter_secao_investigacao' or the MCP resource for reading sections, including the recursive path through sub-investigations. When-to-use and the alternative are both stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera novamente o indice (resumo estrutural) de uma investigacao ja criada por 'investigar_empresa', usando seu 'investigation_id'. Util para re-consultar quantos itens cada secao tem sem precisar refazer a investigacao. Erro se o investigation_id nao existir.
| Name | Required | Description | Default |
|---|---|---|---|
| investigation_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the error behavior ('Erro se o investigation_id nao existir') and the retrieval/non-destructive nature is implied by 'Recupera'. However, it says nothing about permissions, idempotency, or caching of the index, leaving behavioral gaps for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the action and resource, followed by the use case and the error condition. No filler or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not required, and the description correctly avoids it. With a single required parameter, its provenance documented, and the error case covered, an agent has what it needs to call the tool correctly; only permission/auth context is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% - investigation_id has no schema-level description - so the description must compensate. It does so by stating the parameter's origin ('usando seu investigation_id', i.e. the value obtained from 'investigar_empresa') and the error if it does not exist, which is meaningful context beyond the bare string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Recupera o indice (resumo estrutural) de uma investigacao'), and names the sibling that produced the investigation ('investigar_empresa'). The parenthetical clarifies what an 'indice' is, making the purpose unambiguous. It does not, however, explicitly contrast itself with the close sibling 'obter_secao_investigacao'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear use case ('re-consultar quantos itens cada secao tem sem precisar refazer a investigacao') which implies when to call it instead of re-running 'investigar_empresa'. It also states the failure condition. It stops short of naming 'obter_secao_investigacao' as the alternative for drilling into a single section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera o conteudo completo (paginado) de UMA secao de uma investigacao criada por 'investigar_empresa', usando o 'investigation_id' que essa tool devolveu. Nenhum dado e descartado: percorrendo todas as paginas de uma secao (veja 'total_paginas' na resposta) voce chega a 100% do que foi coletado. Parametro 'secao' (obrigatorio), uma das: empresa, candidatos, socios, pessoas_chave, linkedin, redes_sociais, noticias, contatos, processos_confirmados, processos_referencias, processos_status, movimentos_processuais, fontes, empresas_relacionadas, pessoas_relacionadas, relacionamentos, possiveis_relacoes_familiares, peps, limitacoes. Para a secao 'empresas_relacionadas', cada item traz seu proprio 'investigation_id' — use-o para percorrer a sub-investigacao completa daquela empresa relacionada (recursivamente, se ela tambem tiver empresas relacionadas). Os movimentos de cada processo confirmado ficam na secao 'movimentos_processuais' (cada item traz o 'numero_processo'), nao dentro de 'processos_confirmados'. Parametros 'pagina' (padrao 1) e 'tamanho_pagina' (padrao 20, maximo 50) controlam a paginacao. Erro se o investigation_id nao existir (ou tiver expirado da memoria do servidor) ou a secao for invalida.
| Name | Required | Description | Default |
|---|---|---|---|
| secao | Yes | ||
| pagina | No | ||
| tamanho_pagina | No | ||
| investigation_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that nothing is discarded, exposes pagination defaults and the max page size, and states error conditions (nonexistent investigation_id or one expired from server memory). It does not describe auth requirements or rate limits, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded and the dense single paragraph is largely justified by the section enumeration and pagination/recursion rules. Every sentence carries information, though the block could be broken up for scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained; given that, the definition covers the section taxonomy, pagination controls, recursion into related companies, and error conditions. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description compensates fully: it enumerates all 19 valid values of the required 'secao' parameter (which the schema leaves as a bare string), and explains 'pagina' (default 1), 'tamanho_pagina' (default 20, max 50), and the origin of 'investigation_id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it retrieves the full paginated content of ONE section of an investigation. It also ties itself to the sibling tool that produced the id ('investigar_empresa'), so an agent can place it in the workflow without opening sibling schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the entry condition (use the investigation_id returned by 'investigar_empresa') and the pagination walk needed to reach 100% of the data. It also resolves ambiguity about where process movements live ('movimentos_processuais', not 'processos_confirmados') and how to recurse into 'empresas_relacionadas'. It stops short of naming explicit alternative tools or when-not-to-use cases, so it is not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifica se o servidor MCP esta operante.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It correctly conveys that the call is a non-mutating liveness check, but adds nothing about response shape, latency, or failure semantics — though for a ping the behavioral surface is inherently small and the output schema covers returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the purpose with zero filler. Nothing could be removed without losing the meaning, and nothing needs to be added for a tool this simple.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the return value needn't be explained, and with zero parameters there is no input surface to cover. The description is essentially complete for a liveness probe, missing only explicit usage timing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The empty schema is consistent with the description, which implies no input is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it verifies whether the MCP server is operational, which is a clear health-check purpose. It does not differentiate from siblings, but the siblings (buscar_empresa, investigar_empresa, etc.) are all domain search tools, so no real overlap exists to disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this is a connectivity/liveness probe, but the description never says when to call it (e.g., before a batch of other calls) or when not to. For a zero-parameter ping the omission is minor, but it is still inference rather than guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0buscar_empresabuscar_informacoes_publicasinvestigar_empresaobter_indice_investigacaoobter_secao_investigacaopingScored across 6 tools
Most tools have clearly distinct purposes, but buscar_empresa (single CNPJ lookup) overlaps with investigar_empresa, which also fetches cadastral data. The obter_indice_investigacao vs obter_secao_investigacao pair is related but the descriptions clearly differentiate index vs section retrieval, so an agent can pick correctly.
Tools follow a consistent Portuguese verb_noun pattern (buscar_*, obter_*, investigar_*), which is predictable and readable. The lone exception is 'ping', an English outlier, though it is a conventional health-check verb.
Six tools is well-scoped for a company-investigation server. Each tool (health check, CNPJ lookup, URL fetch, run investigation, fetch index, fetch section) earns its place without redundancy.
The investigation lifecycle is well covered: start an investigation, retrieve its index, and page through any section. Minor gaps exist, such as no tool to list previously created investigations or clean them up, but core workflows have no dead ends.
Brazilian company and person data by CNPJ/CPF: registry, partners, tax status, sanctions, lawsuits.
Brazilian business data for AI agents. Public company dossiers by CNPJ.
Free Brazilian CNPJ lookup (legal name, status, partners) + lawsuit discovery. Public data, no login
Identifies the ultimate beneficial owner of a company or person from the CNPJ or CPF, for compliance