radar-cnpj

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the categories of information the index exposes (operations, formats, authentication, limits), which is useful content-level context. With no output schema, it still omits structure, size, or format of the response.

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 short sentence with zero filler, and the content enumeration is front-loaded. It is efficient, though the brevity borders on under-specification rather than deliberate conciseness.

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 zero-parameter, read-only discovery tool with no output schema, the description does convey the broad categories of what the index contains. It is reasonably complete for such a simple tool, with only the response shape and intended call timing left unspecified.

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 per the baseline there is nothing for the description to disambiguate. Schema coverage is reported at 100% with an empty properties object, leaving no parameter gap to compensate for.

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 names the resource ('API index') and enumerates the content it covers (operations, formats, authentication, limits), which goes slightly beyond the title. However, it never states an action verb or what the tool actually returns, so the purpose reads as a topic label rather than a task. It also does nothing to separate it from sibling discovery tools like ref, health, or search.

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 when-to-use guidance, no mention of alternatives, and no indication of when this should be preferred over sibling tools such as ref or health. An agent could guess it is a 'start here' discovery call, but that is inference, not guidance.

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

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

With only a thin annotation set (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description carries real behavioral weight: a hard rate limit of 30 AI analyses/day per network, the fact that `ia_filters` consumes the same budget, and the exact failure shape (`limite_diario` with `renova_em`). It also scopes the semantic boundary of the output, which annotations cannot express. Nothing here contradicts readOnlyHint=false — consuming a quota is consistent with a non-read-only tool.

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 and mechanism, then limits, then quota mechanics — a sensible ordering with no filler sentences. It is somewhat dense for a three-parameter tool and leans on internal tokens (`ficha.limites`, `limite_diario`, `renova_em`) that inflate the reading cost, keeping it just 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?

There is no output schema, so the description takes on the burden of describing returns and does so: active, opened and closed company counts, how the companies are set up, and a plain reading of the numbers. Combined with the documented fallback response and quota limit, an agent has everything needed to call it and interpret both success and throttled outcomes.

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 100%, so `texto`, `uf` and `municipio` are already documented with length limits and examples in the schema itself. The description only restates the high-level idea-to-CNAE-to-place mapping, adding no format or precedence detail (e.g. how `uf`/`municipio` hints interact with a city named in `texto`) beyond the schema. Baseline 3 applies.

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 precise verb-resource pair (evaluates a business idea by counting registered companies) and the mechanism (maps to a CNAE activity code plus a place, then counts active/open/closed companies). It further disambiguates by stating what it does NOT do (no search volume, no demand promise), which separates it from the lookup siblings like consulta_cnpj and search.

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 makes the use context clear (early-stage idea validation against registered-company counts) and points to `ficha.limites` for the interpretation boundary, and it names `ia_filters` as the tool sharing its daily AI-analysis quota. What's missing is an explicit 'use X instead when you need Y' routing rule against the many sibling lookups.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new operational context — that calls do not consume the daily free limit and that the origin's protection limit still applies — which is exactly the quota/throttling information annotations cannot express. It stops short of describing output shape or latency, so a 4 rather than 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?

Three tight sentences: return contents first, then scope/behavioral caveats, then alternative routing. Every sentence carries information and the most decision-relevant content is front-loaded.

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 compensates by naming the returned fields. Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed to select and invoke the tool 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 description coverage is 100% and the single cnpj parameter is already documented as accepting input 'with or without punctuation.' The description adds only the phrase 'by CNPJ,' which duplicates the schema rather than extending it, so the baseline 3 applies.

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 the specific resource (a Brazilian company's registration record, keyed by CNPJ) and enumerates the returned fields (name, status, activity, address). It also explicitly contrasts itself with the sibling consulta_cnpj, so an agent can distinguish the two without opening either 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?

Gives an explicit when-not rule with the alternative named: 'For sanctions, tax status and a live CNIA check, use consulta_cnpj.' It further clarifies scope limits ('does not show contacts or partners and runs no extra checks'), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantially more: a hard cap of 20 addresses and 20 companies, the total-address field name (pontos_total), a 10-lookups-per-day-per-network quota, and the specific free_limit/resets_at error payload. That is rich operational context beyond the structured fields.

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 sentences, each earning its place: purpose/returns, then truncation caps, then quota/error behavior. The most decision-relevant information (what you get back) is front-loaded with zero filler.

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 read-only lookup with no output schema, the description covers return shape, truncation, and quota behavior, which is most of what an agent needs. It stops short of describing the address record fields or how to route to sibling lookup tools.

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?

There is a single parameter with 100% schema description coverage, so the schema already carries the meaning and a 3 is the baseline. The description only restates 'CEP (Brazilian postal code)' without adding format, normalization, or validation guidance beyond the 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?

It states a specific resource and return: addresses at a CEP with CNEFE/IBGE coordinates plus the companies registered there. The lookup verb is implicit rather than explicit, and it never names the closely related siblings (consulta_endereco, consulta_cnpj), so an agent gets a clear purpose but no sibling differentiation.

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 description explains what comes back but never says when to reach for this tool versus consulta_endereco or consulta_cnpj, nor any precondition such as requiring a valid 8-digit CEP. The only implicit guidance is that it returns both addresses and companies, which hints at scope without stating it.

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

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

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), the description discloses real behavioral traits: 10 free lookups per day per network, the failure shape (`free_limit` with `resets_at`), that checks are live and the registry data is updated daily, that personal data comes back masked, and that omitting `temas` returns the full record while null blocks mean unchecked.

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 is front-loaded, but the body devolves into a single enormous sentence cataloguing every data source, which is hard to scan. The operationally critical facts — free-limit behavior and alphanumeric CNPJ support — are buried at the very end rather than surfaced, so length is not fully earning 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?

With no output schema, the description carries the return-value burden itself and does so thoroughly, enumerating the blocks available under `temas` and their provenance. Combined with the rate-limit, masking and freshness disclosures, an agent has everything needed to call and interpret this tool.

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 already 100%, so the baseline is 3, but the description adds genuine meaning: it states the tool accepts both the numeric and the alphanumeric CNPJ format (the schema only mentions punctuation), clarifies that basic company data always stays regardless of `temas`, and explains the omit-vs-null semantics of the topic selector.

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 first sentence states a specific verb and resource: fetch a Brazilian company record by CNPJ from the Receita Federal, with an unusually precise inventory of the attached blocks (sanctions, PEP, tax, labor/environmental risk, contracts, regulators). That is far more specific than a sibling like search_companies or consulta_cadastro, but the description never explicitly distinguishes itself from the several other CNPJ-oriented tools in the sibling list (consulta_cadastro, evaluation_basic/premium, add_company), leaving that routing 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 only implied: 'useful to vet suppliers' and the note that `sancoes` reflects registry data against the CNPJ root. There is no explicit when-to-use statement, no when-not, and no named alternative such as consulta_cadastro or evaluation_basic for the cases where a lighter lookup or a credit evaluation is what the agent actually wants.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower; the description still adds real behavioral value by disclosing the result caps (up to 20 addresses and 20 companies), the quota exemption, and the fact that the origin's protection limit applies.

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 clauses, front-loaded with the core purpose before the quota and limit caveats. Only minor friction from unexplained internal jargon ('pontos_total', 'the origin's protection limit').

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 naming the `pontos_total` field and the caps on returned addresses/companies is genuinely useful. Quota and limit caveats round it out; only the sibling differentiation and any error/empty-result behavior are 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?

There is only one parameter and schema coverage is 100%, so the schema fully documents that 'cep' accepts input with or without a hyphen. The description adds nothing about the parameter format, which is the expected baseline when the schema does the work.

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: retrieve addresses and companies at a Brazilian CEP. Clear enough to act on, but it never distinguishes itself from near-name siblings like consulta_cep or consulta_cnpj, so an agent cannot tell from the description alone which of the CEP/CNPJ tools to pick.

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 implies a use case (looking up addresses/companies for a postal code) and adds quota-relevant context ('without counting against the daily free limit'), but gives no explicit when-to-use vs. when-not, and no guidance on choosing it over consulta_cep or consulta_cnpj.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond that: it does not consume the daily free quota, it omits contact data, and `incompleto` flags a partial source response. The partial-failure semantic is the kind of detail annotations cannot express.

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 short sentences, front-loaded with the core action and result semantics; each sentence adds a distinct fact (ranking, quota exemption/hidden contacts, `incompleto` meaning). No filler.

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 no output schema, the description carries the return burden and does reasonably well, disclosing result count, ordering criterion, contact omission and the `incompleto` sentinel. It could say slightly more about what each suggestion contains (e.g., name vs CNPJ fields), but nothing critical for correct invocation 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 100%, so the sole `q` parameter (3-120 chars, name/CNPJ/phone/e-mail) is already fully documented. The description echoes the same accepted inputs without adding syntax, normalization or prioritization rules, so baseline 3 is appropriate.

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 ('Suggests up to 8 Brazilian companies') plus the accepted key types (CNPJ, name, partner, phone, e-mail), so an agent knows this is a fuzzy autocomplete-style lookup rather than a full record fetch. It contrasts implicitly with consulta_cadastro/consulta_cnpj by capping results at 8 and noting it hides contacts, but never names a sibling outright.

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 only implied: signaling that it is free of the daily limit and returns a short ranked shortlist hints at exploratory/pre-lookup use, but the description never says when to choose it over search_companies, consulta_cnpj or consulta_cadastro. No explicit when-not conditions are given.

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

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

Adds substantial context beyond the annotations: a per-network rate limit of one message per 10 seconds with queuing (not an error) on overage, delivery by e-mail with `email` as reply address, a 32 KiB JSON cap and a 2 MB audio cap, and a two-minute browser recording limit. The annotations (readOnlyHint=false, non-idempotent, non-destructive) cover the safety profile, and the description enriches it well; response/confirmation behavior is the only notable omission.

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 mechanics, with no filler sentences — every claim (limits, formats, delivery) earns its place given an 18-parameter tool. The sentences are dense and stacked with parentheticals, which slightly hurts readability, but there is no redundancy.

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 an 18-parameter, multi-mode write tool with no output schema, the description covers delivery path, size/rate constraints, and the conditional field groups that an agent must get right. It stops short of describing what a successful response contains, but the critical invocation guidance is present.

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 already 94%, so the baseline is 3, but the description adds genuine cross-parameter meaning: `tipo` activates the proposal fields, `espaco` must be placement ids from `GET /api/partners`, `orcamento` has different enum sets for advertising vs consulting, and `prefer_whatsapp` requires `whatsapp`. This is meaningful semantics the schema does not express on its own.

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?

Opens with a specific verb and audience ('Write to the people behind the product') and immediately enumerates the supported intents (question, sponsorship, partnership, advertising proposal). No sibling tool in the list is remotely similar, so differentiation is trivially satisfied and the purpose is unmistakable.

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 routing between the question and proposal paths via `tipo`, notes that `tipo` 'turns on the fields below', and covers the split between JSON and multipart voice submission. It does not state when not to use this tool or name any alternative, but the usage context is clear enough to invoke correctly.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior beyond that: personal names, MEI house numbers, phone and e-mail stay masked with data.mascarado: true, null means unchecked, and answers are cached for up to 6 hours. It does not mention auth requirements or rate limits, 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?

The purpose and the consulta_cnpj alternative are front-loaded, but the middle is a dense run-on enumeration of roughly thirty data blocks that pushes the operationally important masking and cache facts to the very end. Since no output schema exists the detail is defensible, but it is far longer than needed and poorly tiered.

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 no output schema, the description carries the return-shape burden and does so broadly, covering sanctions, tax, labor, contracts, PEP, regulator registrations and masking. Missing only edge behavior such as invalid-CNPJ handling and what empty result sets look like, which keeps it just short of complete.

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 100%, so both parameters are already documented, which sets the baseline at 3. The description adds genuine meaning on top by tying each data.* block to a topic category (sancoes, dividaAtiva, pep, campanhas, etc.), effectively mapping the temas enum-less string values to the payload sections an agent would want.

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 opening states the exact resource ('Brazilian company record by CNPJ') and enumerates the linked public-record blocks, so the agent knows precisely what comes back. It also differentiates itself from the sibling consulta_cnpj by naming it for live checks, so the two tools are distinguishable without opening either 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?

It gives one explicit routing rule — 'for a live check, use consulta_cnpj' — plus a freshness window ('reused for up to 6 hours') and the 'check the reference date' caveat, which tells the agent when the cached record is safe to trust. There is no statement of when not to use it or of prerequisites, so it falls short of a full when/when-not/alternative treatment.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the returned date is a reference date, not live, so the agent knows results can be stale. It omits any cost, auth, or rate-limit notes.

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 short sentences, front-loaded with the subject, then the concrete return fields, then the key limitation. Nothing is redundant and every sentence adds information the agent needs.

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 no output schema, the description carries the burden of explaining the return value, and it does so for two fields while flagging the staleness caveat. It leaves some ambiguity about whether additional health indicators exist, but for a zero-parameter read tool this is close to complete.

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, which sets the baseline at 4. The description instead spends its words on output field semantics (`import.dump_date`, `import.counts`), which is a reasonable substitute but does not affect parameter interpretation.

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 names the resource (company database) and resolves the vague title 'Health' by specifying what is actually reported: `import.dump_date` and `import.counts`. An agent can tell this is a status/freshness probe rather than a data query. It stops short of a clean verb+resource statement, but the field-level detail disambiguates well.

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 explicit when-to-use or when-to-prefer-an-alternative statement against siblings like api_index or search. The closing caveat ('does not confirm real-time changes') implies the intended use is checking data freshness/reference date, which is useful implied guidance but not a routing rule.

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

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

Goes beyond the annotations by disclosing a specific 18-20 second runtime and that it draws on a shared daily AI-analysis quota with `avaliar`. Those are exactly the operational constraints an agent needs for scheduling and avoiding quota exhaustion. It does not state whether repeated identical inputs return identical filters, which matters given idempotentHint=false.

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 short sentences, each with a distinct job: purpose, latency, quota coupling. The core function is front-loaded and nothing is padded or repeated.

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 no output schema, the description does convey what comes back (filters suitable for `search`'s `f` argument) plus timing and quota. It stops short of describing the filter format or how to pass it through, leaving a small but real gap for a conversion tool.

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?

Only one parameter (`texto`) and schema coverage is 100%, so the schema already carries the semantics; baseline 3 applies. The description's phrase 'plain-language description of the companies you want' is consistent with the schema but adds no syntax, length, or format guidance.

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 concrete transformation: plain-language company description in, filters for `search` (`f`) out. It names the sibling tool it feeds, which lets an agent place it in the workflow. The cryptic abbreviation '(`f`)' for the target parameter slightly muddies the otherwise clear purpose.

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 it should call this before `search` when it has natural-language criteria. Latency (18-20s) and the shared AI quota give practical decision context, but there is no explicit when-not or alternative path (e.g. hand-building filters).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and not-open-world. The description adds genuinely new behavioral context beyond that: it discloses a freshness guarantee ('never cached') plus the rationale, and flags the result as 'approximate'. It falls short of stating accuracy limits or what happens on resolution failure.

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, no filler, with the returned value front-loaded and the caching constraint following as supporting rationale. 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?

For a zero-parameter, no-output-schema tool with annotations covering safety, the description supplies what the agent needs: what is returned (city/state), its source (network edge), and its freshness guarantee. Only accuracy caveats and failure behavior are left unstated.

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 and there is nothing for the description to compensate for. It correctly implies the result is caller-derived rather than argument-driven.

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 and return (the caller's approximate city/state, derived from the network edge), which disambiguates the otherwise opaque name 'local'. It does not explicitly contrast itself with any sibling, but its function is distinct enough from the lookup/consulta tools that differentiation is not strictly needed.

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 only implied: an agent can infer this is the tool to call when it needs the requester's geographic location, but there is no explicit when-to-use framing, no prerequisites, and no named alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds that these vocabularies feed filters, which is useful behavioral context, but it doesn't disclose what happens when `q` is omitted (list all?) or the shape of results.

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 zero filler, front-loading the purpose before the search instruction. It could be marginally sharper by stating the implied use case explicitly, but it is well-sized.

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 two-parameter lookup with no output schema, the description covers what the tool is and how to search, but omits what a call returns (code/label lists?) and the no-`q` fallback behavior, leaving an agent to infer the result format.

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 100% and the enum is fully documented, so the schema carries parameter meaning. The description restates the three vocabulary values and mentions text search via `q`, matching the schema without adding format or matching semantics (e.g., substring vs prefix).

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 names a specific resource (reference vocabularies for filters) and enumerates the three vocabularies (cnae, municipio, natureza), plus the search action via q. It's clear what the tool does, though it doesn't explicitly differentiate itself from potential siblings like search, suggest, or ia_filters.

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?

Saying the vocabularies are 'for the filters' implies this tool is used to discover valid filter values, and it notes how to search with `q`. However, there is no explicit when-to-use vs alternatives guidance, no statement of when not to use it, and no routing to sibling lookup tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds useful behavioral context beyond them: the input requirement and the performance cost of a termless, filterless scan, which is exactly the kind of operational detail annotations don't carry.

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 front-loaded sentences with no padding: purpose first, the `tipo` semantics second, the input precondition last. Every clause carries information the agent can act on.

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 no output schema, the description would ideally say something about result shape or pagination, but `page`/`pageSize` are self-documenting in the schema and the core invocation requirements are fully covered. It is complete enough to call correctly without being exhaustive about returns.

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 100%, so the baseline is 3, but the description goes further by spelling out the semantic meaning of each `tipo` value (legal name, trade name, partner, phone, email, address, activity code) rather than just listing the enum. It also clarifies that `f` is a JSON string. That is genuine added meaning over the 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 ('Search Brazilian companies') and scopes it by term and/or filters. It is clear and specific, but it never names or distinguishes itself from siblings like search_construction, get_cnpj, or consulta_cadastro, so an agent gets no routing signal from the text alone.

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 concrete usage precondition: it 'needs a term or at least one filter,' with the consequence of omitting both ('would scan 71 million establishments'). That is strong when-to-use context, but it offers no when-not-to-use exclusions or named alternatives, keeping it below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds two genuinely extra traits: the company-owned-only scope constraint and a data-freshness caveat ('Check source dates and update status'), which annotations cannot express.

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 lookup keys before the filters and the scope caveat; no filler. The closing clause ('Check source dates and update status') is terse to the point of ambiguity, which is a small deduction rather than bloat.

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 11 optional parameters and no output schema, the description covers the core lookup and filters but omits any mention of pagination/cursor behavior, the 1-50 page-size limit, or the uf+municipio pairing rule. The schema carries these, so the gap is moderate rather than severe.

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 100%, so every parameter including cursor, limite, areaMin/areaMax, situacao and the ref hint for municipio is already documented. The description only restates the filter categories in prose (area, type, category, status) without adding format or constraint meaning, so it sits at the baseline.

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 Brazilian CNO construction works') and enumerates the three lookup keys (12-digit CNO number, company CNPJ, city+state). It does not, however, differentiate itself from the generic 'search' sibling in the tool list, so an agent must infer which one applies.

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 description implies its context (construction-work lookups) and adds a scope rule ('Only company-owned records are included'), which is useful. But it never says when to choose this over the sibling 'search', nor states exclusions or prerequisites such as requiring uf together with municipio.

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

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

The annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add operational context — and it does: 'not cached and not counted as a visit in the metrics', the 'incompleto: true' partial-failure signal, and the guarantee that results carry no contacts and no personal names. That is genuinely useful behavior beyond the structured fields, though the response shape itself remains unspecified.

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 lead sentence front-loads the return scope ('up to eight Brazilian companies'), and the remaining sentences are dense but each carries distinct information (matching rules, input constraints, failure flag, exclusions, caching). The sentence fragments are choppy but nothing is redundant.

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 no output schema, the description must carry the return burden, and it does explain count (up to eight), deduplication, the 'incompleto' flag, and what results exclude. It stops short of describing the actual response fields, but combined with rich read-only annotations this is close to complete for a one-parameter lookup.

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 100% and the single 'q' param is documented, so the baseline is 3. The description goes further by explaining input detection ('it detects the kind of input'), the 3-character floor, the phone/e-mail requirements, and ranking rules (exact names before prefixes, no repeated CNPJ, matches legal name, trade name and partners), which meaningfully deepens what the schema alone conveys.

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 ('suggest') and resource ('up to eight Brazilian companies') and enumerates the accepted input kinds (CNPJ, name, partner, phone, e-mail), so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the similarly named sibling 'consulta_sugerir', which by name appears to do the same thing, so the sibling differentiation is missing.

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 concrete input-side conditions (text needs at least three characters, a phone needs the area code, an e-mail needs the full address on record) which is more than most definitions. But it never says when to prefer this tool over 'consulta_cnpj', 'consulta_cadastro', or the near-identical 'consulta_sugerir', so alternative routing is left to inference.

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