IBGE Brasil MCP

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds a concrete behavioral detail: 'a live GET against the public source when the document needs it' and notes error handling for unknown ids. This supplements, not contradicts, the 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?

The description is structured into three focused paragraphs: purpose, context/usage, and behavior. While slightly verbose with the 'OpenAI Deep Research contract' phrase, each sentence contributes useful information and the main purpose is front-loaded.

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

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

With an output schema available and a single parameter, the description covers all necessary context: the source catalog (IBGE), the prerequisite of `search`, the error case, and the tool's role relative to siblings. 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?

The sole parameter `id` is fully described in the schema (100% coverage) as a document identifier from `search`. The description reinforces this dependency and error condition, but adds little new semantic value beyond the schema's explanation. 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 clearly states the action: 'Returns the full document for an id obtained from `search`' — a specific verb, resource, and dependency. It distinguishes itself from the ibge_* siblings by explicitly noting they are 'the tools for data queries', preventing confusion.

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 provides explicit usage guidance: ids must come from `search`, unknown ids produce an error, and the ibge_* tools are the alternative for data queries. This leaves no ambiguity about when to invoke this tool versus others.

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 largely redundant. The description still adds genuine context beyond annotations: it is a live GET against the public IBGE Calendário API and returns a Markdown list.

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, then tightly grouped Features / Event types / Examples / Routing / Behavior sections. The 'read-only and idempotent' clause duplicates the annotations and could be trimmed, but overall structure is clean and scannable.

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 6-param read-only query tool with a 100%-documented schema, full annotations and an output schema, the description supplies everything else an agent needs: purpose, event semantics, examples, sibling routing, and API/return context. Nothing material 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% (baseline 3), but the description adds meaning the schema does not: it interprets the 'tipo' enum values as Release vs Collection events and shows realistic values for produto (IPCA, PNAD, GDP) and de/ate formatting. The example block converts abstract params into concrete usage.

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 release and collection calendar') and immediately names the sibling it must not be confused with (ibge_noticias). An agent can distinguish this calendar-query tool from the news tool 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_noticias for already-published content, plus four concrete invocation examples (no params, produto, date range, tipo). 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?

Beyond the readOnly/idempotent annotations, it discloses the live GET against the public SIDRA API, the Markdown + structuredContent return shape, and rich mode behavior: statistics computed over ALL rows before truncation, campos/formato ignored and registros emptied in that mode, and ambiguity refusal in agruparPor with an aviso field.

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 sections (years, themes, examples, mode, exclusions), so it is easy to navigate. It loses a point for restating content already in the schema, such as the full theme list and year enumeration.

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 nine parameters with an output schema and full annotation coverage, the description supplies exactly what structured fields cannot: mode-switching rules, examples, and sibling routing. An agent has everything needed to select and invoke 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter interaction semantics (estatisticas=true overrides pagina/campos/formato, agruparPor ranking by descending sum with resolved short labels) and realistic parameter combinations in the examples that the per-property schema text alone does not tie together.

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'), names its scope (simplified access without SIDRA table codes), and explicitly routes to three siblings (ibge_cidades, ibge_comparar, ibge_sidra) with the condition that selects each.

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?

Carries a full 'Use a different tool when' block naming alternatives and their conditions, plus four concrete invocation examples and a dedicated explanation of when to enable estatisticas mode. Nothing about tool selection 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, and destructiveHint=false, so the safety profile is covered — the description's restatement adds little there. It does add genuinely new context: a live GET against public IBGE APIs and a return format ('Markdown plus a typed structuredContent payload'). No rate-limit or auth caveats are mentioned, but for a public read-only API this 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 purpose, then features, indicator list, examples, and routing — a logical, skimmable structure. It is somewhat long and the features list partially overlaps the examples, but each block carries usable information and no sentence is purely filler.

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

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

For a 5-parameter read-only tool with full schema coverage and an output schema, the description supplies everything an agent needs: what it does, the indicator vocabulary, the routing alternatives, and the return shape. Nothing required 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 of 3 applies, but the description adds real value by enumerating the available indicators (populacao, area, pib_per_capita, idh, etc.) and showing parameter combinations per tipo. It goes beyond the schema's enum glosses without fully specifying each parameter's syntax.

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 municipal indicators from IBGE') and explicitly scopes the tool to a SINGLE municipality (Cidades@ panel). It names the exact sibling tools it is not (ibge_censo, ibge_comparar, ibge_indicadores), so an agent can disambiguate 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 rules: 'Use a different tool when: Census themes → ibge_censo; Comparing multiple municipalities → ibge_comparar; macro indicator time series → ibge_indicadores.' It also gives worked examples mapping each 'tipo' value to a concrete scenario, leaving nothing to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real context by specifying it is 'a live GET against the public IBGE CNAE API' and 'Returns Markdown,' which goes beyond the annotations and informs the agent about the external source and output medium.

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 and uses clear headers for hierarchy, features, examples, and behavior, making it scannable. It is slightly verbose with the level-by-level counts (21/87/285/673/1,332) that are informative but not strictly necessary for invocation.

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 annotations covering the safety profile, an output schema present, and 100% schema description coverage, the description need not explain return values. It rounds out the picture with hierarchy structure, feature list, worked examples, and source/format behavior, leaving nothing essential for a correct call unstated.

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

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

Schema description coverage is 100% and the codigo field already documents format and examples in the schema, so the schema carries the semantic load. The description's examples for busca, codigo, and nivel add marginal reinforcement, but it never addresses the limite parameter; baseline 3 is appropriate.

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

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

States a specific verb (Queries) and resource (CNAE - National Classification of Economic Activities from IBGE), and clarifies the domain as Brazilian economic-activity classification. This cleanly distinguishes it from domain-adjacent siblings like ibge_cidades, ibge_estados, and ibge_pesquisas.

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' and 'Examples' sections give concrete invocation scenarios (search by term, by code, list by level, show hierarchy), which effectively communicates when to use the tool. It lacks explicit when-not guidance or named alternatives among the many IBGE siblings, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety profile is structured. The description adds value beyond that: it discloses the underlying data sources (SIDRA and Localidades public APIs) and the return format (Markdown plus typed structuredContent). It doesn't discuss rate limits or error behavior, keeping it short of 5, but adds genuine context beyond 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?

Front-loaded with a clear purpose statement, then structured lists of indicators, features, and examples. Reasonably sized for a tool with this many options. Minor redundancy between the indicator list and schema enum, and examples repeat some information, but overall well-organized and skimmable.

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, the description need not explain return values, and it appropriately mentions structuredContent. It covers constraints (max 10), accepted inputs, indicator vocabulary, and routing guidance. Missing minor items like the behavioral meaning of 'ranking' vs 'json' formats but overall complete for calling correctly.

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

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

Schema description coverage is 100% and the schema already enumerates indicators with descriptions and formats. The description repeats the indicator list and code format (7 digits for municipalities, 2 for states), which duplicates schema content rather than adding new meaning. Baseline 3 is appropriate.

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

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

States a specific verb (compares) and resource (data between localities), enumerates available indicators, and explicitly differentiates from siblings: 'Use this tool ONLY to rank/compare 2–10 localities on one indicator. For a single locality, use ibge_cidades, ibge_censo, or ibge_sidra.' An agent can route correctly without inspecting other 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?

Explicit when-to-use ('ONLY to rank/compare 2–10 localities on one indicator'), when-not-to-use (single locality), and named alternatives (ibge_cidades, ibge_censo, ibge_sidra). Also gives a hard constraint (up to 10 localities) and concrete examples. Nothing 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real mode-dependent behavior: estatisticas=true bypasses pagination, ignores campos/formato, leaves registros empty, and computes over ALL rows before truncation; agruparPor ranks groups by descending sum and reports the resolved column in `aviso`, refusing ambiguous labels. It also discloses the transport (live GET against public SIDRA) and the return shape (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?

Long but well-segmented with headers, bulleted indicator groups, territorial-level legend, and example lines; the purpose and mode caveats are front-loaded. It loses a point because the indicator enumeration and statistics-mode rules substantially restate the input-schema descriptions.

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 an output schema present, the description says enough: which indicators exist, what the statistics mode does to the response, how territorial levels map, and when to pick a sibling instead. No material gap remains for correct invocation.

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 9 parameters (and largely duplicates the indicator list). The description still adds value by giving worked examples that bind values to parameters (nivel_territorial="3" for state, localidade="35" for SP) and by explaining the agruparPor ranking semantics beyond the schema wording.

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 ('Queries Brazil health indicators, served through IBGE's SIDRA'), enumerates the exact indicators and domains, and explicitly names the sibling tools it should not be confused with (ibge_cidades, ibge_censo, ibge_sidra). 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?

Explicit when-to-use for statistics mode ('largest/smallest/mean/median/distribution/ranking questions') with concrete trigger phrases, plus a dedicated 'Use a different tool when' block that gives the alternative and the condition selecting it. 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 adds genuinely new context — it is a live GET against the public IBGE Localidades API returning a Markdown table — though the return format is partly redundant given an output schema exists.

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 one-line purpose, then uses labeled Features/Examples/routing sections that are scannable and waste-free. Every sentence either defines scope, demonstrates a call, or routes to a sibling.

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 annotations covering safety, a full input schema with enums, and an output schema covering return values, the description needs only purpose, examples and routing — all of which are present. 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 coverage is 100% and both params are enum-constrained with self-documenting values, so the baseline is 3. The description goes beyond the schema by showing the actual wire values in context (regiao="NE", ordenar="sigla"), which reduces the chance of an agent guessing at an invalid code.

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

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

Opens with a specific verb+resource ('Lists all Brazilian states from IBGE') and immediately scopes it with the exact count (27) and the two filter/sort axes. The 'Use a different tool when' section names the sibling tools it is not, so an agent can separate it from ibge_municipios and ibge_localidade 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?

Explicitly names the alternatives (ibge_municipios for municipalities, ibge_localidade for single-locality details) and the condition that selects each, plus concrete invocation examples for no-param, region-filtered, and sorted calls. 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 readOnly, idempotent, openWorld and non-destructive. The description adds genuinely new context beyond them: it is a live GET against the public IBGE Localidades API and returns Markdown. It does not discuss 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 the core purpose, then cleanly sectioned into features, code structure, examples and alternatives, which suits the tool's branching input modes. The code-structure bullets partially duplicate the parameter schema, costing some 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, return values need not be explained. Between the level-decoding rules, the four examples, the named alternatives and the read-only/API/Markdown behavior note, an agent has everything needed 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 coverage is already 100%, so the baseline is 3, but the description adds meaning the schema lacks — the digit-length-to-level mapping (1/2/7/9 digits) and worked examples such as nome="Campinas", uf="SP" that show how nome and uf combine. It stops short of documenting mutual exclusivity between codigo and nome.

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

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

The opening sentence states a specific dual verb (decodes / searches) against a specific resource (IBGE geographic codes), and the 'Use a different tool when' block explicitly names ibge_municipios and ibge_localidade, so an agent can distinguish it from siblings without reading 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?

Explicit routing is provided: it says when to use this tool (decode a code at any level, resolve name→code) and when not to, naming two concrete alternatives plus the condition that selects each. 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 goes beyond by disclosing the transport ('a live GET against the public IBGE SIDRA API'), the return shape (Markdown plus typed structuredContent), and non-obvious mode behavior: statistics runs over ALL rows before truncation and causes campos/formato to be ignored while 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 purpose, then logically sectioned indicator catalog, examples, statistics-mode rules, and routing guidance. The 15-item indicator list is long but each entry earns its place as the de facto enum for a free-form string parameter; overall structure is clean, slightly dense.

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 tool with an output schema present, the description carries the needed usage logic, mode semantics, and indicator catalog without redundantly explaining return values. An agent has everything required to select and invoke 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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: it enumerates the valid indicador values (pib, ipca, desemprego, populacao...) and the special 'listar' value, and explains how estatisticas interacts with agruparPor and topN. It does not, however, clarify categorias/localidades beyond what is implied.

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 ('Queries IBGE economic and social indicators') and enumerates the actual indicator families (economic, prices, labor, population), so an agent knows exactly what data it returns. It explicitly names the siblings it is NOT (ibge_comparar, ibge_censo, ibge_cidades), giving clear differentiation.

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

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

Provides a dedicated 'Use a different tool when' block routing four sibling scenarios to their alternatives, plus concrete call examples and a rule for when to enable statistics mode ('which state has the highest unemployment?'). The when-to-use boundaries are explicit rather than inferred.

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, destructiveHint=false, and openWorldHint, so the description does not need to restate safety. It adds genuine value beyond them by naming the backing source ('live GET against the public IBGE Localidades API') and the return format ('Markdown record'). It does not mention any rate limits or auth requirements, which are minor for a public 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-loads the purpose, then organizes the remainder into labeled Features, Examples, When-to-use, and Behavior blocks. Every section is short and actionable; the concrete code examples partially duplicate the schema's digit-length note, but they remain useful for disambiguation.

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 enumerated; the description still notes the Markdown format. Combined with the hierarchy explanation, the code examples, and the sibling routing rules, an agent has everything needed to call this correctly for a three-level locality lookup.

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

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

Schema coverage is 100% and the schema already documents both 'codigo' digit lengths and the 'tipo' enum with inference from code length, so the baseline is 3. The description's concrete examples (São Paulo state=35, city=3550308, district=355030805) add grounded meaning by mapping real entities onto the abstract code lengths, marginally exceeding 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 ('Returns details of a specific locality by IBGE code') and immediately clarifies scope with the exact code lengths for state, municipality, and district levels. It explicitly distinguishes itself from siblings by name ('Use a different tool when... ibge_municipios or ibge_geocodigo'), 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?

Provides an explicit selection condition ('returns the full record of ONE locality you already have the code for') and pairs it with two named alternatives for the opposite cases (having a name, wanting to decompose a code). This is textbook when-to-use / when-not-to-use guidance with named siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered; the description's 'read-only and idempotent' sentence largely repeats them. What it does add is the nature of the call — a live GET against the public IBGE Malhas API — which tells the agent data is fetched remotely rather than cached locally.

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: purpose first, then features, locality types, resolution, examples, and sibling routing, all in scannable bullets. It loses a point because the resolution and format enumerations restate schema fields that already carry the same information.

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

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

With an output schema present, the description need not explain return shapes, and annotations carry the safety profile. Given 6 parameters, one required, the description supplies locality coding, resolution levels, format choices, precedence-free guidance, and sibling routing — nothing needed 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%, so the baseline is 3 and the schema already documents resolucao, qualidade, formato and intrarregiao. The description goes further by giving worked mappings ('BR' or '1' = Brazil, 'SP'/'35' = São Paulo, 7-digit municipality code) and example parameter combinations, which reduce ambiguity when constructing a call.

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

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

States a specific verb and resource ('Gets geographic meshes (maps) from IBGE') and enumerates the scope it covers (Brazil, regions, states, municipalities; GeoJSON/TopoJSON/SVG). It also names the sibling it is not — ibge_malhas_tema for thematic meshes — so an agent can separate 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?

Contains an explicit 'Use a different tool when' block that routes thematic meshes (biomes, Legal Amazon, semi-arid, metropolitan regions) to ibge_malhas_tema, plus three concrete invocation examples. The condition that selects the alternative and the condition that selects this tool are both stated.

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, non-destructive. The description adds substantial value beyond them: the design decision that geometry is deliberately excluded (with a concrete size at ~9 MB per biome polygon) and that a canonical WFS URL is returned instead, plus the detail that this hits the IBGE Geosserviços WFS rather than the Malhas API. It stops short of discussing rate limits or error behavior, so it is 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?

The description is front-loaded with the core capability, then uses scannable sub-sections for recortes, filtering, and alternatives. It is on the longer side, but every section earns its place; the geometry rationale could be tightened slightly but is justified by the size figure.

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 and annotations carry the safety profile, the description completes the picture: it explains what the response contains, what is intentionally omitted (geometry), how to obtain geometry (WFS URL), which recortes accept codigo, and which sibling to use for administrative meshes. Nothing material 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?

Schema description coverage is 100%, so the schema already documents tema, codigo, limite and their enums/defaults/maxima. The description reinforces codigo semantics and explains the biome-code provenance ('biome codes come from the source, not from a fixed table'), but this is largely redundant with the schema – 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 opens with a specific verb and resource: 'Lists what a THEMATIC territorial recorte of Brazil contains: how many features, with which codes and names, and the URL to download its geometry.' It also names the sibling it is not ('Administrative meshes WITH geometry → ibge_malhas'), so an agent can distinguish it from the similarly named ibge_malhas immediately.

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 'Use a different tool when' block explicitly routes administrative mesh requests to ibge_malhas, and the description explains the codigo filtering acceptance per recorte as well as when to call without codigo ('Ask without codigo to see what exists'). This is explicit when-to-use and when-not-to-use 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, openWorldHint, and destructiveHint=false. The description restates 'read-only and idempotent' and adds the live GET source and Markdown table output, which is useful context but largely redundant with annotations. Output schema exists, so no need to explain returns.

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, then features, examples, and exclusions in labeled sections. Every line earns its place with no filler.

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

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

Complete for a read-only filtered-list tool: purpose, modes, examples, boundaries, behavior, and output shape all covered. An agent has everything needed to select and invoke 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 baseline is 3. The description adds value beyond the schema: concreteness of the 7-digit code result, the 5,570 total, and worked examples showing uf setup with busca combined. Marginal lift above 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+resource ('Lists Brazilian municipalities from IBGE') and specifies the scope precisely (5,570 municipalities, 7-digit codes). It distinguishes itself from siblings ibge_geocodigo, ibge_localidade, and ibge_vizinhos with explicit routing.

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 'Use a different tool when' section names three alternatives (geocodigo, localidade, vizinhos) and the exact conditions selecting each. Examples show the three main invocation modes. 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 redundant 'read-only and idempotent' line earns nothing. However, the description adds genuinely new context: 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 state.

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

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

Front-loaded one-line summary followed by numbered features, examples, and a behavior note — well organized and scannable. Minor waste from the read-only/idempotent sentence duplicating annotations and some repeated param hints, but nothing egregious.

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 detailed beyond the Markdown-table note. Both query modes, their required inputs, and the decade range are covered, making the definition sufficient for correct invocation; only minor edge cases (e.g., locality code validation) are left implicit.

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 100% schema description coverage, the schema already documents each parameter and even tags them by tipo ('Para tipo=frequencia', 'Para tipo=ranking'), including comma-separated names and the limit default. The description largely restates those bindings and the decade example list, adding only the 1930–2010 range, so the baseline 3 is correct.

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. The resource is unique among the ibge_* siblings, so an agent can immediately tell this tool apart from geography/indicator/calendar 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?

The feature breakdown plus four worked examples make the when-to-use for each mode (tipo='frequencia' vs tipo='ranking') unambiguous. It does not name or exclude any sibling alternative, and gives no explicit when-not-to-use, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real behavior: newest-first sorting, default 10 with no params, max 100, pagination via pagina, and a live GET returning Markdown. It slightly restates 'read-only and idempotent' already in annotations, but the added operational detail 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 purpose, then parameters, examples, and routing in clearly delimited sections. Slightly long with some redundancy (return-field list overlaps the output schema), but every section is scannable and 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?

Complete for a zero-required-param search tool: coverage of all 7 params, default/pagination behavior, enum meaning, invocation examples, and sibling routing. The output schema exists, yet the description still conveniently summarizes returned fields without it being necessary.

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 extends meaning: it clarifies that tipo='release' is an official survey publication vs 'noticia' general news and that omitting returns both, and adds the DD/MM/AAAA format with examples 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?

Specific verb+resource: 'Searches and lists already-published IBGE news articles and press releases.' It also distinguishes itself from the sibling ibge_calendario by scoping to already-published content, so an agent can tell them 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 states when to use it ('find recent IBGE publications or announcements... when an indicator was released') and names the alternative with the disambiguating condition: scheduled/upcoming releases route to ibge_calendario. Includes concrete invocation examples.

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, so the description's 'read-only and idempotent' is largely redundant; however it adds genuinely new context — a live GET against the public IBGE Países API and Markdown output format. That is useful beyond the structured fields, though it omits any auth/rate-limit notes.

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

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

Front-loaded with a one-line purpose, then feature bullets, region/code conventions, examples, and behavior — highly scannable. Slightly verbose, and the 'Available indicators: tipo="indicadores"' example is a bit misleading since indicator IDs go in a separate parameter.

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 values need not be explained, and the description still covers all five parameters, valid enum values, code formats, and invocation examples. The only small gap is the ambiguity between the indicators enumeration and the indicadores parameter.

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 parameter docs are already complete; the description still adds value by listing the valid region values, prescribing ISO-ALPHA-2 codes with examples (BR, US, AR, PT, JP), and demonstrating how parameters combine per operation. It only marginally clarifies how the 'indicadores' parameter relates to tipo='indicadores'.

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 operations: list, details, search, filter by region. The word 'international' implicitly separates it from the Brazilian-scoped siblings (ibge_estados, ibge_cidades, ibge_municipios, ibge_localidade), so an agent can route correctly.

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 Examples block gives a use pattern for each mode (listar, detalhes, buscar, listar+regiao, indicadores), which effectively says when to combine which parameters. It does not name a sibling alternative or an explicit 'do not use this for X' exclusion, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the description's restatement of 'read-only and idempotent' earns no credit. It does add that this is a live GET against the public IBGE SIDRA/Pesquisas API, which clarifies the network dependency, but says nothing about rate limits, failures, or empty-result behavior.

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

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

Front-loaded with the core purpose and the sibling routing sentence, then structured into Features/Main surveys/Examples/Behavior. The 'Main surveys' catalog is domain-flavored filler that lengthens the definition without changing how the tool is called, keeping this short of a 5.

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

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

An output schema exists, so return-value detail is unnecessary. Between purpose, explicit sibling alternatives, parameter examples, and the domain framing of survey families, an agent has everything needed to select and invoke 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. The description goes beyond that by showing the intended shape of each argument in context (busca="população" for name search, detalhes="pnad" for a survey's tables), which clarifies that detalhes takes a survey code rather than an arbitrary string.

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 disambiguates from siblings with 'This lists surveys, not data.' The agent knows exactly what this tool returns versus ibge_sidra and ibge_sidra_tabelas.

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 to alternatives: ibge_sidra_tabelas for table codes, ibge_sidra or the named wrappers for data. The Examples block maps each parameter mode (none, busca, detalhes) to a concrete intent, so 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, and destructiveHint=false, but the description adds substantial behavioral context beyond those: it specifies it is a 'live GET against the public IBGE SIDRA API', mentions the return format ('Markdown plus a typed structuredContent payload'), explains that statistics mode ignores pagina/campos/formato, and discloses that SIDRA absence markers are excluded and that very large queries are refused due to the Aggregates API ceiling. This is rich behavioral disclosure with no contradictions.

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 long but well-structured: it front-loads the core purpose, then uses labeled sections for common tables, territorial levels, examples, statistics mode, and sibling guidance. Every sentence earns its place—even the long statistics section is necessary for a complex feature. It is slightly verbose (e.g., repeating the Aggregates API ceiling note) but remains organized and scannable, so a 4 is appropriate rather than a 5.

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

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

For a tool with 12 parameters, 1 required, and an output schema present, this description is nearly exhaustive. It covers common usage patterns, edge cases (statistics mode ignoring some params, large query limits), how to discover table codes and metadata, and how to disambiguate from sibling tools. The output schema handles return-value details, 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 coverage is 100%, so the baseline is 3, but the description goes far beyond: it provides a curated list of common table codes with meanings, explains territorial level codes, gives concrete examples for each parameter, details the statistics mode and agruparPor resolution behavior (including refusal for ambiguous labels), and explains that topN caps at 100. This adds practical semantics that the schema alone does not convey.

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 clear verb+resource statement: 'Queries SIDRA tables (IBGE's Automatic Recovery System).' It further distinguishes itself from siblings by explicitly naming ibge_censo, ibge_indicadores, ibge_comparar, and ibge_cidades as friendlier wrappers for specific use cases, and references ibge_sidra_tabelas and ibge_sidra_metadados as lookup tools. This leaves no ambiguity about what the tool does and how it differs from the others.

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 guidance on when to use this low-level engine vs. alternative tools ('Prefer a friendlier wrapper when it fits: Census themes → ibge_censo, Economic/social time series → ibge_indicadores, Rank/compare 2–10 localities → ibge_comparar, One municipality's panel → ibge_cidades'). It also explains the statistics mode for ranking/distribution questions and warns about the Aggregates API ceiling, telling the user to narrow periods or raise territorial level. This is explicit when/when-not guidance with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false, but the description goes further by explaining the mechanism: 'a live GET against the public IBGE SIDRA API' and specifying the return format is Markdown. This adds context beyond the structured hints about how and where the call executes.

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 purpose, followed by a scannable bullet list of returned fields, usage guidance, and concrete examples. The examples with real table codes are useful, though the list of features is somewhat verbose since the output schema likely covers some of it.

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, the description doesn't need to explain return values in detail, yet it still provides helpful categories and example table codes. Combined with explicit routing to sibling tools and API behavior, an agent has everything needed to invoke and interpret 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 coverage is 100%, so the schema already documents all three parameters including defaults. The description lists metadata categories that map to the optional flags (periods, territorial levels) but does not add syntax or format details beyond the schema's own descriptions. Baseline 3 is appropriate 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 the specific verb and resource ('Returns metadata for a specific SIDRA table') and enumerates the metadata fields returned. It clearly distinguishes itself from the sibling data-query tool ibge_sidra and the table-search tool ibge_sidra_tabelas.

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: 'Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.' Both prerequisite and follow-up tools are named, and the 'BEFORE querying data' condition is unambiguous.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it performs a live GET against the public IBGE SIDRA API, returns a Markdown table, and explains vocabulary normalization (renda→rendimento, etc.) with a notas_vocabulario note. It could add rate-limit or pagination details, but it goes beyond the 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?

The description is well-structured with clear sections (Features, Surveys, Examples, Workflow) and front-loads the core purpose. It is somewhat long, but every section earns its place by providing routing and behavioral context. A few redundant lines (e.g., listing surveys twice) could be trimmed, but it remains efficient.

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 list/search tool with zero required parameters, an output schema, and full schema coverage, the description is complete. It explains the workflow position, the return format, the vocabulary normalization behavior, and the alternatives. 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 schema already documents all three parameters. The description adds examples and explains the AND/accents/case behavior for busca, but it mostly restates what the schema says. Baseline 3 is appropriate because 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?

The description states a specific verb ('Lists and searches available SIDRA tables') and clearly distinguishes this tool from siblings by naming the SIDRA workflow and wrappers. It also enumerates features and examples, so an agent can tell it apart from ibge_sidra_metadados and ibge_sidra 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?

The description explicitly says this is step 1 of the SIDRA workflow, names the follow-up tools (ibge_sidra_metadados, ibge_sidra), and advises that wrappers (ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades) are usually easier for common data. This gives clear when-to-use and when-not-to-use 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 cover readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is free. The description adds real value beyond that: it discloses the mesoregion-based proximity approximation, the exact-adjacency limitation, and that it returns a Markdown list.

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 purpose well, but the mesoregion-proximity caveat is repeated three separate times ('same mesoregion (proximity approximation)', 'Uses mesoregion as geographic proximity proxy', 'proximity is approximated by shared mesoregion'), which is redundant padding in an otherwise structured block.

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

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

For a read-only lookup tool with a rich schema and an output schema, the definition is nearly complete: it explains inputs, the approximation model, and the return format. The only meaningful gap is the unaddressed 'raio' parameter, whose centroid-radius semantics sit awkwardly beside the mesoregion-proxy claim.

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 four parameters; baseline is 3. The description adds code format (7 digits) and name/uf pairing, but never mentions the 'raio' (radius in km) parameter, which is the one parameter whose semantics most conflict with the mesoregion-proximity framing.

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 explicitly distinguishes itself from the sibling ibge_municipios ('For listing/searching municipalities, use ibge_municipios'). An agent can identify the tool's role 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?

Provides concrete usage examples (by code, by name+uf, with population) and routes a different task to ibge_municipios. It lacks an explicit statement of when NOT to use it beyond the approximation caveat, but the context is clear.

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. The description adds valuable behavior beyond these: returns at most 10 results, empty list means no match, relevance ordering, language handling, caching, and the linkage to fetch. This contextual information helps the agent anticipate outcomes and error cases.

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 longer than average but every paragraph earns its place: core purpose, tool contract context, alternative routing, query semantics, and behavior. The primary search behavior is front-loaded in the first sentence. Slight redundancy exists between the schema and the Query line, but overall it is well organized and scannable.

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?

The description is complete for a search/catalog tool of this complexity. It covers what is searched, output shape and limits, relevance ordering, empty results semantics, query language details, read-only/idempotent behavior, and how to follow up with fetch. An output schema exists, so return values need no further explanation, and all necessary agent guidance is present.

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

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

Schema coverage is 100% and the schema already describes the query parameter as natural language/keywords with accents and case ignored. The description adds the meaningful extra detail that the query may be in Portuguese or English, which goes beyond the schema. This justifies a score above the baseline of 3.

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

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

The description states a specific verb and resource: 'Searches the IBGE catalog' and explicitly defines the output as 'up to 10 matching documents as { id, title, url }, ordered by relevance'. It also distinguishes itself from siblings by labeling itself a 'catalog index, not a data query', which disambiguates it from the data-returning 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?

The description gives explicit routing guidance: 'For direct questions and for data (values, series, rankings) prefer the ibge_* tools...' and 'Pass one of the returned ids to fetch to read the document.' It clearly states when to use this tool versus alternatives and names the relevant sibling tools.

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