radar-cnpj

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent operation. The description adds useful behavioral context beyond annotations: first watch is free, extra slots are paid per 30 days, there is no automatic renewal, and the service performs repeated checks and change detection.

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 mostly front-loaded and efficient, covering purpose, pricing, renewal, and polling behavior. The final sentence, "Read the monitoring and alert state," is somewhat vague and less clearly earned than the rest.

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 non-destructive mutation tool with annotations and no output schema, the description covers the key operational context: cost, renewal, polling, and coverage. It could be more complete by clarifying duplicate-watch behavior or what state is returned, but it is largely sufficient.

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 both parameters are already documented in the input schema. The description does not add meaningful syntax or format details beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource: "Starts watching a CNPJ." It is clear what the tool does, but it does not explicitly differentiate itself from siblings such as list_watches or reactivate_watches.

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: start monitoring a CNPJ, and the service will repeat checks so the agent need not poll. However, there is no explicit guidance on when to use this versus list_watches, reactivate_watches, or other monitoring-related siblings, and no when-not-to-use conditions.

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 read-only, idempotent, non-destructive, and closed-world behavior, so the description adds useful context by listing the returned offer and purchase fields. It does not describe rate limits, auth requirements, or how missing api_pass changes behavior, but the annotation coverage lowers that burden.

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 in one compact sentence, and the long return-field list is dense but justified because there is no output schema. The description is not bloated, though the return object could be formatted more readably.

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 tool with rich annotations and no output schema, the description provides enough return-shape information for an agent to understand the result. The main missing piece is an explicit mapping of api_pass presence to discovery versus private-purchase inspection.

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 single optional api_pass parameter is fully documented in the schema, including its private pass format and the warning to save it before buying. The description only hints at it via 'inspect a private purchase' and adds no format or behavior details beyond the schema, 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?

The description states two concrete functions: discovering the monthly data package and inspecting a private purchase. This is clearer than a tautology and gives the agent a usable verb/resource pairing, though it does not explicitly differentiate itself from the sibling api_access_buy.

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 two modes imply when the tool is useful, but the description never explicitly says to call it without api_pass for discovery versus with api_pass for inspection. It also does not mention when to use api_access_buy instead, so usage is only implied.

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 description says 'Same pass in retries recovers the same purchase' and the transaction parameter 'Never creates another charge,' which conflicts with idempotentHint=false. Although it otherwise discloses useful behavior such as no automatic renewal and separate tariffs, the idempotency contradiction is material for a purchase operation.

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 offer is front-loaded in the first sentence, and the remaining sentences cover relevant operational details. The paragraph is dense and could be structured more clearly, but most content 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?

Given the absence of an output schema, the description provides substantial operational context: price, validity, retry behavior, no automatic renewal, excluded tariffs, response headers, and prepaid credit behavior. This is sufficient for an agent to understand what the tool does and how it fits into the payment flow.

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 schema already documents payment, api_pass, transaction, and credit_token. The description adds flow context, such as saving the api_pass before buying and using the transaction hash for reconciliation, but does not add parameter syntax 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?

The description states a specific verb and resource: buying 1000 basic data reads for US$1, valid for 30 days. It also scopes what is not included (OCR, AI, documents, delivery) and mentions the prepaid alternative, making the tool's role distinguishable.

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 usage context: buy basic data reads, send X-API-Pass on eligible reads, and skip this purchase if using prepaid credit. It does not explicitly compare against every sibling tool, but the alternative path is named.

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, 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?

Annotations only say readOnly=false, destructive=false, idempotent=false; the description goes well beyond by disclosing the daily quota, the exact rate-limit response shape (`limite_diario` with `renova_em`), and where limitation caveats live (`ficha.limites`). That is precisely the operational context annotations cannot 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?

Front-loaded with the core mechanism, then scope limits, then quota — a sensible order with no filler. It is dense in a single block, and the quota sentence could be separated, but every clause carries information.

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 the work of describing what comes back (counts by status, setup breakdown, a plain reading of the numbers) and where limitations are surfaced. It stops short of naming all returned fields, but an agent has enough to call it and interpret the response 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 100%, so uf/municipio/texto are already documented — the baseline is 3. The description's phrase 'mapped to ... a place' hints that location is derived, but adds no format or precedence detail beyond what the schema already states about hints.

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 with mechanism: maps a business idea to a CNAE code and place, then counts active/opened/closed companies and describes how they are set up. This clearly distinguishes it from registry-lookup siblings like consulta_cnpj or get_cnpj, which look up an existing company rather than evaluating an idea.

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 clear scope boundaries — it does not estimate search volume and does not promise demand — and points to `ficha.limites` for caveats, plus a concrete quota (30/day per network). It lacks an explicit 'use sibling X instead when Y' routing statement, 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.

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered upstream. The description adds the useful hint that the endpoint is "public" (no auth needed) and enumerates the returned payload sections, but says nothing about freshness, cost, or why flags like `dev_gate` and `homolog` exist.

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 one-sentence purpose is properly front-loaded, but the returns block is a dense brace-and-comma dump mixing nested optional keys (`free_now?`, `gratis?`) with no markup. It is information-bearing yet hard to parse, and could be structured more cleanly.

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 convey return shape, and it does enumerate top-level and nested fields. However, it only lists names without explaining what `quota`, `payment.homolog`, `credit.header`, or the `?` optionality mean, leaving the agent to infer semantics of a fairly complex payload.

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 of 4 applies; there is nothing for the description to clarify. The description correctly implies a no-argument call.

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?

"Public discovery of payment and prepaid credit" identifies the resource area and signals no-auth discovery, but the phrasing is abstract rather than a concrete verb+resource. It never distinguishes itself from siblings like `pricing`, `api_index`, or `api_access`, even though this tool apparently aggregates those very concepts as return fields.

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 prerequisites, and no named alternative. An agent cannot tell whether to call this instead of `pricing` or `api_index`, which is the central ambiguity given the overlap.

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 far beyond the annotations: it discloses subscription vs. one-off billing per payment rail, the 402-with-price failure mode, the `account_required` precondition, the `compra` marker against repeat credit debits, the single-settlement x402 nonce, and the advice to keep receipts after a delivery error. None of that is recoverable from readOnlyHint=false / idempotentHint=false alone.

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 payment rails, then preconditions and caveats — each sentence carries distinct information with no filler. It is dense with domain jargon (`compra`, `X-Credito`, `X-PAYMENT`) but that density buys real detail rather than repetition.

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 payment/mutation tool with no output schema, it covers the failure path (402 with price), the auth precondition, and idempotency hazards thoroughly. The one gap is the success response shape — an agent is told what happens when payment is missing but not what a completed purchase 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% and the single enum value `carteira-100` is already explained in the schema (99 more monitored companies). The description adds no further meaning about what the plan tier entitles or costs, so the schema does all the work — baseline 3.

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+resource: "Buys a plan for the signed-in account," which clearly separates it from list_plans, pricing, consulta_planos and cancel_plan. It never explicitly names a sibling or restates how it differs from them, so it stops just short of 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?

Provides real usage context: sign in first, choose a payment rail (prepaid credit, x402 v1/v2, card), and know that Pix/USDC give 30 days while card auto-renews. Missing an explicit pointer to alternatives (e.g. "use list_plans to see options, cancel_plan to stop renewal"), so it is clear context without 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?

The description carries substantial disclosure beyond the annotations: nothing further is charged, the paid period remains active until keeps_until, and it points to `account.cancel.losses` in `GET /api/plans` to enumerate what is lost. It also distinguishes refund timelines by payment method, which the annotations do not cover. The one gap is that it never reconciles this irreversibility with `destructiveHint: false`, leaving the agent to reconcile a plan-ending, data-removing operation flagged as non-destructive.

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 behavior is front-loaded in sentence one, which is good, but the remainder is a dense run-on mixing refund rules, timing, and payment-method exceptions without structure. The explicit JSON snippet in prose is partly redundant with the schema and costs space.

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 correctly tells the agent where to inspect losses (`account.cancel.losses` via `GET /api/plans`) and what `keeps_until` signifies, which is enough to call the tool defensibly. Minor gap: it does not state whether the call is reversible or how to confirm success.

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 schema already states the parameter must be `true` and what it means. The description repeats the literal body `{ "accept_data_removal": true }` and reinforces that acceptance means losing what the plan added, but adds no syntax or edge-case detail 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?

The opening sentence states a specific verb and resource ("Cancels the active plan") and immediately scopes the consequences. It is clearly distinguishable from siblings like list_plans, buy_plan, and reactivate_watches without needing to open 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?

The description gives rich conditional context (refund applies if purchased <7 days ago, or if the paid period hasn't started; USDC/credit purchases must be refunded by e-mail), which implies when the tool is appropriate. However it never explicitly routes the agent away from alternatives (e.g. buy_plan, reactivate_watches) or states a "when not to use" condition, so usage is only implied.

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 closed-world, so the safety profile needs no restating. The description does add genuinely useful behavior: hard caps of 20 addresses and 20 companies, and that `pontos_total` carries the true total. It stops short of saying what happens on an invalid CEP or whether the truncated result means a follow-up call is needed.

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 clauses, each carrying distinct information (what it returns, the result caps, the cost profile), with the payload statement front-loaded. Slightly compressed to the point of dropping the verb in the opening clause.

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?

No output schema exists, so the description correctly takes on return-value disclosure: it names addresses, companies, limits, and the `pontos_total` counter, and states the tool is free. A one-clause note on invalid-format CEPs or empty results is the only real 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?

Only one parameter and schema coverage is 100%, with the '8 digits' format documented in the schema itself. The description adds nothing about the CEP parameter, 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 a specific resource and verb: returns addresses at a CEP plus the companies registered there, with coordinates from CNEFE/IBGE. It is clearly distinguishable from consulta_cnpj-style lookups, though it never names the closest sibling (consulta_endereco) to draw the line 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?

Usage is implied rather than stated: an agent can infer 'use this to look up a CEP', and the cost note ('free: uses no daily allowance or balance') gives a real reason to prefer it over paid siblings. But there is no explicit when-not and no comparison against consulta_endereco 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 declare readOnly/idempotent/openWorld but say nothing about cost or failure modes; the description supplies that: source failure returns 503 without charging or falling back to a stored record, the free allowance is consumed before balance or per-call payment, and this is a source check rather than an issued official certificate. These are non-obvious operational traits, though the ordering/pricing sentence is dense and partly ambiguous.

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 same fact is stated three times: 'read conferidoEm', 'Without cnia_atual=true, an older CNIA can be returned; inspect conferidoEm', and the implied repeat earlier. The closing sentence 'An unavailable required check does not support a clean conclusion' is vague filler, and the key routing fact (what makes this different from get_cnpj) never appears at all, so space is wasted on redundancy instead of the front-loaded distinction.

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 read-only lookup with a fully documented 3-param schema and no output schema, the description does cover cost, failure semantics and partial-result behavior reasonably well. What is missing is the disambiguation an agent needs to pick it among several CNPJ tools, and any indication of response shape beyond 'blocks may be omitted / null means unchecked'.

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 schema already documents cnpj, temas and cnia_atual in detail, including the 503-without-charging behavior. The description largely restates the schema (cnia_atual condition, topic selection) rather than adding new semantics, so baseline 3 applies. The one genuinely additive hint, inspect conferidoEm for staleness, is useful but duplicated.

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 names the resource (CNPJ lookup) and adds qualifying detail (prepared public records plus an attempted CNIA source check), but the opening word 'Additional' is ambiguous — additional to what? With siblings like get_cnpj, dossier_cnpj and get_api_x402_cnpj_by_cnpj in the namespace, the description never says how this differs, so the agent cannot confidently distinguish it from alternatives.

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 conditional guidance for one parameter ('Set cnia_atual=true when that check is required') and for topics ('Select topics to load only the needed blocks'), which is real usage help. But there is no when-to-use-this-tool guidance versus the other CNPJ siblings, and no explicit 'do not use when...' clause.

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 description discloses a lot of behavior that the annotations do not: unpaid calls return a 402 with a price in dollars and reais, the body uses x402 v1 while PAYMENT-REQUIRED uses v2, the balance is held by the account holder or by the wallet that confirmed payment, unpaid wallets need the signed challenge to get an mmw_… credential, and a payment grants no login. It also states that a plan adds 30 days plus quota while a package is valid 90 days, and that there is no automatic renewal. This is exactly the extra context the annotations cannot 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?

The purpose is front-loaded in the first sentence, but the rest is a dense run-on of cryptic clauses such as 'The body uses x402 v1; PAYMENT-REQUIRED uses v2' that require prior knowledge to parse. Most of the information earns its place, but it needs restructuring.

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 has to carry the return path, and it does: the 402 quote, the credential URLs (wallet_start and wallet_token), and the balance-holder semantics. It doesn't cover error cases besides 402, but it is complete enough for this money-moving 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 100%, and the schema already documents the idempotency mark, the offer list, the x402 payment and the cred_… token. The description only adds the framing that the offer is one package plus three plans and that credit versus x402 are the two payment paths. 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 names a specific verb and resource: it buys one package or one of three plans, paid by credit or x402, with or without an account. That is far more specific than the title 'Buy lookups'. It never names the sibling it complements (consulta_planos for choosing a plan, api_access_buy for API plans), so differentiation is implied by subject matter rather than stated.

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 the purchasing procedure in detail (unpaid call returns a 402 quote, then sign the x402 payment), which is real invocation guidance. But it never says when to pick this over consulta_planos, pricing, billing, or api_access_buy. An agent can infer the flow but has to guess at routing.

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?

Rich disclosure beyond the annotations: credit consumption ('without charging the group'), 503 failure semantics for required source checks, default stored-CNIA vs live-check behavior, deduplication and validation done server-side, and truncation flags. Annotations only say readOnlyHint=false / idempotent=true; the description supplies the cost and failure contract the agent actually needs.

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?

Seven sentences with the key payload (one row per CNPJ, JSON vs CSV) reasonably front-loaded, but there is redundancy — the cnia_atual rule is largely repeated from the schema — plus stray phrasing ('missing metadata cannot support a clean conclusion') and mixed English prose with Portuguese field names that loosens precision.

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?

No output schema exists, and the description does name the key returned material (per-row fontes, evidencias, PGFN debt states, source dates, truncation flags) and the one-row-per-CNPJ shape, so an agent can reason about results. It stops short of describing the top-level envelope or error payload, but the substantive gaps are small.

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. The description does add output-oriented meaning ('read fontes and evidencias per row') and restates the cnia_atual live-check cap, but it also conflicts with the schema: schema maxItems is 100, while the text says 'up to 200 valid ones per request', which can mislead on the actual batch ceiling.

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?

Concrete verb+resource: it produces a supplier screening report with one row per CNPJ, and it states what the service does internally (validates, deduplicates, joins, formats). It implicitly distinguishes batch from single-company lookups ('no per-company response parsing'), but never names a sibling tool such as consulta_cnpj or dossier_cnpj, so the differentiation is left implicit.

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 internal alternative route (use POST /api/consulta/lote?formato=csv over HTTP for CSV instead of the MCP JSON response), which is genuine routing guidance. But it never says when to use this batch tool instead of the obvious single-CNPJ siblings, nor any prerequisite beyond the cnia_atual constraint.

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 read-only/idempotent/closed-world, but the description adds real behavioral context beyond them: output varies by credential type (X-Credito vs X-Wallet-Token), balance is shared across Radar CNPJ, PontoFato and EditalMD, and wallet credentials are issued per-portal. That is exactly the kind of auth-dependent behavior an agent needs before deciding to call it.

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 sentences, front-loaded with the returned payload and followed by the credential branching, with no filler. Slightly dense in the second sentence but every clause carries operational meaning.

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 parameters and no output schema, the description carries the burden of saying what comes back, and it does list the four data groups plus the conditional on credentials. Minor gap: it doesn't indicate the shape of the plan/offer data (currency, tiers, whether prices are per-call), though that is largely nameable from the response itself.

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 nothing for the description to disambiguate. The mention of header-based credentials is useful naming even though no schema properties exist.

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 enumerates what the call returns (free allowance, the single package, the three plans, the balance) and frames it as a 'lookup service', so an agent knows this is a read of pricing/plan/balance data rather than an operation on CNPJ records. The opening phrase 'CNPJ and address lookup service' is slightly confusing since siblings consulta_cnpj/consulta_endereco do the actual lookups, and no sibling is explicitly named to distinguish this from pricing or billing.

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 through the credential conditions ('without a credential... with an account...'), which implicitly tells the agent that an anonymous call returns offers and an authenticated call returns balance. There is no explicit 'use this instead of pricing/billing/api_access when...' guidance, so the agent must infer the split among four closely related commercial 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 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?

Beyond the annotations, it discloses important behavioral traits: no captcha/account/payment, rate limiting of one message every 10 seconds per network with queuing rather than error, email delivery with `email` as reply address, and multipart voice submission details with file size 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?

The description is front-loaded with useful context, but it repeats the same facts about captcha/payment and the 10-second rate limit twice, making it less concise than it could be.

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 tool with an output schema absent but full schema description coverage, the description covers operational constraints, delivery behavior, and multipart voice submission well. It does not describe the response format or confirmation behavior, which is a minor remaining 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?

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning for key parameters: `tipo` routes proposal types, `espaco` uses placement ids from `GET /api/partners`, and voice submissions use `dados` plus `audio` with explicit size and format constraints.

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: writing to the people behind the product for a question or a sponsorship/partnership/advertising proposal. It is clear about the tool's purpose, though it does not explicitly contrast with any sibling tool.

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 names concrete use cases (question, sponsorship, partnership, advertising proposal) and explains the conditional route via `tipo` with placements from `GET /api/partners`. It lacks explicit when-not-to-use guidance or named alternatives.

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 well beyond the annotations by disclosing billing semantics (same credit holder reopening the same company on the same Brasília day is not charged), failure behavior (503 with no charge and no stale-record fallback), and an interpretation warning ('Missing checks are not a clean result'). These are exactly the operational facts an agent needs and none are derivable from readOnlyHint=false / 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?

The core distinction and the cnia_atual tradeoff are front-loaded, and every sentence carries operational content. It is somewhat long and drifts into referencing an HTTP path inside a tool description, which is slightly awkward but not wasteful.

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 usefully tells the agent which response fields matter (dossie.dados, dossie.semaforo.alertas, dossie.semaforo.sem_conferencia) and warns about the meaning of missing checks. The concrete response shape is still unspecified, but the behavioral coverage is high overall.

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 adds real meaning to cnia_atual: what it forces, what happens on failure, and the alternative of inspecting the returned CNIA date instead. It also names which returned fields to read, giving the parameters downstream purpose.

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 sentence names a concrete resource (company dossier) and its distinguishing contents (unmasked details, risk signals), which separates it from plain lookup siblings like consulta_cnpj or get_cnpj. It does not, however, explicitly name which sibling to use instead, leaving the agent to infer the distinction.

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 situational guidance for the flag ('set cnia_atual=true to require a CNIA source check') and a cost-check precondition ('Read GET /api/dossie/preco before spending'), plus a scope caveat ('screening aid, not an official certificate'). It never states when to prefer this over consulta_cnpj, reveal_cnpj, or avaliar, so sibling selection is left implicit.

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 well beyond the annotations by disclosing the charging model: failures and not-found lookups are not charged, a CNIA source failure returns 503 without charging or reusing a prior record, and the payment details appear in `uso` in the same response. It also explains that unrequested fields are omitted and null means an unchecked source. This is exactly the kind of cost/error-behavior context annotations cannot 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 sentences, front-loaded with the core purpose and the payment model, then the endpoint equivalence, then error/charging semantics. Mild redundancy between 'without an account' and 'no account, no allowance and no pack', but nothing is wasted overall.

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 still covers what comes back (the record plus payment info in `uso`), what happens on failure (402 unpaid, 503 on source failure, no charge), and that omitted topics mean omitted fields. The shape of the record itself is only described indirectly via the `temas` enum, which is the main remaining 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?

Schema coverage is 100% and the `temas` and `cnia_atual` descriptions are already extremely detailed, so the schema does the heavy lifting. The description adds nothing parameter-specific beyond the note that payment lands in `uso`; 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?

Names a specific verb+resource (CNPJ lookup returning the Federal Revenue record, sanctions, tax standing, address) and pins the scope to a paid-per-call, account-free variant mapped to GET /api/consulta/cnpj/:cnpj. It differentiates by business model rather than by naming the near-identical siblings (consulta_cnpj, get_cnpj, dossier_cnpj, reveal_cnpj), so an agent still has to infer which sibling to prefer.

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?

States the selecting condition explicitly: use this when there is no account, no allowance and no pack, because payment is per call. It also describes the interaction flow (unpaid request returns 402, paid request returns the record). It stops short of naming an alternative tool for the account-holding case.

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 read-only, idempotent, non-destructive and closed-world, and the description still adds substantial context beyond them: free with no account, personal details masked, null means unchecked, per-source freshness dates (import.dump_date, sancoes.conferidoEm, dividaAtiva.referencia), the CNIA staleness caveat, and the explicit disclaimer that this is not a credit-bureau report or official certificate.

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 a run-on of fragments with visible duplication: 'situacao.data is the status-change date' appears twice, the joined-sources claim is restated ('Receita, four CGU sanction registries, the TCU list and PGFN debt'), and freshness guidance is split between 'health' and 'import.dump_date at /api/health'. Useful content, but padding and repetition bury the front-loaded value.

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 the work of pointing at concrete response paths (data.situacao.label, data.sancoes.vigentes, data.dividaAtiva.inscricoes) and explains freshness, null semantics, masking and the report disclaimer. That is close to complete for a 2-parameter read, with minor gaps around pagination or response size.

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 schema already enumerates every temas value and states that omitting it returns the full record. The description reinforces which topics to request for this use case but adds no syntax, format or behavioral detail about the cnpj or temas parameters beyond what the schema provides — baseline 3.

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: retrieve registration status, public sanctions and federal tax debt already joined by CNPJ in one call. The line 'Check the company without consulting and combining each source separately' positions it against sibling lookups, though it never explicitly distinguishes itself from consulta_cnpj or dossier_cnpj, and in fact defers to consulta_cnpj for CNIA freshness, which slightly blurs the boundary.

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 calling pattern (set temas=dados,sancoes,divida) and an explicit alternative workflow for stale CNIA data ('require a source check during this request with consulta_cnpj and cnia_atual=true'). It does not state exclusions or when a sibling like dossier_cnpj is preferable, so it stops short of full when/when-not routing.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding context the annotations do not: that billing terms differ per payment method (Pix/USDC = 30 days non-renewing, card = monthly auto-renew) and that `account` comes back as `null` when no credential is supplied. That conditional-output behavior is exactly the kind of thing an agent cannot infer from 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 short sentences, front-loaded with what is returned before the billing nuance. The billing sentence is slightly dense ('Pix and USDC pay 30 days') but every sentence carries information an agent would otherwise lack.

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 carries the burden of explaining returns. It names the top-level shape (plans + `account`) and the null case, but never says what a plan record contains (price, interval, id) or whether the list is ordered or paginated, which leaves an agent under-informed about the payload it will have to reason over.

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. The description still adds the useful semantic point that the response shape depends on whether an account or wallet credential is present, which goes beyond an empty 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?

The description clearly states what the tool returns: the catalogue of plans for sale plus the caller's active plan. It is a readable listing tool, though it never distinguishes itself from similarly named siblings such as 'pricing' or 'consulta_planos', so an agent still has to guess which of them to call.

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: reading available plans is the natural precursor to 'buy_plan' or 'cancel_plan', and the payment-terms sentence hints at comparing options. There is no explicit statement of when to choose this over 'pricing' or 'consulta_planos', and no stated prerequisites.

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, closed-world, non-destructive, so the safety profile is covered. The description does add genuine value by explaining the quota computation and that over-quota watches carry `suspensa: true` and send no e-mail, which is output semantics not derivable from annotations – but it omits the shape of the returned list and any pagination or ordering behavior.

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 with the resource stated up front. The clause about the origin checking the quota 'inside the transaction' is internal implementation detail that doesn't help an agent invoke the tool, so it slightly dilutes an otherwise efficient description.

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-value burden; it discloses the suspensa flag and quota accounting, which is helpful, but never describes the overall structure of the returned watch list. For a read tool with a single well-documented parameter, this is adequate but incomplete.

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 (credito) with 100% schema description coverage, so the schema already documents it fully. The description adds no further meaning about the credit token, which is acceptable given the high coverage.

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 identifies the resource ('The CNPJs you watch') and mentions the quota annotation, but never uses a clear verb like 'list' or 'returns' – the action is only implied. It partially distinguishes from add_watch by describing existing watches, but an agent must infer the read/mutation distinction rather than read it.

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 statement of when to call this versus siblings such as add_watch or reactivate_watches, nor any prerequisite guidance beyond the schema's credito token. The quota explanation describes mechanics, not usage selection.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description contributes beyond that by disclosing the return shape (product, quota, pricing, billing, api_index), which is valuable since there is no output schema. It stops short of stating auth requirements or whether the pricing is live/cached.

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 lines, purpose front-loaded, then return shape — no filler. The brace-notation field list is slightly terse but still parseable.

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 is the only source of return-value information, and it supplies field names only. Fields such as live, free_now, charged_now, and trial are not explained, so an agent knows the shape but not the semantics — enough to decide to call it, not enough to interpret the response confidently.

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. The description correctly implies a parameterless call and adds nothing misleading about inputs.

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?

"Current prices and free allowances" names a concrete resource (pricing/quota data) and the second line enumerates what the caller gets back. It is clear on its own, but it never distinguishes itself from siblings like billing, consulta_planos, or api_access_buy, which plausibly overlap with pricing information.

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, when-not-to-use, or alternative-routing statement. An agent must infer that this is the tool to call before a purchase (api_access_buy) or before consulting plan-related siblings, with nothing in the text confirming or excluding that.

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 this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds genuinely useful commercial context — US$ 0.10 per slot, 30-day term, no auto-renewal, and no charge when nothing is paused — but does not explain what is returned, whether already-active companies are untouched, or how partial failures are handled.

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?

One dense sentence with no filler; the price and term are front-loaded and the no-charge guarantee closes it. The nested parenthetical ('the ones past the quota; their alerts wait') is slightly compressed but still 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?

With one param, a rich schema and no output schema, the description covers the essential economics but omits the outcome: how many companies were reactivated, total charge incurred, or what happens to companies that fail. For a tool that spends money on behalf of the user, that leaves a meaningful 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 single required parameter 'credito' is fully documented in the schema (100% coverage), including its format and issuing endpoint. The description adds nothing about it, so the baseline of 3 applies; the billing consequence of supplying a valid token is implied but never stated.

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 ('reactivates') on a specific resource ('paused companies of your credit wallet'), and the parenthetical clarifies what 'paused' means (past the quota, alerts waiting). It is distinguishable from add_watch/list_watches, though it never names those siblings explicitly to route the agent.

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 precondition ('with no paused company, nothing is charged'), so an agent can infer this is only relevant when paused companies exist. However, it never tells the agent to check list_watches first or compares itself to alternatives such as add_watch or billing.

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?

Beyond the annotations, it discloses the billing model (paid packs, no free allowance), a meaningful non-recharge rule for already-revealed companies, and the fact that GET /api/revelar/:cnpj only checks access without charging. It also bounds the result: unmasking does not verify ownership, current contact availability, or refresh the source. That is substantial behavioral context an agent cannot get from readOnlyHint=false / destructiveHint=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?

The pricing constraint is front-loaded, which is good, but the tail repeats itself: 'does not verify contacts or deliver a risk dossier' and 'does not refresh the source or provide a risk dossier' restate the same limitation twice. Two sentences could be cut without losing information.

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, non-read-only, unpriced-by-default tool with no output schema, the description covers cost model, preconditions, and the boundary of what is returned. What is still faint is the concrete shape of the payload (which fields of names/contacts come back), which matters slightly more given there is no output schema.

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 the schema documents it at 100% coverage, including the unpunctuated 14-digit / alphanumeric format. The description adds no syntax or formatting detail beyond the schema, so the baseline 3 for high coverage 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 opening sentence gives a concrete verb and resource: unmasking partner names and contacts for a CNPJ. It also carves out scope against unnamed siblings by saying it 'does not verify contacts or deliver a risk dossier,' implicitly separating it from dossier_cnpj. It stops short of naming the sibling tools (consulta_cnpj, get_cnpj, dossier_cnpj) that an agent would otherwise confuse it with.

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 sets clear preconditions and exclusions: a paid lookup pack or per-company quote is required, there is no free allowance, and the tool is not for verification or risk dossiers. It also steers the agent to 'reuse the company already selected instead of integrating another source,' which is real usage guidance. The gap is that no alternative tool is named for the verification/dossier cases it rules out.

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 read-only, idempotent, non-open-world, non-destructive, so the safety profile is covered. The description adds genuinely non-structured information: records are restricted to company-owned works, no official certificates are produced, and source dates/update status should be checked for freshness.

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 lookup keys, then filters, then scope and the add_watch pointer – the ordering matches how an agent would decide. Slightly dense: 'Check source dates and update status' is compressed and ambiguous, and pagination is never mentioned despite cursor/limite existing.

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 11-parameter, zero-required, no-output-schema search tool, the description covers discovery paths, filter dimensions, scope restrictions and the key caveat (no certificates). Minor gap: no mention that results are paged and that cursor must be reused with identical filters, though the schema carries that.

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 (uf, cno, cnpj, tipo, situacao, categoria, areaMin/areaMax, cursor, limite) is already documented. The description only restates the same dimensions at a high level and adds no format or interaction rules beyond the schema, so 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 a specific verb (Find) plus the exact resource (Brazilian CNO construction works) and enumerates the three lookup keys: 12-digit CNO, company CNPJ, or city+state. An agent can distinguish this from ref, search and consulta_* siblings 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?

Explicitly scopes the tool ('Only company-owned records are included') and routes monitoring elsewhere ('Use add_watch for company changes'), plus a clear negative capability ('does not issue official certificates'). It stops short of naming a lookup alternative for the cases this tool can't serve (e.g. finding a municipality name), which the schema leaves to the ref tool.

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 description explains why readOnlyHint=false matters (it consumes a paid lookup), discloses the 402 failure mode, the return path data.selo_sintonia with grade/cycle/validity or null, the legal reason other grades are hidden, and the no-double-charge rule for repeat checks in the same cycle. That is behavioral context well beyond what the annotations state.

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 in the first sentence, followed by cost, error behavior, return shape, and caching in descending order of importance. Every sentence carries distinct information with 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 still covers return structure, null semantics, error codes, and billing rules. An agent has everything needed to call this correctly and interpret the result.

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 cnpj parameter is fully documented in the schema, including the alphanumeric format. The description adds nothing about the parameter itself, 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?

The first sentence states a specific verb and resource: checks at Receita Federal whether a company appears on the public Sintonia A+ seal list. This is narrow enough that an agent can distinguish it from generic siblings like consulta_cnpj or get_cnpj, though no alternative is named 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?

It gives concrete operating context: one lookup from the paid package, no free quota, 402 with offers when balance is missing. It doesn't name a sibling to use instead for non-seal company data, so the when-not guidance is only implied.

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.