pontofato

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 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description only adds that lat/long are included in the result, with no mention of multiple-address returns, empty results for unknown CEPs, or error behavior — modest added value over annotations.

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 compact sentence with no filler, and the resource is front-loaded. Slightly terse, 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?

For a single-parameter read lookup with no output schema, the description adequately conveys what comes back (addresses plus coordinates). The main missing piece is sibling disambiguation, not core call correctness.

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 specifies the exact format ('8 digits, with or without the hyphen'). The description adds nothing about the single 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?

The description names a specific resource (addresses of a Brazilian postal code) and expands the CEP acronym, plus it indicates the returned payload includes latitude/longitude. It does not, however, distinguish this tool from siblings like consulta_cep or consulta_endereco, which plausibly overlap.

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 the many sibling lookup tools (consulta_cep, consulta_endereco, vizinhanca, raio). The agent must infer usage from the name alone.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial behaviour the annotations do not: result truncation (up to 20 addresses / 20 companies), the `pontos_total` counter field, a 10-per-day network-scoped free quota, and the exact error payload (`free_limit` with `resets_at`). It still doesn't say what happens with a malformed CEP or whether an API key is ever 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 dense sentences, front-loaded with the payload, then limits, then quota behaviour. Every clause conveys information an agent can act on; nothing is padded or repeated from the schema.

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 heavy lifting by naming the returned collections, their caps, and the `pontos_total` field, plus quota failure shape. It stops short of describing the structure of an individual address or company record, but it is sufficient to 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?

There is a single required parameter with 100% schema description coverage ('CEP with 8 digits'), so the schema already carries the semantics. The description adds no format, normalization, or example detail beyond that baseline.

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

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

Clear verb+resource: it retrieves addresses (with CNEFE/IBGE coordinates) and the companies registered at a given CEP. It is specific about the payload, but it never distinguishes itself from near-identical siblings such as `cep`, `consulta_endereco`, `consulta_cnpj`, or `empresas`, so the agent cannot be sure which one 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?

No statement of when to use this versus `cep` or `consulta_endereco`, and no prerequisites beyond the implicit 'have a CEP'. The only conditional guidance is the post-quota failure mode, not usage 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing rate limits (10 free lookups per day per network, with `resets_at` in the failure response), personal-data masking, the 'null means unchecked' convention, and that unrequested blocks are omitted. These are exactly the operational details an agent cannot infer from the schema.

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 and the key operational caveats are front-loaded, which is good, but the middle is a single sprawling sentence enumerating a dozen data domains. It earns its length partly by substituting for an absent output schema, yet it is dense enough to be hard to scan.

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 return-value semantics, and it does so thoroughly: it enumerates the returned blocks, explains topic selection and omission, masking, and the one error path. The remaining gap is sibling differentiation against lookups such as consulta_cadastro or empresas.

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 a genuine nuance by stating the CNPJ may be numeric or alphanumeric (the schema only mentions punctuation), plus the live-check semantics of `sancoes`. The `temas` topic list is largely duplicated from the schema, so it does not push this higher.

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 — a live Brazilian company record keyed by CNPJ from Receita Federal — and enumerates the exact data domains returned (sanctions, PEP lists, tax status, contracts, regulators). The scope is unmistakable and clearly distinct from sibling lookups like consulta_cep or consulta_endereco.

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 real usage context: 'useful to vet suppliers' and the guidance to pass `temas` or omit it for the full record. It also documents the free-tier ceiling and the resulting `free_limit` state. It stops short of naming when a sibling (e.g. consulta_cadastro) is the better choice, so no explicit exclusion is offered.

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 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 non-read-only, non-idempotent, non-destructive; the description goes well beyond that. It discloses the queueing rate-limit behavior (a message arriving sooner waits its turn, no error), that delivery is by e-mail with `email` as reply address, the multipart/form-data alternate path with exact size caps (32 KiB JSON, 2 MB audio), and accepted audio formats.

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 and most sentences carry real information (rate limit, multipart, delivery). There is mild redundancy between the first sentence and the 'One route for a question and for a sponsorship...' sentence, and the mention of `GET /api/partners` as a separate route is slightly disorienting.

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 and 94% schema coverage, the description covers behavior well: limits, queueing, delivery, and the alternate voice format. It omits any statement about the success/failure response or authentication, which is a modest remaining gap given no output schema exists.

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 94%, so the schema carries most parameter meaning (baseline 3). The description adds genuinely non-schema information: the behavior of `tipo` turning on dependent fields, and the entire multipart `dados`/`audio` input format that does not appear in the JSON schema at all.

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

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

The description opens with a specific verb and resource: 'Write to the people behind the product', and enumerates the two supported cases (a question, or a sponsorship/partnership/ad proposal). The phrasing is slightly loose ('the people behind the product'), but an agent immediately knows this is the contact/submission tool, and no sibling overlaps with 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?

It explains the selector (`tipo`) that switches between a question route and the proposal fields, and states the rate-limiting behavior (one message every 10 seconds per network, queued rather than errored). It does not give explicit when-not-to-use guidance, but with no competing sibling that gap is minor.

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?

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. 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds what is returned (active/opened/closed companies, recent openings, distance), which is useful context beyond the annotations, but it does not disclose limiting behaviors such as result caps, pagination, or default-window effects.

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, stating scope first. It is slightly run-on, packing output characteristics (recent openings, distance) into the same clause as the filter, but no sentence 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 and 6 parameters, the description should carry more of the return-shape burden. It hints at returned fields but omits the defaults for raio (500m) and desde (90 days) and says nothing about output volume or ordering, leaving the agent with gaps for a fairly complex spatial query.

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 is already documented and the baseline is 3. The description adds only marginal clarification (CNAE glossed as 'activity code', radius in meters), both of which the schema already states.

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 scope: companies (active, opened, closed) within a radius, filtered by CNAE, with recent openings and distance. It is clearly distinguishable from generic siblings like buscar or consulta_cnpj. However it never names the closest-looking siblings (raio, proximo, cep) to disambiguate.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named, despite 'raio' and 'proximo' being plausible competing tools for spatial queries. The agent must infer the use case entirely from the name and description.

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