pontofato

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful disclosure of the returned payload shape, but it does not say whether the discovery mode is unauthenticated, whether an invalid api_pass errors or simply falls back to discovery, or how purchasing relates to this read.

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?

Purpose is front-loaded in one sentence, and the long nested return-shape list earns its space somewhat because there is no output schema. The enumeration of offer fields is dense and unannotated (the ? markers are never explained), but it is not padded with filler prose.

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 inline return shape usefully compensates for what would otherwise be missing. However, the dual-mode behavior, error behavior for a bad pass, and the relationship to the purchase sibling are all left unspecified, which is a real gap for a tool whose only parameter changes its meaning.

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 api_pass parameter already documents its format and the need to save it before buying. The description only implies that api_pass switches to the "inspect a private purchase" mode, adding modest meaning beyond the schema — the baseline of 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 two concrete operations: discovering the monthly data package (offer) and inspecting a private purchase. That is clear verb+resource, but it never distinguishes this tool from the sibling api_access_buy, so an agent has to guess which one initiates a purchase versus previews one.

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 statement about when to supply api_pass versus omit it, and no reference to the obvious alternatives api_access_buy or api_index. Usage is only inferable from the word "or" in the first sentence, which leaves the agent to reconstruct the two-mode logic.

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

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

With annotations only covering hints, the description carries useful extra context: price, 30-day validity, no automatic renewal, retry recovery, and how the pass/credits headers appear on subsequent reads. Note a mild tension: 'Same pass in retries recovers the same purchase' reads as idempotent behavior while idempotentHint=false, though the hint plausibly refers to the call itself rather than same-pass reconciliation. It never states what happens if payment and api_pass disagree or whether a failed signed payment charges anything.

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 commercial terms are front-loaded in the first sentence, then retry, renewal and payment-alternative details follow in short clauses. Some of the header mechanics ('Send X-API-Pass on eligible data reads') belong more to the read tools than to a purchase and make it slightly longer than necessary.

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 tool with no output schema it covers cost, duration, retry safety, renewal policy and the credit alternative — enough for an agent to act correctly. It omits the shape of the successful response (e.g., whether the pass is echoed back or only credits remain) and failure modes for invalid signed payments.

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 each of the four parameters already has its own description, so the description is not required to compensate. It adds no parameter-level detail beyond naming the X-API-Pass / X-Credito / Bearer cred_ mechanisms at a conceptual level, 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?

The first sentence gives a concrete verb, unit, price and validity window ('Buy 1000 basic data reads for US$1, valid for 30 days'), which tells an agent exactly what the tool transacts. It also fences off sibling scope by noting OCR, AI, documents and delivery have their own tariffs, so an agent won't confuse this with the other access/pricing tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies an explicit alternative path ('With prepaid credit, you can skip this purchase: send X-Credito…') and a retry condition ('Same pass in retries recovers the same purchase'), which is real routing guidance. It stops short of stating preconditions such as what to do if a pass is already held or which data reads are 'eligible', leaving a small amount of 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only a hint at the payload contents, which is modest value; there is no note on caching, cost, or freshness of the route index.

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, front-loaded sentence with no filler. It is efficient, though its brevity shades into under-specification rather than pure 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?

With no output schema, the description carries the burden of explaining the return value, and it only sketches it ('each route and how to connect the MCP'). For a zero-param discovery tool the stakes are low, but an agent still lacks detail on the shape of the index or when it should be consulted.

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 is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies a parameterless call by describing pure content retrieval.

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 the resource ('the API index') and what it contains ('each route and how to connect the MCP'), so the agent can infer it is a discovery/listing endpoint. However, it is a noun phrase with no verb, and nothing distinguishes it from siblings like 'health' or the various consulta_* routes beyond a vague notion of an index.

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 mention of alternatives among the fifteen sibling tools. The agent must guess whether this is a bootstrap/discovery call or an informational endpoint to consult in some other circumstance.

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 readOnly/idempotent/non-destructive, so the description is free to add the part annotations cannot: the exact return contract, including nested payment fields (provider, mode, network, chain_id, homolog, dev_gate, faucet) and the credit url/header. With no output schema present, this return-shape disclosure is genuinely additive rather than redundant.

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 sentence is front-loaded and short, which is good, but the return contract is dumped as one deeply nested brace blob with optional markers ('free_now?', 'gratis?') that is hard to parse. It earns its place content-wise but the formatting undermines readability.

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-arg, read-only tool the return contract is the main thing an agent needs, and it is provided in full. What is missing is the selection rationale against the pricing and consulta_planos siblings, so the definition is complete on payload but incomplete on routing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-arg tool is 4. The description correctly implies the call is unconditional and requires no input.

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 phrase 'Public discovery of payment and prepaid credit' gestures at the resource but uses an abstract noun ('discovery') instead of a concrete verb+resource. The long return-field list does reveal that it covers payment, pricing, billing and credit, but an agent must reverse-engineer the purpose from the payload shape rather than the opening sentence.

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 the overlapping siblings pricing, consulta_planos, api_access, or api_access_buy. The word 'Public' hints that no auth is needed, but no exclusions or alternatives are given, leaving the agent to guess which billing-adjacent tool to pick.

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 (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely non-structured behavior: a hard cap of 20 results, the aggregation rule of one result per street per city, and the conditional behavior where a house number present in the query yields the point of that number. What is missing is failure/empty-result behavior and whether results can be expanded beyond 20.

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 dense sentences with the core capability front-loaded and the conditional house-number behavior placed second where it belongs. No filler; slight compression makes the first sentence a little awkward to parse but nothing is wasted.

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 carry the return-shape burden and largely meets it (result cap, deduplication per city, conditional point). Parameters are fully covered by the schema and the read-only nature is declared by annotations. Remaining gaps are edge-case behavior (zero results, pagination) rather than anything blocking a correct call.

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 q, uf and cidade, making a baseline of 3 appropriate. The description adds only marginal meaning ('by name (or by neighborhood)'), and neighborhood is not even a schema parameter, which leaves a small mismatch between the prose and the actual 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?

It states a specific verb and resource ('Finds a street by name (or by neighborhood) in Brazil') plus a scope constraint (up to 20 results, one per street per city). That is far more precise than the bare name 'buscar' or the title 'Find a street'. However, it never names or distinguishes itself from close siblings such as consulta_endereco, proximo, or raio, so an agent cannot tell from the text alone which address tool 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?

The description explains what a query may contain (street name, neighborhood, house number, city) but gives no when-to-use or when-not-to-use guidance. With siblings like cep, consulta_cep, consulta_endereco, vizinhanca and proximo all in the same address domain, the absence of any routing cue is a real gap.

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), yet the description adds substantial context beyond them: data vintage is 2022, census measures describe the sector rather than an individual or the whole postal code, income is not current purchasing power, and company counts are not foot traffic. These are real interpretive constraints an agent would otherwise get wrong. It stops short of saying what the payload looks like or how large it can be.

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?

Purpose is front-loaded in the first sentence, followed by sourcing and then caveats in a compact sequence. The caveat list is dense but each clause warns about a distinct misinterpretation; minor cost is that the trailing caveats read as a run-on list.

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 tool with no output schema, the description does indicate the return content (addresses plus latitude/longitude) and flags the main semantic traps in the data. It lacks any statement about result volume or fields per address, which is the only 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?

Schema description coverage is 100% and the single 'cep' parameter is already documented as '8 digits, with or without the hyphen'. The description adds no format, normalization, or error-handling detail for that parameter, so the schema carries the full burden and the baseline of 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 concrete resource and output: 'The addresses of a CEP (Brazilian postal code), with latitude and longitude', and discloses the underlying data sources (CNEFE, company records, census sectors). It is clear what the tool returns, but it never differentiates itself from close siblings such as consulta_cep, consulta_endereco, or buscar.

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 sentence 'Use the prepared result instead of importing and joining those datasets' gives one usage rule, but it is guidance about reimplementation, not about when to pick this tool over the many sibling address/CEP tools. There are no exclusions or alternative-routing hints.

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 it read-only, idempotent and non-destructive, and the description adds genuinely new operational context: it does not count against the daily free limit, shows no contacts or partners, runs no extra checks, and the origin's protection limit still applies. These are behavioral traits not derivable 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 tight sentences, front-loaded with the field scope, then the constraints, then the alternative. Every clause carries information; none is padding.

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?

Although there is no output schema, the description enumerates the returned fields and the exclusions, plus cost/limit behavior. An agent has everything needed to invoke it 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?

Single parameter with 100% schema description coverage; the schema already explains CNPJ accepts punctuation or not. The description only restates 'by CNPJ', adding no meaning beyond the schema, 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 enumerates the exact fields returned (name, status, activity, address) for a Brazilian company by CNPJ. It also distinguishes itself from the sibling consulta_cnpj by naming what it does not cover, so an agent can tell the two apart 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?

Explicitly routes the agent: 'For sanctions, tax status and a live CNIA check, use consulta_cnpj.' This names the alternative and the conditions that select it, 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, and non-destructive, so the safety bar is low. The description adds genuinely new context: result caps (up to 20 addresses, 20 companies), the pontos_total field for the real address count, and the free/no-balance billing behavior — none of which appear in 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?

Two sentences, no filler: the first defines the resource, the second covers the return caps, the total-count field, and billing. Return limits and pricing are front-loaded where an agent will see them.

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 its duty by explaining what comes back, the caps, and the pontos_total field so the agent knows the 20-item limit does not mean 20 total addresses. Minor gap: it doesn't describe the shape of the coordinate or company fields, but overall it is sufficient to call 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?

There is a single parameter (cep) with 100% schema description coverage ('CEP with 8 digits'), so the schema fully carries parameter meaning. The description adds nothing about format or normalization of the CEP, 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?

The description states a specific resource (addresses at a CEP with CNEFE/IBGE coordinates) plus the companies registered there, which distinguishes it from a plain CEP lookup or CNPJ lookup. It stops short of naming which of the many sibling tools (cep, consulta_endereco, empresas, consulta_cnpj) it supersedes, so the differentiation is implied rather than explicit.

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 returned data (you use it when you want addresses AND companies for a CEP), and the 'Free: it uses no daily allowance or balance' note gives useful cost guidance that helps an agent choose it over metered siblings. However, there is no explicit when-to-use/when-not statement or named alternative among the crowded sibling set.

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 adds substantial behavior beyond the read-only annotations: a failed required CNIA check returns 503 without charging or falling back to a previous record, while omitting cnia_atual may return stored CNIA data with conferidoEm as the freshness indicator. It also discloses topic-omission behavior and that the free allowance is applied before lookup balance or per-call payment.

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 dense but front-loaded, and each sentence carries a behavioral or usage fact. It loses a point for unexplained shorthand such as 'Additional' and 'conferidoEm', which make the structure less immediately clear 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 a three-parameter lookup tool with no output schema, the description covers the important failure modes, caching/freshness behavior, topic selection, and billing order well. It still leaves the exact return shape and the precise meaning of conferidoEm to be inferred.

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 baseline is 3. The description reinforces the meaning of cnia_atual and temas, but it does not add syntax or format details beyond what the schema already documents.

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: a CNPJ lookup that returns prepared public records and can attempt a live CNIA source check. It is clear enough to understand the operation, but 'Additional CNPJ lookup' is vague and it does not differentiate itself from sibling tools such as consulta_cadastro, empresas, or get_api_x402_cnpj_by_cnpj.

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 useful parameter-level guidance: set cnia_atual=true when the live source check is required, and select temas to load only needed blocks. However, it never explains when to choose this tool over the many sibling CNPJ/company lookup tools, so usage remains implied rather than explicit.

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 declare readOnly=false, idempotent=true, destructive=false; the description goes well beyond them, disclosing the 402-price response, the x402 v1 body vs v2 PAYMENT-REQUIRED split, balance custody rules (account/credit holder vs the x402-confirming wallet), the mmw_… credential flow via wallet_start/wallet_token, and 30-day plan vs 90-day package validity with no auto-renewal. It stops short of describing the success response body, which is the main remaining gap.

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?

Purpose is front-loaded in the first sentence, but the remainder is a dense, run-on block where several clauses (credential retrieval, custody of balance, expiry windows) are compressed into single sentences and require re-reading. Each fact is relevant, but the sequencing mixes response format, identity semantics, and duration rules without clear structure.

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 tool with no output schema and four interacting auth modes, the description covers the failure path, credential acquisition, and validity periods, which is substantial. It leaves the successful purchase response and how the resulting lookup quota is consumed undocumented, which an agent would need before calling.

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 (compra, oferta, payment, credit_token) is already documented, and the description adds no syntax or format detail for any of them. It does reinforce the idempotency semantics of the repeat-with-same-mark behavior at the conceptual level, which aligns with the schema, but the schema is doing 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 and resource: buys the single package or one of the three plans, and names both payment rails (credit or x402) plus the no-account case. It never names a sibling (e.g., consulta_planos for browsing, api_access_buy for API access), so the boundary with adjacent tools is left implicit, but the purchase action itself is unambiguous.

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: the mention that an unpaid call returns 402 with the price implies you should call this to obtain a quote, and that offers come from a prior lookup. There is no explicit when-to-use vs. when-not, no pointer to consulta_planos or pricing as the way to discover offers, and no guidance on choosing credit_token vs payment.

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 goes beyond them with real operational context: quota treatment (no charge against the daily free limit), result caps (20 addresses / 20 companies), and the caveat that the origin's protection limit still applies. Return-format details remain thin, keeping it short of a 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 compact clauses, front-loaded with what the tool returns and immediately followed by the most decision-relevant fact (no quota cost). No filler sentences, though the `pontos_total` field reference sits slightly awkwardly mid-sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full annotation coverage and no output schema, the description supplies what an agent needs: scope, caps, a named response field, and quota behavior. Nothing consequential to 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?

With one parameter at 100% schema description coverage, the schema already documents `cep` including hyphen tolerance. The description adds only the gloss '(Brazilian postal code)', which is mildly helpful but not semantic content the schema lacks. 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 names the resource precisely — addresses and companies at a Brazilian CEP — and even clarifies the acronym for non-Brazilian readers. The retrieval verb is implicit but unambiguous. It does not, however, distinguish itself from near-identical siblings such as consulta_cep and cep, so an agent must still guess which of those overlaps 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?

There is no statement of when to use this tool versus consulta_cep, cep, consulta_cnpj, or empresas, despite the sibling list containing at least two plausibly overlapping CEP lookups. Quota remarks ('does not count against the daily free limit') hint at a preferred use case but never convert that into explicit routing 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 already declare readOnly, idempotent, and non-destructive, so the safety bar is low; the description still adds real value by disclosing that output varies by credential type, naming the X-Credito and X-Wallet-Token headers, and noting the balance is shared across Radar CNPJ, PontoFato and EditalMD. It stops short of describing response shape or ordering, but there is no output schema for it to duplicate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each carrying distinct information: what is returned, how credentials change it, and where wallet credentials come from. The lead sentence is a little dense and the colon construction is awkward, 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 input parameters and no output schema, the description covers the two things an agent needs: what data comes back and how authentication state changes it. The added note that the wallet credential is issued separately per portal prevents a predictable failure mode.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The credential headers mentioned are transport-level context rather than schema parameters, and the description handles them appropriately.

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 concrete payload the tool returns — today's free allowance, the single package, the three plans, and the balance — which goes well beyond the bare title 'Lookup plans'. However, the opening framing ('The CNPJ and address lookup service') is slightly misaligned with a plans/pricing resource and doesn't explicitly distinguish it from siblings like 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 implied through the credential-conditioned behavior: without a credential you get the free allowance and offers, with credit or an x402 wallet you additionally get the shared balance. That tells an agent what it can expect in each state, but it never states when to pick this over the pricing or billing siblings.

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 it safe (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds non-obvious behavior: no quota consumption, no contact data returned, and the meaning of the `incompleto` condition. That is genuine added context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences: the core behavior and ordering come first, followed by the quota/contact caveats and the `incompleto` note. Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and covers the main points (list of up to 8 ordered matches, no contacts, `incompleto` marker). Only a fuller sketch of the returned fields is missing, which is minor for a suggestion endpoint.

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` parameter is fully documented in the schema with length bounds and accepted formats. The description adds no syntax or format detail beyond that, 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 verb (suggests) and resource (Brazilian companies) with scope (up to 8) and ordering (best match first). The note that it 'does not show contacts' implicitly separates it from the fuller consulta_cadastro, but no sibling 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?

The remark that it 'does not count against the daily free limit' hints at when it is preferable, and the no-contacts note implies a lightweight lookup, but there is no explicit statement of when to use this instead of buscar, sugerir, or consulta_cadastro.

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 declare readOnly=false, idempotent=false, and destructive=false. The description adds substantial behavioral context beyond that: rate limiting every 10 seconds per network with queuing rather than error, no captcha/account/payment, email delivery with `email` as reply address, multipart audio limits, and that audio can replace the message.

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 and structured around purpose, constraints, and multipart audio. It is somewhat repetitive, however, restating no captcha/no payment and the 10-second throttle twice, so not every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter tool with no output schema, the description covers critical operational details: throttling, no captcha/account/payment, email delivery, and multipart audio size/duration constraints. It leaves a use-case gap by not mentioning the `consultoria` branch present in the 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?

Schema description coverage is 100%, so the baseline is 3. The description adds useful cross-field meaning: `tipo` selects the proposal route, `espaco` references placements from `GET /api/partners`, and voice uses `dados` plus an `audio` file that can replace `message`.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb phrase, 'Write to the people behind the product,' and names the main use cases: questions and sponsorship/partnership/advertising proposals. This is enough for an agent to distinguish this contact tool from the API/billing/search siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains when to use the tool for a question or a proposal and gives concrete voice-message usage via multipart/form-data. However, it does not state explicit exclusions or alternatives, and it omits the `consultoria` branch that the schema exposes, so it falls short of a full 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the burden is lower. The description adds the 50-per-page result cap, which is genuinely useful behavioral context, but says nothing about ordering, empty-result behavior, or lookup failures.

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 the resource stated first and no filler or preamble. The trailing "up to 50 per page" is slightly redundant with the schema's page description, which keeps it from being maximally tight.

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 simple two-parameter lookup whose safety traits the annotations already declare, the description is arguably sufficient to call the tool. However, with no output schema, it never indicates the shape or fields of a returned company record, leaving the agent to guess at the response.

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 both parameters (cep, page) are fully documented inline, including the 8-digit format and 0-based paging, so the baseline is 3. The description's "up to 50 per page" only restates the schema's page semantics rather than adding new meaning.

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 companies registered at a CEP" names a concrete resource and the exact filter (postal code), so an agent knows it returns companies tied to a CEP rather than a single company or an address. It does not distinguish itself from area-style siblings such as raio, vizinhanca, or unidades, which likely overlap in purpose, so it stops short of 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?

The description gives no when-to-use guidance and never names an alternative, even though the sibling list contains several overlapping lookup tools (consulta_cnpj, raio, vizinhanca, unidades). The only implicit usage signal is the pagination cap, which is about mechanics, not tool 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?

The description adds substantial behavioral context beyond the annotations: payment is per call, unpaid requests receive 402, successful responses include payment details in `uso`, and failed or not-found lookups are not charged. This is exactly the kind of billing and failure behavior an agent needs before invoking a paid tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and efficient, covering purpose, payment model, and charge behavior in three sentences. There is minor repetition around no account/no allowance/no pack, but it does not obscure the key 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 three-parameter tool with full schema coverage and no output schema, the description is largely complete: it explains the payment flow, the 402 case, and what happens on failure. It could say more about how payment is supplied or the exact response shape, but the essential invocation context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description does not add parameter-level meaning 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 operation — a CNPJ lookup — and identifies the returned record contents (Federal Revenue, sanctions, tax standing, address). It also distinguishes this variant by payment model (paid per call, no account), though it does not explicitly name the closest sibling such as consulta_cnpj.

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 context for use: agents without an account, allowance, or pack. It also explains the 402 response when payment is absent, but it does not explicitly compare against named alternatives or state when not to use this 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that: no indication of what the response contains, how current the availability data is, or what 'UF' means. With annotations carrying the safety load, this adds almost nothing.

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 front-loaded sentence with no filler, appropriate for a zero-parameter status endpoint. The only weakness is the unexplained abbreviation '(UF)' and the vague phrase 'address coverage'.

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 no parameters, so the description is the only source of information about the return value. It hints at two data sets (availability, per-state coverage) but does not explain their shape or meaning, leaving a modest gap for a diagnostic endpoint.

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. No parameter-level information is missing.

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 ('service availability') and an additional data dimension ('address coverage by state (UF)'), so an agent can broadly tell this is a status/coverage endpoint. However, it uses no verb and leaves 'coverage' ambiguous (coverage of what, counted how), and it never distinguishes itself from the many lookup siblings. It is understandable but not sharp.

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 tool, no prerequisites, and no mention of alternatives among the many sibling lookup tools. An agent must infer usage entirely from the name.

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 destructiveHint=false, so the safety profile is fully covered. The description adds the return envelope (product, quota breakdown with optional free_now/charged_now/trial flags, pricing, billing, api_index), which is genuinely useful given there is no output schema, but it says nothing about auth requirements, freshness of prices, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two lines, front-loaded with the purpose and followed by a compact field list; every token earns its place and the optional fields are marked with '?' rather than spelled out.

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 return-value burden and does so by enumerating the top-level keys and quota sub-fields. It stops short of explaining semantics of fields like 'live' or 'how_to_pay', which would fully close the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly does not waste space inventing parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete resource ('current prices and free allowances'), so an agent knows exactly what data comes back. It does not, however, distinguish itself from overlapping siblings such as 'billing' or 'consulta_planos', leaving ambiguity about which price-related tool 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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The only signal is the tool's name and the phrase 'current prices', which forces the agent to infer usage from the surrounding tool list.

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 destructiveHint. The description adds only that missing/empty values don't become zero and that (0,0) is only used when sent. It doesn't explain what is returned, error conditions, or limitations for a geocoding lookup beyond what annotations cover.

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 two short sentences with no wasted words. The purpose is front-loaded; the next sentence elaborates on an edge case.

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 lookup tool with no output schema and many sibling geocoding/address tools, the description lacks sufficient context on return values, coordinate system assumptions beyond WGS84 (which is in schema), or how it differs from similar tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema documents lat and lon fully. The description adds a small clarification about missing values not being zeroed and the (0,0) sentinel, but this is marginal 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 (find) and resource (nearest address) and gives the inputs (lat, lon). It does not explicitly differentiate from siblings like consulta_endereco, consulta_cep, or vizinhanca, but the purpose is clear.

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?

No guidance on when to use this tool versus alternatives such as consulta_endereco or vizinhanca. Only a caveat about (0,0) and missing values is provided, which is not usage 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds two useful pieces beyond that: the response includes distance and addresses, and the operation is 'Free' (cost context). It does not cover error behavior, the 1-2000m bounds, or what happens with ambiguous input.

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 front-loaded sentence covering what is returned, followed by a one-word cost note ('Free.') that carries real signal. No filler, though the sentence is dense enough that the input/return distinction takes a second read.

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 correctly summarizes the return (distance and addresses). All parameters are optional yet the tool logically needs either a cep or a lat/lon pair; the description implies this but never states it explicitly, 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%, so all four parameters (cep, lat, lon, raio) are already fully documented with defaults and ranges. The description restates the center-point options and the radius in prose but adds no syntax or format detail beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: returns the CEPs within N meters of a point, plus the distance and addresses. It is immediately clear what the tool does, but it does not distinguish itself from close siblings such as vizinhanca or proximo, which likely also deal with nearby locations.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The parenthetical '(a CEP, or a latitude and longitude)' clarifies accepted input forms but is not a usage rule, leaving the agent to guess how this differs from vizinhanca, proximo, or cep.

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

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

With readOnlyHint/idempotentHint already declaring the safety profile, the description adds substantial extra context: an eight-result cap, the 3-to-8-digit CEP prefix rule with optional hyphen after the fifth digit, and the provenance/limitation that data is CNEFE 2022 and does not certify the current postal CEP. Only pagination/ordering behavior is left unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool returns and the result cap before drilling into format rules, so the agent gets the essentials first. Slightly dense and run-on in the middle sentences, but every sentence adds a distinct fact rather than padding.

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 carries the return-value burden: it discloses the shape (up to eight places with neighborhood and city) and the caveat that one address represents each CEP. For a three-parameter read-only suggestion tool this is nearly complete, with only result ordering/pagination unaddressed.

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 already 100%, so the baseline is 3. The description adds meaning beyond the schema by spelling out the accepted CEP input format (3-8 digits, optional hyphen after the fifth) and clarifying that uf/cidade only constrain the street-search branch, not the CEP branch.

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 (suggest) and resource (partial CEP or street name) with concrete scope: up to eight places, each with neighborhood and city. It implies a distinct role from a full lookup tool ('the full lookup returns the others') but never names the sibling (buscar, consulta_cep) it is meant to complement.

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?

Conveys the usage context well: partial input for typeahead-style suggestions, with format rules for CEP prefixes and optional UF/city for street search. However, it never states when an agent should pick this over buscar/consulta_cep/consulta_endereco, and the reference to 'the full lookup' is left unnamed.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it discloses that results are paginated ('in pages'), that omitting `logradouro` and `numero` causes paging through the entire CEP, and it describes the returned fields ('complement' and 'type').

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 what the tool returns and followed by the key distinction from the CEP lookup and the filtering behavior. Every sentence contributes to understanding; no redundant or vague phrasing.

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 adequately compensates by naming the returned fields (complement, type) and the paginated nature of results. It also covers the interaction of the optional filters. It does not explain error handling or the exact pagination metadata, but for a read-only, idempotent tool with fully described parameters, this is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the interaction between the optional `logradouro` and `numero` filters and the default behavior: without them, the tool pages through all units of the CEP. This clarifies the filtering role of those parameters in a way the individual schema descriptions do not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource ('units at a CEP (apartment, store)') and what is returned ('with the complement and the type, in pages'). It clearly distinguishes this tool from the CEP lookup sibling by explaining that the lookup groups by street and number while this tool returns each unit.

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 provides a clear context for use: when you need individual units rather than the grouped CEP level. It also states the condition 'Without `logradouro` and `numero`, it pages through the whole CEP,' which helps the agent decide when to supply those filters. However, it does not explicitly name an alternative tool to use when this tool is not appropriate, so a 4 rather than 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 and idempotent, and the description adds substantial behavioral context beyond them: data vintage (CNEFE 2022), geocoding basis (postal codes), response flags (base, truncado, lenta), missing-count semantics ('unknown, not zero'), and billing behavior ('lenta:true or missing counts does not consume the allowance or charge credit/x402'). That billing and data-quality disclosure is exactly the kind of 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?

The purpose and scope are front-loaded in the first sentence, and the sentences are short with little padding. It loses a point because terse fragments like 'Check base, truncado and lenta' introduce unexplained jargon without saying what those flags mean or where they appear.

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 what comes back, and it does mention counts, recent openings, distance, and the base/truncado/lenta flags plus missing-count semantics. It stops short of explaining what base and truncado actually signify, which leaves an agent guessing about result validity.

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 cep/lat/lon/cnae/raio/desde are already documented, and the baseline of 3 applies. The description adds modest value by reinforcing CNAE as an activity code, radius in meters, and that positions derive from postal codes, but it does not clarify precedence between cep and lat/lon or the 'desde' default relative to the data date beyond what the schema says.

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+resource: companies (active, opened, closed) within a radius in meters, filtered by CNAE, returning recent openings and distance. An agent can tell it is a geographic proximity count/list tool. It does not explicitly name the sibling it supersedes (raio, proximo, empresas), so differentiation is inferred 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?

'Query the neighborhood without downloading and indexing both datasets' implies the use case (avoid ingesting two datasets), and the closing sentence gives a clear when-not ('does not measure foot traffic, demand or exact storefront positions'). However, no sibling alternative is named and no explicit trigger conditions ('use this when you have a CEP and want counts by activity') are given.

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