IBGE Brasil MCP

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context on top: an unknown id returns an error, and retrieval is a live GET against the public source that only happens when needed. It does not discuss rate limiting or failure modes beyond the unknown-id case, so it stops 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?

Front-loads the return contract, then the contract/scope, then behavior. Every sentence carries information, though the documented return field list duplicates the output schema and could be trimmed.

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

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

An output schema exists, so the return-value enumeration is partially redundant, but the description still supplies the retrieval contract, the valid-id precondition, and the routing away from `ibge_*` siblings. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented in the schema. The description reinforces that the id must come from `search`, which is useful, but adds no format or syntax detail beyond it. 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 full document for an id'), names its companion tool `search`, and explicitly distinguishes itself from the `ibge_*` data-query siblings. An agent can route between retrieval and query without opening a schema.

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

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

Gives explicit when-to-use ('id obtained from search'), a when-not alternative ('the ibge_* tools remain the tools for data queries'), and a validity constraint ('only ids returned by search are valid'). This is close to a complete routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value beyond them by naming the underlying live GET to the public Calendário API and the return format (Markdown list). Minor gap: pagination behavior via pagina/quantidade is not characterized.

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

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

Front-loaded one-line purpose followed by Features, Event types, Examples, and routing sections. Every section carries distinct, non-redundant information and the examples are compact.

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

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

Given an output schema exists, return values needn't be detailed, and safety is covered by annotations. The description still rounds out domain concepts (Release vs Collection event types) needed to interpret the results correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all six parameters. The description's examples tie parameter names to concrete values (produto="IPCA", de/ate date range, tipo="coleta"), which adds useful usage semantics 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?

States a specific verb and resource (queries the IBGE release/collection calendar) and enumerates what it covers. It explicitly distinguishes itself from the sibling ibge_noticias, so an agent can route correctly without opening schemas.

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

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

Provides explicit when-to-use context plus a 'Use a different tool when' section routing already-published news to ibge_noticias. Concrete examples (no params for upcoming, produto="IPCA", date range, tipo="coleta") map conditions to calls.

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/openWorld/destructive=false, so the safety profile is covered. The description still adds beyond them: it states the call is a live GET against the public IBGE SIDRA API and the return shape (Markdown plus typed structuredContent), and it flags that in statistics mode campos/formato are ignored and registros comes back empty.

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

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

Front-loaded with purpose, then years, themes, examples, mode notes, and alternatives in a scannable structure. Slightly long because the theme bullets duplicate the schema enum descriptions, but nothing is genuinely wasted and the ordering is logical.

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 9-parameter, output-schema-backed tool this covers everything an agent needs: scoping, alternatives, mode switches, worked examples, and return format. The presence of a structured output schema means return-value detail is not required, and routing guidance is fully 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 baseline is 3, but the description adds real meaning above the schema: the estatisticas cross-parameter effect (campos/formato ignored, registros empty), the agruparPor ranking behavior with short-label resolution and refusal on ambiguous labels, and the pre-pagination computation semantics.

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 ('Queries IBGE Demographic Census data (1970-2022)') and immediately scopes it apart from the raw SIDRA tools by noting it works 'without knowing SIDRA table codes'. An agent can distinguish it from ibge_sidra 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?

Contains an explicit 'Use a different tool when' block naming three alternatives (ibge_cidades, ibge_comparar, ibge_sidra) with the condition that selects each, plus worked examples and a dedicated statistics mode for largest/smallest/mean questions. When-to-use is fully specified.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds useful context beyond annotations: it identifies the underlying source ('live GET against the public IBGE APIs (Cidades@/agregados)') and the return shape ('Markdown plus a typed structuredContent payload'). It does not discuss rate limits or error modes, but with annotations covering behavior, this is solid.

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

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

Front-loaded with the core purpose, then cleanly sectioned into features, available indicators, runnable examples, sibling routing, and behavior. Every block is scannable and earns its place, with no redundant 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?

An output schema exists, so return values need not be described beyond the brief note about Markdown plus structuredContent. Combined with the valid-indicator list and examples, the definition gives an agent everything needed to call a five-parameter, zero-required tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real value: it enumerates the valid indicator identifiers (populacao, area, densidade, pib_per_capita, etc.) that the schema does not contain, and gives concrete example parameter combinations (tipo="historico", municipio="3550308", indicador="populacao") that clarify how tipo interacts with the other fields.

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 (queries) and resource (municipal indicators), and explicitly frames the tool as the panel for a SINGLE municipality (Cidades@). The routing paragraph names the exact siblings it must not be confused with (ibge_censo, ibge_comparar, ibge_indicadores), so an agent can distinguish it without opening a 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?

Provides explicit when-to-use conditions via the feature list (overview, specific indicator, historical, list surveys) and explicit when-NOT-to-use conditions naming the correct alternatives for census themes, multi-municipality comparison, and macro time series. Nothing is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new context: it is a live GET against the public IBGE CNAE API and returns Markdown. It does not discuss rate limits or error behavior, but it exceeds the annotation bar.

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

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

Front-loaded with what CNAE is, then hierarchy, features, examples and behavior in a scannable structure. The per-level counts (21/87/285/673/1332) and some examples duplicate what the schema already conveys, costing a little efficiency.

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 an output schema present, rich annotations, and fully documented parameters, the description only needs to frame purpose and usage — which it does. Nothing essential for correct invocation is missing, though it could note the default nivel behavior more explicitly.

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 busca, nivel, codigo and limite thoroughly, including the code-format examples that the description also repeats. The description adds no semantics 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 verb and resource — querying the CNAE economic-activity classification from IBGE — and the hierarchy detail makes the scope unambiguous. It is clearly distinguishable from the other ibge_* siblings (cidades, sidra, municipios), none of which handle CNAE codes.

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 'Features' list plus four worked examples (busca, codigo for code/section, nivel for listing) tell an agent concretely how to invoke the tool for each intent. It stops short of naming when NOT to use it or routing to a sibling alternative, so it is clear but not fully 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 already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered; the description still adds value by disclosing the underlying data sources (live GET against public IBGE SIDRA and Localidades APIs) and the return shape (Markdown plus typed structuredContent). It does not mention rate limits or error behavior, so it stops 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?

Front-loaded with purpose, then indicators, features, examples, and the exclusion rule — a sensible hierarchy. Mildly redundant since the indicator bullet list duplicates the schema enum text, but the examples and routing rule earn their space.

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

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

An output schema exists and the description still notes the dual Markdown + structuredContent return, plus indicator coverage, locality-count bounds, accepted code formats, and sibling routing. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and both enums are fully documented in the schema, so the schema does the heavy lifting. The description largely restates the indicator list and the 7-digit/2-digit code convention already present in the schema, adding little new semantic detail.

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

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

States a specific verb+resource ('Compares data between localities') and enumerates exactly what can be compared (population, GDP, area, density, literacy, households). The 'Use this tool ONLY to rank/compare 2–10 localities on one indicator' line separates it cleanly from ibge_cidades, ibge_censo and ibge_sidra.

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?

Explicit when-to-use (2–10 localities on one indicator), when-not (single locality → use ibge_cidades, ibge_censo, or ibge_sidra), plus concrete invocation examples and a way to list indicators via indicador='listar'.

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/openWorld, but the description adds real context beyond them: it is a live GET against the public API, returns Markdown plus a typed structuredContent payload, estatisticas ignores campos/formato and leaves registros empty, and agruparPor resolves short names and refuses ambiguous labels (reporting via `aviso`).

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?

Long but tightly organized into purpose, indicator groups, territorial legend, examples, statistics mode, and exclusions. Front-loaded with the core purpose; only the examples and indicator list add bulk, which is justified for a 9-parameter tool.

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 9-parameter tool with full schema coverage and an output schema, all an agent needs is present: indicator vocabulary, territorial codes, statistics-mode semantics, sibling routing, and behavior profile. No meaningful gap remains.

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 baseline is 3, but the description genuinely adds meaning: the territoral-level mapping (1=Brazil … 6=Municipality) is restated for usability, examples show real localidade/nivel_territorial combinations, and the interaction between estatisticas, agruparPor, topN and campos is explained beyond the per-parameter text.

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 (queries) and resource (Brazil health indicators via IBGE SIDRA/DataSUS) and enumerates the exact indicator domains. The 'Use a different tool when' section names siblings (ibge_cidades, ibge_censo, ibge_sidra), making it distinguishable without opening any schema.

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

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

Explicit routing guidance: which tool to use for a single municipality's panel, for population counts, and precisely when to flip estatisticas=true (highest/lowest/mean/median/distribution/ranking). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description still adds value by naming the backing endpoint (live GET against the public IBGE Localidades API) and the return format (Markdown table). It does not discuss rate limits or failure modes, which is a minor 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?

Front-loaded with the core statement and organized under Features/Examples/Use-a-different-tool/Behavior headers, each carrying distinct information. The examples slightly duplicate the enum values, and the header structure is heavier than strictly needed for a 2-param read tool.

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 trivial read-only list tool with an output schema, the description covers what it does, how to filter/sort it, when to pick a sibling, and the return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with enums, so the baseline is 3, but the description adds example values (regiao="NE", ordenar="sigla") that show real usage beyond the enum listing. It does not explain the default sort behavior, which the schema already handles.

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 (lists all Brazilian states from IBGE) and explicitly names the siblings it is not for (ibge_municipios, ibge_localidade). An agent can distinguish it from the other ibge_* tools without opening any schema.

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

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

Provides concrete invocation examples (no params, regiao="NE", ordenar="sigla") and an explicit 'Use a different tool when' section routing two sibling cases. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond annotations: it is a live GET against the public IBGE Localidades API and returns Markdown. It does not discuss error behavior or rate limits, but those gaps are minor for a public read-only decoder.

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

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

The description is front-loaded with the core purpose and organized under clear headings. It is longer than strictly necessary because it repeats code-format details already present in the schema, but the structure and examples make the extra length useful rather than noisy.

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

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

Given the 3 optional parameters, 100% schema coverage, full annotation coverage, and the presence of an output schema, the description supplies everything needed for correct invocation. Alternatives are named, examples are provided, and the return behavior is stated, so no material context is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description still adds value by repeating the digit-to-level code structure and giving concrete examples such as codigo="3550308" and combined nome="Campinas", uf="SP", which clarify usage beyond the raw 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 purpose: decoding IBGE codes or searching codes by locality name. It enumerates supported levels (region, state, municipality, district) and explicitly distinguishes itself from ibge_municipios and ibge_localidade, so an agent can select it without inspecting sibling schemas.

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 explicit examples for both main modes and a dedicated 'Use a different tool when' section naming alternatives and the conditions that select them. This routes the agent away from tools that only list municipalities or return one full locality record.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: a live GET against the public IBGE SIDRA API and a Markdown + structuredContent return shape. It stops short of documenting rate limits or truncation/pagination behavior outside statistics mode.

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

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

Front-loaded with the core purpose and organized under bold headers (Economic, Prices, Labor, Population, Examples, Statistics mode), which makes it scannable despite its length. The indicator catalog is long but each line is a distinct key, so the length is earned rather than padded.

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 10-parameter, annotation-rich tool with an output schema, everything an agent needs is present: the valid indicator catalog, category filter usage, working examples, the statistics-mode contract, and explicit sibling routing. Nothing material is left for the agent to infer.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real value on top: worked examples for indicador, periodos and nivel_territorial, the cross-parameter rule that estatisticas=true ignores campos/formato and leaves registros empty, and the agruparPor ranking semantics with ambiguity refusal. It does not explain topN or localidades beyond the schema text.

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 ('Queries IBGE economic and social indicators') and then enumerates the exact indicator keys across four categories. It explicitly names the sibling tools it is not (ibge_comparar, ibge_censo, ibge_cidades), so an agent can route correctly without opening any schema.

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

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

Contains a dedicated 'Use a different tool when' block with three named alternatives and the condition that selects each, plus four concrete invocation examples. It also states when to flip estatisticas=true (largest/smallest/mean/median/distribution/ranking) and what that mode disables.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds context beyond structured fields: it is a 'live GET against the public IBGE Localidades API' and returns a 'Markdown record,' which tells the agent about the data source and output format. It does not cover rate limits or auth, but for a public read-only API that is minor.

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

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

Front-loaded with the core purpose and organized into clear sections (Features, Examples, Alternatives, Behavior). It is slightly longer than necessary because the 'Features' list restates code-length information already present in the schema, but the structure and routing guidance justify most of the length.

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

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

For a two-parameter lookup tool with 100% schema coverage, full annotations, and an output schema, the description covers purpose, routing, behavior, and examples. The output schema handles return details, and annotations handle safety, so nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by providing concrete code examples (São Paulo state: codigo=35; city: codigo=3550308; district: codigo=355030805) that illustrate the digit-length conventions in practice, adding practical value beyond the schema's format description.

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?

First sentence states a specific verb and resource: 'Returns details of a specific locality by IBGE code.' It further clarifies scope ('the full record of ONE locality you already have the code for') and explicitly names sibling alternatives (ibge_municipios, ibge_geocodigo), so an agent can distinguish it from the ~20 other ibge_* 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?

Explicitly states when to use a different tool: when you have a name and need the code, or when you want to decompose a code's structure, each mapped to a specific sibling (ibge_municipios, ibge_geocodigo). This is a textbook when/when-not/alternatives section with no ambiguity.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the caller-relevant fact that this is a live GET against the public IBGE Malhas API and that the response matches the requested format. It omits pagination/size limits and failure behavior, so it stops 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?

Front-loaded with the core purpose, then organized into labeled sections that are easy to scan. Slightly redundant: resolution is explained once in the generic features and again in the 'Resolution' section, and the format list appears twice.

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 6 parameters (4 enum-constrained), an output schema, and full annotation coverage, the description supplies everything an agent needs: purpose, routing, locality/resolution/format conventions, and examples. No material gap remains.

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 baseline is 3, but the description earns extra by mapping locality types ('BR'/'1', state abbreviation, state code, 7-digit municipality code) and resolution levels to concrete examples. It restates much of the schema, and intrarregiao is left entirely to the schema, keeping it out of 5 territory.

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 ('Gets geographic meshes (maps) from IBGE') plus output formats, and explicitly distinguishes itself from the sibling ibge_malhas_tema for thematic meshes. An agent can route between the two without opening either schema.

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

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

Provides explicit 'Use a different tool when' routing to ibge_malhas_tema, plus three concrete invocation examples covering locality/resolution/format combinations. Both when-to-use and when-not-to-use are present.

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

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

Annotations already declare read-only/idempotent/open-world safety, so the bar is lower, yet the description still adds real context: geometry is deliberately excluded (one biome polygon >9 MB), the call is a live GET against the public IBGE Geosserviços WFS, that service differs from the Malhas API, and the return is Markdown plus typed structuredContent.

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

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

Front-loads the core purpose, then uses parallel bulleted sections for enum meanings, filtering, exclusions, and behavior. It is on the longer side, but nearly every line (geometry exclusion, service identity, routing) 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?

Even though an output schema exists, the description explains the geometry-omission decision and the download-URL workaround, which is the one thing an agent must understand to use the result correctly. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description adds meaning beyond the schema: codigo is only accepted by biomas, costeiro, and fronteira, and biome codes come from the source rather than a fixed table. It does not add syntax detail for limite 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?

States a specific verb (Lists) and resource (thematic territorial recorte of Brazil) with explicit scope: feature counts, codes, names, and a geometry download URL. It also names the sibling ibge_malhas as the tool for a different job, so an agent can distinguish it without opening any schema.

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

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

Provides explicit routing via 'Use a different tool when: Administrative meshes WITH geometry → ibge_malhas', plus conditional guidance on when codigo is accepted versus when to call without it. Covers both when-to-use and the alternative.

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, openWorldHint, and destructiveHint=false, so "read-only and idempotent" is partly restating structured data. It does add genuine context beyond the annotations: the tool issues a live GET against the public IBGE Localidades API and returns a Markdown table, which tells the agent about latency exposure and output shape. No permission or rate-limit detail is given, but that is minor for a public read API.

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

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

Front-loaded with the one-line purpose, then layered features, examples, and exclusions in scannable blocks. Structure is excellent, though the "Features" bullets and "Examples" partially restate the same facts (state filtering appears in both), which is a small amount of redundancy rather than filler.

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

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

An output schema exists and annotations carry the safety profile, so the description is not obligated to explain return values. It still covers scope, all three parameters' intent, sibling routing, data source, and output format — nothing an agent needs to select or invoke this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above that by showing that uf and busca compose (uf="MG", busca="Belo") and by confirming that omitting uf returns the full national list, which the schema states but the examples reinforce. It says nothing about the limite/slicing parameter, leaving that entirely to the schema.

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

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

States a specific verb and resource ("Lists Brazilian municipalities from IBGE") and immediately enumerates the concrete capabilities: filter by state, list all 5,570, search by name. The description also differentiates itself from ibge_geocodigo, ibge_localidade, and ibge_vizinhos, so an agent can place it against siblings without opening any schema.

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

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

Provides three worked invocation examples mapping intent to parameters (uf="SP", busca="Campinas", uf="MG"+busca="Belo"), plus an explicit "Use a different tool when" block that names three alternatives and the exact condition that selects each. When-to-use, when-not-to-use, and alternatives are all covered.

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/openWorld/destructive=false, but the description adds real value: the live GET against the public IBGE Nomes (Censo) API, the Markdown table return shape, and the 1930-2010 decade constraint that the schema does not encode.

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?

Well front-loaded with the core purpose, then organized into features, examples, and behavior. Example lines are slightly verbose but each demonstrates a distinct valid call combination, so little 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?

An output schema exists, so return values need not be re-explained, and the description covers both modes, parameter pairing rules, and the decade limit. Minor gaps remain around locality code behavior and result limits, but nothing an agent needs to invoke correctly is absent.

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 goes slightly beyond by showing combined parameter usage (comma-separated nomes, tipo+decada, tipo+sexo) and the available decade range, which the schema's decada description does not state.

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 ('Queries name frequency and rankings in Brazil (IBGE)') and enumerates the two distinct query modes, making it immediately distinguishable from siblings like ibge_censo or ibge_sidra.

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

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

Gives clear when-to-use context per mode, including which parameters belong to each tipo, backed by four concrete examples. It stops short of naming alternatives or stating when a sibling tool would be preferred over this one.

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, openWorld, non-destructive. The description still adds real context beyond them: newest-first ordering, the no-parameter default of 10 items, that it is a live GET against the public IBGE Notícias API, and that output is a Markdown list with a header reporting total count and page. That is meaningful behavioral disclosure, though no rate-limit or error behavior is mentioned.

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

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

Front-loaded with the core purpose, then cleanly segmented into parameters, return shape, examples, and alternatives. Despite its length, each block is scannable and every sentence carries distinct information, so 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?

Even though an output schema exists (so return values need not be restated), the description still summarizes the item shape and header fields, and it covers the read-only/live-API nature. For a 7-parameter, zero-required list tool this leaves no decision-relevant 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%, so the baseline is 3. The description genuinely adds meaning on top: it defines 'tipo' semantics ('release' = official survey results vs 'noticia' = general news), gives example search terms, restates the date format, and clarifies the quantidade/pagina pagination relationship, which the schema alone does not connect.

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 ('searches and lists'), resource ('already-published IBGE news articles and press releases'), and an explicit negative scope ('already-published'/'not yet published'). It distinguishes itself from the sibling ibge_calendario by naming it, so an agent can route without opening any schema.

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

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

Gives concrete when-to-use triggers (finding recent publications, when an indicator was released, news mentioning a term), worked examples, and an explicit 'Use a different tool when' clause pointing to ibge_calendario for scheduled releases. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds value by stating the mechanism is a live GET against the public IBGE Países API and that output is Markdown, which the annotations do not say.

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

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

Front-loaded purpose followed by scannable features, region list, code convention, and examples — well structured and easy to skim. The region enumeration and code-format note duplicate the schema slightly, costing a little density.

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 an output schema present, return-value detail is not required, yet the description still flags Markdown output and the read-only live-API nature. All five parameters, the enum modes, and the region vocabulary are accounted for, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each field. The description goes further by tying parameters to intent through concrete examples and by surfacing the region vocabulary and ISO-ALPHA-2 code convention in prose, reducing lookup friction.

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 — 'Queries international country data via IBGE' — and enumerates the concrete modes (list, details, search, filter by region) that separate it from siblings like ibge_estados or ibge_localidade. An agent can tell what this tool covers 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?

The feature list plus worked examples (tipo="listar" with regiao="americas", tipo="detalhes" with pais="BR") give clear, actionable context for choosing each query mode. It stops short of explicit when-not-to-use guidance or naming alternative sibling tools for overlapping tasks (e.g., localidade or municipios).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, yet the description still adds value: it discloses that this is a live GET against the public IBGE SIDRA/Pesquisas API and that output is a Markdown list. It does repeat the read-only/idempotent traits already in annotations, which keeps 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?

Front-loads the core purpose, then layers features, examples and routing in a scannable structure. The 'Main surveys' taxonomy block is longer than strictly necessary for tool selection, but it is genuinely useful context for a survey-catalog tool.

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

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

An output schema exists so return values need no explanation; the description still covers purpose, inputs, examples, sibling routing, and the underlying API behavior. For a zero-required-parameter read-only listing tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description rises above it by supplying worked examples that map each parameter to realistic values ('busca="população"', 'detalhes="pnad"') and clarifying the no-parameter case lists everything. It does not, however, state matching behavior (partial vs exact) for busca.

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 ('Lists available IBGE surveys and their tables') and immediately scopes it against siblings: 'This lists surveys, not data.' An agent can distinguish it from ibge_sidra_tabelas and ibge_sidra without opening any schema.

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

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

Explicitly routes the agent: use ibge_sidra_tabelas to find table codes, ibge_sidra or a wrapper to query data. It also gives concrete when-to-use examples ('Search population: busca="população"'). Nothing is left to inference.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description adds substantial context beyond that: it discloses the live GET against the public IBGE SIDRA API, return format ('Markdown plus a typed structuredContent payload'), data-quality marker exclusion ('-', '..', '...', 'X'), source-imposed query ceilings (Aggregates API limits), and mode-specific behavior (estatisticas ignores pagina/campos/formato; registros empty). This is rich behavioral disclosure.

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?

Despite its length, the description is well-structured with clear sections (common tables, territorial levels, examples, statistics mode, routing, behavior) and front-loads the core purpose. Every part serves to guide correct invocation, so it earns its place without wasted words.

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

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

Given 12 parameters, a complex statistics mode, and 20+ sibling tools, the description is complete: it routes to alternatives, explains limitations and special behaviors, and notes output format. With an output schema present, return values need not be detailed further, and the description fills all remaining gaps.

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 value by listing eight common table codes with descriptions (e.g., 6579, 9514) and giving usage examples (tabela="6579", periodos="2023"), which help select parameter values. However, it does not deeply explain parameter semantics beyond what the schema already provides, so a 4 is warranted.

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: 'Queries SIDRA tables (IBGE's Automatic Recovery System).' It explicitly positions itself as the low-level engine and names sibling wrappers (ibge_censo, ibge_indicadores, etc.), so an agent can distinguish it from alternatives without opening schemas.

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

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

Provides explicit when-to-use routing: 'Prefer a friendlier wrapper when it fits: Census themes → ibge_censo; ... Rank/compare 2–10 localities → ibge_comparar.' Also directs to ibge_sidra_tabelas and ibge_sidra_metadados for table discovery, and explains when to use the statistics mode (estatisticas=true). No guidance is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the live GET against the public IBGE SIDRA API and that the return format is Markdown. It does not mention rate limits or error behavior, but that is a minor omission given annotations handle the rest.

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

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

Front-loaded with the core action and organized under clear Features/Examples headings with scannable bullets. Slightly redundant: the 'BEFORE querying' guidance appears twice (in the intro line and the later 'Use this after...' sentence), which is minor waste but not confusing.

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

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

For a read-only metadata lookup with a full output schema, the description supplies everything an agent needs: what is returned, when to call it relative to the two sibling tools, and concrete example codes. Return-value detail is correctly delegated to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by mapping concrete table codes to content semantics (6579=population, 9514=Census 2022, 4714=PNAD unemployment) and by tying the feature list (available periods, territorial levels) to the optional booleans incluir_periodos and incluir_localidades.

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 metadata for a specific SIDRA table') and enumerates exactly what that metadata includes (name, survey, periodicity, territorial levels, variables, classifications, periods). This distinguishes it cleanly from ibge_sidra (data queries) and ibge_sidra_tabelas (table code discovery).

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 states when to use it ('BEFORE querying data with ibge_sidra') and names both bracketing siblings: use after ibge_sidra_tabelas and before ibge_sidra. This is a complete when/when-not/alternative routing instruction.

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, openWorldHint and destructiveHint=false, so the safety profile is covered; the description nonetheless adds real context by stating this is a live GET against the public IBGE SIDRA API and that the response is a Markdown table. It also discloses non-obvious behavior beyond the annotations: everyday Portuguese is silently mapped to IBGE terminology, and the response flags that mapping in notas_vocabulario. It does not discuss rate limits or error behavior, so not 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?

Front-loaded with the core purpose, then structured into Features, Surveys, Examples and Workflow sections — easy to scan. The bulleted list of SIDRA surveys (Census, PNAD, GDP, Industrial, Agricultural) is largely filler that the 'pesquisa' parameter already implies, costing some tightness.

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

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

An output schema exists so return values need not be explained, yet the description still notes the Markdown table format. With zero required parameters, 100% schema coverage, and explicit workflow placement and wrapper alternatives, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents busca, limite and pesquisa including the vocabulary mapping. The description goes modestly beyond by giving worked parameter examples (busca="população", pesquisa="censo"), but does not clarify limite's default/max or AND semantics beyond what the schema 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 opens with a specific verb+resource ('Lists and searches available SIDRA tables') and immediately distinguishes itself from siblings by naming itself as step 1 of the SIDRA workflow, with ibge_sidra_metadados and ibge_sidra as the downstream steps. An agent can tell this apart from the wrapper tools (ibge_censo, ibge_indicadores) without opening any schema.

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

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

It gives explicit routing: use this first to find a table code, then ibge_sidra_metadados for structure, then ibge_sidra for the query — and adds a when-not branch ('For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades'). Concrete invocation examples (no parameters, busca="população", pesquisa="censo") remove remaining ambiguity.

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, openWorld and non-destructive, but the description still adds genuinely new behavioral context: the proxying via shared mesoregion, the live GET against the public IBGE Localidades API, and that the return is a Markdown list. The only shortfall is that the repeating of the mesoregion caveat crowds out other traits, such as how results are ordered or limited.

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

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

The core sentence is well front-loaded and the examples are useful, but the mesoregion caveat is stated three separate times (in Features, in the first Note, and in the second Note), which is redundant padding on a short definition.

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

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

With a full annotation set and an output schema covering the return format, the description only needs to explain scope and behavior, which it does well; the unexplained 'raio' parameter is the one loose end.

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 baseline applies and the description's examples (municipio, uf, incluir_dados) largely duplicate documented fields. Notably it never mentions the 'raio' (radius in km via centroids) parameter, which is arguably in tension with its claim that proximity is only approximated by mesoregion — leaving the agent to reconcile the two from the schema alone.

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 ('Finds nearby/neighboring municipalities') and immediately distinguishes itself from ibge_municipios by naming that sibling for listing/searching. An agent can separate this from the other ibge_* tools without opening a schema.

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

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

Gives concrete when-to-use context plus examples for code lookup, name+uf lookup, and population inclusion, and explicitly routes list/search queries to ibge_municipios. It also warns that exact spatial adjacency is out of scope, which is a real exclusion criterion.

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, openWorld and non-destructive, so the safety profile is covered. The description adds context beyond them: the catalog comes from the public source and is cached in memory, and an empty list means nothing matched. It does not discuss result latency or ranking nuances, but the added caching/source disclosure is substantive.

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

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

Front-loaded with the core purpose and return shape, then structured into contract, alternatives, query notes, and behavior. Every sentence earns its place, though the Deep Research contract paragraph is somewhat verbose relative to the tool's simplicity.

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

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

An output schema exists, so return values need not be explained in depth; the description still summarizes them. For a single-parameter read-only search with annotations covering safety, an agent has everything needed: what it searches, what it returns, when to use it, and which tool to chain into.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents it fully. The description restates the same facts (natural language or keywords, Portuguese or English, accents/case ignored) rather than adding new syntax or constraints. Baseline 3 applies when the schema does the heavy lifting.

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 ('searches the IBGE catalog'), names the exact return shape ({ id, title, url }, up to 10, ordered by relevance) and explicitly frames itself as a catalog index rather than a data query. An agent can distinguish it from every ibge_* sibling without opening a schema.

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

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

Gives explicit when-to-use ('OpenAI Deep Research contract... require exactly the tools search and fetch'), an explicit alternative for other cases ('for direct questions and for data prefer the ibge_* tools'), and the follow-up step ('pass one of the returned ids to fetch'). Nothing is left to inference.

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