Brazil's open CNPJ registry: filter and count companies by sector, place, size, MEI, partners.
Scored across 8 tools
Most tools target a distinct resource+action: get_company (single CNPJ), search_companies (filtered list), count_companies (aggregates), list_partners (company→people), search_partners (person→companies), lookup_codes (reference tables), dataset_info (metadata). Two overlaps remain: companies_at_address largely duplicates search_companies with a 'cep' filter, and list_partners vs search_partners are inverse queries that the names alone don't clarify. Descriptions disambiguate the partner pair reasonably well, but the address tool feels like a redundant narrowing of search_companies.
All names are snake_case and the majority follow verb_noun (count_companies, get_company, list_partners, lookup_codes, search_companies, search_partners). Two deviate into bare noun phrases (dataset_info, companies_at_address), which is a minor inconsistency rather than a confusing one. The pattern is still predictable enough for an agent to guess names.
Eight tools is well within the sweet spot for a read-only registry API. Each tool maps to a meaningful query mode (lookup, search, count, partners, codes, metadata) with no filler tools. The surface is broad without bloating.
Coverage is strong for a read-only domain: single-record lookup, filtered search with pagination and ordering, aggregation with group_by, partner traversal in both directions, code-table resolution and dataset metadata. Minor gaps: name-based company search requires name_contains plus a uf, so there is no standalone fuzzy/exact company-name lookup, and no batch/multi-CNPJ retrieval. These are workaroundable but would be hit in practice.
Establishments registered at one address, by CEP (8 digits), optionally narrowed by street text, number, municipio or uf. Use it to find companies sharing an address.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | ||
| cep | No | ||
| limit | No | ||
| numero | No | ||
| offset | No | ||
| situacao | No | ativa | |
| municipio | No | ||
| logradouro_contains | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it only discloses one trait (CEP must be 8 digits). It is silent on the default situacao='ativa' filter that silently restricts results to active companies, on pagination semantics for limit/offset, and on permissions or result ordering — all material for correct invocation.
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?
Two tight sentences with no filler, and the resource definition is front-loaded ahead of the use case. The inline '(8 digits)' detail earns its place as a format constraint; the parenthetical field list is dense but readable.
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?
Output schema exists, so return values need not be described, which the definition correctly omits. But for an 8-parameter tool with zero annotations and zero schema coverage, the description is only partially complete — pagination and the default active-status filter are unaddressed and could cause unexpected empty results.
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% across 8 parameters, so the description must compensate. It does cover five of them meaningfully (cep format, logradouro_contains as 'street text', numero, municipio, uf), but leaves limit, offset, and especially situacao — which defaults to 'ativa' with no explanation — completely undocumented.
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+resource combination ('Establishments registered at one address') and names the exact scoping keys (CEP, street, number, municipio, uf). It distinguishes itself from generic siblings like search_companies and count_companies by narrowing to a single address, though it never names those siblings explicitly.
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?
The second sentence gives an implied use case ('Use it to find companies sharing an address'), which is clear enough for the primary scenario. However, it offers no when-not guidance and never explains how this differs from calling search_companies with an address filter, leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count companies or establishments, optionally grouped by one or two fields. Filters (all optional, combined with AND): cnae (CNAE code or prefix, e.g. '4711' or '47', list ok; add include_secondary to also match secondary activities), cnae_secao (letter A-U), uf, municipio (name as in Receita, accents ignored), municipio_codigo, situacao (ativa, baixada, suspensa, inapta, nula), matriz_only, porte (micro = ME, pequeno = EPP, demais, nao_informado), natureza_juridica (code prefix like '2062' or text like 'sociedade limitada'), capital_min/capital_max (BRL), opened_from/opened_to (data_inicio_atividade, YYYY-MM or YYYY-MM-DD), closed_from/closed_to (data da baixa), mei, simples (true/false), name_contains (razao social or nome fantasia; 3-256 characters and uf required), cep, partner_name (a partner's name contains this text). group_by options: uf, municipio, cnae_principal, cnae_divisao, cnae_secao, natureza_juridica, porte, situacao, ano_abertura, mes_abertura, ano_baixa, mes_baixa, mei, simples, matriz_filial, motivo_situacao. unit='estabelecimentos' (default) counts every CNPJ incl. filiais; unit='empresas' counts companies (matriz only). metric='sum_capital' sums declared capital social (BRL, companies only). Examples: MEIs opened per month in a state, active agro companies per municipality, closures by year.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | ||
| cep | No | ||
| mei | No | ||
| cnae | No | ||
| unit | No | estabelecimentos | |
| limit | No | ||
| order | No | count_desc | |
| porte | No | ||
| metric | No | count | |
| simples | No | ||
| group_by | No | ||
| situacao | No | ||
| closed_to | No | ||
| municipio | No | ||
| opened_to | No | ||
| cnae_secao | No | ||
| capital_max | No | ||
| capital_min | No | ||
| closed_from | No | ||
| matriz_only | No | ||
| opened_from | No | ||
| partner_name | No | ||
| name_contains | No | ||
| municipio_codigo | No | ||
| include_secondary | No | ||
| natureza_juridica | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does substantial work: it defines unit semantics ('estabelecimentos' counts every CNPJ including filiais; 'empresas' is matriz only), the metric='sum_capital' behavior (BRL, companies only), and matching quirks like prefix CNAE matching, include_secondary, and accents being ignored. Gaps remain around pagination/limit behavior and auth or rate limits, which are not mentioned.
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 purpose and filter list are front-loaded and every clause carries information an agent needs given the 0% schema coverage. It is presented as one dense semicolon-delimited run-on rather than scannable grouped sections, which slightly hurts navigability across 26 parameters but wastes no words.
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 no explanation, and the description covers filters, the AND-combination rule, all group_by options, unit and metric semantics, and worked examples. For a 26-parameter, zero-required-parameter aggregation tool this is complete enough for correct invocation, with only pagination semantics left implicit via schema defaults.
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 entirely for 26 parameters, and it largely does: it gives accepted values and formats for nearly every filter (cnae prefixes, 'letter A-U', situacao enums, porte labels, natureza_juridica prefixes, date formats YYYY-MM/YYYY-MM-DD, name_contains 3-256 char + uf requirement). Only limit, order, and cep lack semantic detail, which is a minor residue against an otherwise exhaustive list.
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 opens with a specific verb and resource: 'Count companies or establishments, optionally grouped by one or two fields.' That aggregation framing distinguishes it in practice from listing siblings like search_companies or get_company, but no sibling is named, so an agent must infer the boundary rather than being told.
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 well-contextualized through the closing examples ('MEIs opened per month in a state, active agro companies per municipality, closures by year'), which map concrete analytical questions onto the tool. However, it never explicitly states when to use count_companies versus search_companies, and there are no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What data is loaded: source, snapshot month, row counts, field meanings and caveats. Call first if unsure what the tools cover.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does meaningful work: it discloses what the response contains (source, snapshot month, row counts, field meanings, caveats). As a zero-parameter tool, mutation/auth/rate-limit concerns are largely moot, so this is close to adequate, though it says nothing about format or freshness beyond the snapshot month.
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?
Two short sentences, zero filler, with the content enumeration front-loaded ahead of the conditional call guidance. Every clause 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?
There is no output schema, so the description must cover return values, and it enumerates them well. Combined with zero parameters and no annotations, an agent has enough to call it correctly; only the exact response shape/format remains unspecified, which is a minor gap.
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 the baseline is 4. There is no parameter surface for the description to clarify, and it correctly focuses on return content instead.
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 resource (dataset metadata) and enumerates exactly what it returns: source, snapshot month, row counts, field meanings and caveats. The verb is implicit ('What data is loaded') rather than an explicit action, but the scope is unmistakable and clearly distinct from the company/partner query siblings.
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?
It gives an explicit trigger: 'Call first if unsure what the tools cover.' That is real, actionable guidance for when to reach for this tool over the sibling search/list tools. It stops short of stating when not to call it, which keeps it out of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One company by CNPJ (14 digits, with or without punctuation; or the 8-digit root to get the matriz): registration, company data, Simples/MEI, address and contacts, secondary CNAEs, partners (with names), and how many establishments the company has.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses input flexibility (punctuation optional, 8-digit root resolves to the matriz) and enumerates the returned data blocks, but says nothing about not-found/error behavior, permissions, or rate limits.
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 dense sentence that front-loads the selector (CNPJ and its accepted forms) before listing return contents. Every clause carries information, though the trailing enumeration of data domains is long and could be trimmed.
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?
There is no output schema, so the description's enumeration of returned fields (registration, Simples/MEI, address, CNAEs, partners, establishment count) is genuinely necessary and present. The only gap for a one-parameter read tool is the absence of error/not-found semantics and sibling routing.
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% and the single parameter is completely undocumented in the schema, so the description must compensate. It does so well, specifying the 14-digit CNPJ format, punctuation tolerance, and the 8-digit root shortcut that changes the result to the matriz.
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 resource (one company) retrieved by a specific identifier (CNPJ) and enumerates the data domains returned, which lets an agent distinguish a single-record lookup from bulk siblings like search_companies or count_companies. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.
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: pass a 14-digit CNPJ for a company or an 8-digit root to get the matriz. There is no explicit when-to-use/when-not guidance and no routing to alternatives such as search_companies when the exact CNPJ is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partners (socios) of one company by CNPJ root or full CNPJ: names, type, role (qualificacao), entry date, age band. CPFs are masked by Receita. faixa_etaria: 1 = 0-12, 2 = 13-20, 3 = 21-30, 4 = 31-40, 5 = 41-50, 6 = 51-60, 7 = 61-70, 8 = 71-80, 9 = over 80, 0 = not applicable.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose one real behavior — CPF masking by Receita — plus the full faixa_etaria code mapping. It omits pagination, volume of results, error behavior for invalid/missing CNPJ, and whether an 8-digit root returns partners across multiple companies.
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-loads the core purpose then immediately delivers the returned-field list and the code legend. The faixa_etaria enumeration is long but each mapping is load-bearing if the output schema does not decode it; no filler sentences.
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 re-explained, yet the description still usefully decodes faixa_etaria. Missing for a one-param lookup tool: whether a root CNPJ fans out to multiple companies, result limits/pagination, and not-found behavior — meaningful gaps for an agent deciding what to expect.
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% for the single cnpj parameter, so the description must compensate, and it does: it states the parameter accepts either a CNPJ root or a full CNPJ, a detail absent from the schema. It stops short of specifying accepted formatting (digits only vs punctuation) or length rules.
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: 'Partners (socios) of one company by CNPJ root or full CNPJ', and enumerates the returned fields (names, type, role/qualificacao, entry date, age band). The phrase 'of one company' implicitly separates it from the sibling search_partners, but the sibling is never named, so differentiation is left to inference.
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 by the input (have a CNPJ, want its partners), and the description supplies the deterministic output. However, there is no explicit when-to-use statement and no exclusion or routing to alternatives such as search_partners for name-based lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up Receita's code tables by text or code. kind: cnae (activity), natureza_juridica (legal form), municipio, motivo (reason for status), qualificacao (partner role), pais. CNAE text returns ranked candidates using exact descriptions, curated everyday aliases, word matches and spelling suggestions. Read match_type, match_note and every official description; ambiguous terms are not an automatic classification. Numeric codes/prefixes keep the original lookup. Other tables use literal text. Use this before sector or municipio filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| text | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it explains CNAE ranking (exact descriptions, curated aliases, word matches, spelling suggestions), instructs the agent to read match_type/match_note, and warns that ambiguous terms are not an automatic classification. It does not cover permissions or limits of the lookup, but the interpretive behavior is well disclosed.
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, then kind enumeration, then behavioral guidance, all in dense but purposeful sentences. Nothing is redundant, though the run of clauses is slightly packed for quick scanning.
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?
The description supplies the interpretation context needed for a reference-lookup tool and an output schema handles return values. The main residual gap is the undocumented `limit` parameter; otherwise an agent has enough to call it correctly.
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 largely does: it enumerates the valid `kind` values (cnae, natureza_juridica, municipio, motivo, qualificacao, pais) and explains that `text` behaves differently for CNAE text vs numeric codes vs literal-text tables. Only the `limit` parameter is left unexplained.
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 ('look up') and resource ('Receita's code tables by text or code') and enumerates the exact table kinds it resolves. An agent can distinguish this reference-lookup tool from the company/partner search siblings without opening the 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?
Explicitly directs the agent to 'Use this before sector or municipio filtering', giving a clear prerequisite ordering relative to the search siblings. It also distinguishes numeric-code lookups from free-text lookups, though it does not name a specific sibling alternative to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find companies/establishments matching filters. Filters (all optional, combined with AND): cnae (CNAE code or prefix, e.g. '4711' or '47', list ok; add include_secondary to also match secondary activities), cnae_secao (letter A-U), uf, municipio (name as in Receita, accents ignored), municipio_codigo, situacao (ativa, baixada, suspensa, inapta, nula), matriz_only, porte (micro = ME, pequeno = EPP, demais, nao_informado), natureza_juridica (code prefix like '2062' or text like 'sociedade limitada'), capital_min/capital_max (BRL), opened_from/opened_to (data_inicio_atividade, YYYY-MM or YYYY-MM-DD), closed_from/closed_to (data da baixa), mei, simples (true/false), name_contains (razao social or nome fantasia; 3-256 characters and uf required), cep, partner_name (a partner's name contains this text). Returns up to 100 rows per page, ordered by opening date (newest first) unless order_by is capital_social or razao_social. Use count_companies for 'how many' questions. Set include_contacts to add email, phones, full address and a registry_contact_quality block (0-100 score of how likely the REGISTERED email/phone from Receita is a real direct contact, with the signals behind it; it says nothing about the website) and, when the company's own website was crawled, a separate website_contacts block (WhatsApp, phones, emails, social profiles found on its public pages, each with source_url). A whatsapp_business block appears only when a WhatsApp Business account was found on one of the registered phones (display name, account type, name_match score, checked_at); phones are checked in the background after a query shows them, so a result can appear on a later call, and its absence says nothing about whether the number is on WhatsApp. min_contact_score keeps only companies whose REGISTERED contact (the email and phones on the Receita record, not the website) scores at or above it. Pass an integer 0-100, or a tier name: 'high' = 85, 'medium' = 50, 'low' = 0 (e.g. min_contact_score=50 or 'medium' for medium and high). The filter is applied after the page is read, so a call scans at most 2000 candidates and returns pagination.next_offset to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | ||
| cep | No | ||
| mei | No | ||
| cnae | No | ||
| limit | No | ||
| porte | No | ||
| offset | No | ||
| simples | No | ||
| order_by | No | data_inicio_atividade | |
| situacao | No | ||
| closed_to | No | ||
| municipio | No | ||
| opened_to | No | ||
| cnae_secao | No | ||
| capital_max | No | ||
| capital_min | No | ||
| closed_from | No | ||
| matriz_only | No | ||
| opened_from | No | ||
| partner_name | No | ||
| name_contains | No | ||
| include_contacts | No | ||
| municipio_codigo | No | ||
| include_secondary | No | ||
| min_contact_score | No | ||
| natureza_juridica | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present the description carries the full burden, and it does so unusually well: it discloses background phone checking ('a result can appear on a later call, and its absence says nothing'), the 2000-candidate scan cap, post-page filtering of min_contact_score, default ordering, and the exact conditions under which whatsapp_business and website_contacts blocks appear. These are non-obvious behaviors an agent could not infer.
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 text is long but nearly every clause earns its place given zero schema coverage and 26 parameters, and it is front-loaded with the filter contract before the return/behavior detail. It would benefit from list formatting and has minor redundancy (the contact-score explanation is restated twice), keeping it short of 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 26-parameter search tool with no annotations and no output schema, the description covers return shape (100 rows/page, ordering), pagination continuation via next_offset, the optional contacts/whatsapp blocks, and the post-filter caveat. Nothing an agent needs in order to call it correctly appears to be 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% and there are 26 parameters, so the description must compensate, which it largely does: it documents value formats and semantics for cnae/cnae_secao, uf, municipio, municipio_codigo, situacao (with enum values), porte, natureza_juridica, capital bounds, date windows, mei, simples, name_contains, cep, partner_name, include_secondary, include_contacts, and min_contact_score (including the integer/tier duality). Only limit/offset defaults and the full order_by option set are left to 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 and resource ('Find companies/establishments matching filters') and explicitly distinguishes itself from one sibling by routing 'how many' questions to count_companies. It does not, however, differentiate itself from search_partners or get_company, so the differentiation is incomplete for a family of eight tools.
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?
Provides clear conditional guidance ('Use count_companies for how many questions'), tells the agent that all filters are optional and ANDed, and explains when include_contacts vs min_contact_score apply. It never states when NOT to use this tool versus siblings like get_company or search_partners.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the companies a person or entity is a partner of, by name. Exact (accent-insensitive, case-insensitive) match on the partner name by default; set contains=true for a substring match (uf required). Optionally narrow with cpf_middle (the 6 digits Receita publishes, e.g. '240659') because the same name can belong to different people. Returns company name, status and role.
| Name | Required | Description | Default |
|---|---|---|---|
| uf | No | ||
| name | Yes | ||
| limit | No | ||
| offset | No | ||
| contains | No | ||
| cpf_middle | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden well: it discloses match semantics (exact by default, accent- and case-insensitive), the uf requirement when contains=true, and the returned fields (company name, status, role). It does not mention pagination (limit/offset) or result-size behavior, so it is strong but not exhaustive.
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 dense sentences, front-loaded with purpose and the default-match behavior. Every clause carries information, though the parenthetical asides make it slightly harder to scan than an ideal definition.
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?
There is no output schema, and the description correctly enumerates the return fields (company name, status and role). Combined with the match and disambiguation semantics, this is nearly complete for invocation; only pagination behavior 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 across 6 parameters. It explains name matching, contains, cpf_middle (with the '240659' example) and the uf dependency, but leaves limit/offset undocumented and never defines what 'uf' is (a Brazilian state code), leaving two parameters ambiguous.
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?
Names a specific verb (Find) and a precise, directional resource (the companies a person/entity is a partner of), which is meaningfully different from list_partners and search_companies. It does not explicitly name or contrast those siblings, so an agent must infer the distinction, keeping it below a 5.
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?
It gives clear conditional guidance for parameters (set contains=true for substring; uf required in that case; use cpf_middle to disambiguate homonyms), but never states when to choose this tool over the sibling list_partners (the inverse direction) or search_companies. Usage is implied by the purpose rather than routed.
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.
search_companies2 fields changedInput schema / properties / min_contact_score / anyOfPrevious value: -[
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "type": "integer"
+ },
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "title": "Result",
- "type": "array"
- }
- },
- "required": [
- "result"
- ],
- "title": "search_companiesOutput",
- "type": "object"
-}New value: +nullsearch_partners1 field changedOutput schema / (root)Previous value: -{
- "properties": {
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "title": "Result",
- "type": "array"
- }
- },
- "required": [
- "result"
- ],
- "title": "search_partnersOutput",
- "type": "object"
-}New value: +nullcompanies_at_addresscount_companiesdataset_infoget_companylist_partnerslookup_codessearch_companiessearch_partnersFree lookup of 28.4M active Brazilian companies by CNPJ or name (Receita Federal open data).
Brazilian company registry (Receita): CNPJ lookup, CNAE search, idea evaluation, monitoring.
Free Brazilian CNPJ lookup (legal name, status, partners) + lawsuit discovery. Public data, no login
Brazilian company and person data by CNPJ/CPF: registry, partners, tax status, sanctions, lawsuits.
Add one secure layer between your agents and this server.