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 behavioral context beyond them: the 'live GET against the public source when the document needs it' (a network fetch with possible lazy retrieval) and the error-on-unknown-id behavior. It does restate 'read-only and idempotent', which duplicates annotations, keeping it just under 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 and return shape, then companion context, then behavior — a sensible ordering with little waste. Slightly dense and includes minor redundancy with the annotations ('read-only and idempotent').

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

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

For a single-parameter fetch with full annotations and an output schema, the description covers purpose, provenance constraint, error behavior, and sibling routing. Nothing needed 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% and the single `id` param is documented, so the baseline is 3. The description still adds value by clarifying provenance ('id obtained from `search`') and the failure mode for invalid ids, which the schema does not express.

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 ('Returns the full document') and resource (a document by id from `search`), and names the return shape { id, title, text, url, metadata }. It explicitly positions itself against `search` and the `ibge_*` siblings, 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?

Gives explicit preconditions ('only ids returned by `search` are valid; an unknown id returns an error') and routes the agent away from the `ibge_*` tools for data queries. Both when-to-use and when-not-to-use are 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 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered. The description still adds real context beyond them: it is a live GET against the public IBGE SIDRA API, it returns Markdown plus a typed structuredContent payload, and statistics mode has side effects (campos/formato ignored, registros left empty) that an agent must anticipate.

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 organized under labeled sections (years, themes, examples, statistics mode, alternatives, behavior). It is long and repeats the year list already present in the enum, but the structure keeps it scannable and each section carries distinct routing or mode information.

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

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

For a 9-parameter tool with an output schema and full annotation coverage, the definition supplies the routing, mode semantics, and example calls an agent needs. The only shortfall is that the in-description theme list is a subset of the schema enum, so an agent skimming only the description could under-estimate available themes.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further with concrete call examples that show parameter interaction (ano="todos" for a historical series, nivel_territorial="3" for literacy by state, tema="listar" to enumerate tables) and explains that agruparPor ranks groups by descending sum. The description's theme list covers only 9 of the 18 enum values, leaving the rest 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 ('Queries IBGE Demographic Census data 1970-2022') plus the scoping constraint that it works without knowing SIDRA table codes, which is exactly the distinction from ibge_sidra. An agent can tell it apart from siblings without opening the schema.

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

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

Contains an explicit 'Use a different tool when' block that routes to four alternatives (ibge_cidades, ibge_indicadores, ibge_comparar, ibge_sidra) with the condition selecting each. It also names the exact question shape ('which municipality had the largest 2022 population?') that triggers estatisticas=true.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds real context beyond that: it names the upstream API (public IBGE Pesquisas/Cidades@ plus Localidades lookup), warns that panorama may fan out into several indicator calls and report partial upstream gaps, and states the dual Markdown + structuredContent return. Useful, though it stops short of detailing rate limits or failure modes.

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 clearly sectioned into features, indicator values, examples, sibling routing, and behavior. Slightly long, but every block carries routing or parameter information and nothing is repeated 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, so return format need not be explained in depth, and the description still notes Markdown plus typed structuredContent. With full schema coverage, explicit disambiguation from all relevant siblings, and documented behavior, 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 goes further: it enumerates valid indicator identifiers (populacao, area, idh, etc.) and the example block shows how tipo/municipio/indicador combine for each query mode, which the schema's short field descriptions do 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?

States a specific verb (queries) and resource (municipal indicators from IBGE/Cidades@) and immediately scopes it to a SINGLE municipality. It explicitly names the four sibling tools it is not (ibge_censo, ibge_comparar, ibge_indicadores), 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?

Provides concrete call examples per tipo value and an explicit 'use a different tool when' block mapping each alternative scenario to the correct sibling. When-to-use and when-not-to-use are both spelled out.

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

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

Annotations already declare 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 readOnly, idempotent, openWorld and non-destructive. The description adds behavioral context beyond them by disclosing it performs a live GET against the public IBGE APIs (SIDRA and Localidades) and returns Markdown plus a typed structuredContent payload. It does not cover error/rate-limit behavior, but with safety fully annotated this is solid added value.

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

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

Purpose is front-loaded, then useful sections (indicators, features, examples, exclusions, behavior) in a scannable structure. It runs long and duplicates the schema's indicator definitions, but each sentence is on-topic and aids selection.

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, 100% schema coverage, an output schema handling return values, and explicit sibling routing, the definition supplies everything an agent needs to select and invoke it correctly. 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 the baseline is 3, but the description adds a real constraint absent from the schema ('Compare up to 10 localities at once') and concrete code-format examples (7-digit municipalities, 2-digit states) that clarify how to populate 'localidades'. The indicator list largely duplicates the schema enum.

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 (municipalities or states)') and immediately names the scope of the operation. It differentiates itself from siblings by explicitly stating it compares a fixed set of localities rather than producing time series or single-locality panels.

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 'Use a different tool when:' block naming three alternatives (ibge_indicadores, ibge_censo, ibge_sidra) with the conditions that select each, plus a 'use ONLY to rank/compare 2–10 localities' constraint and single-locality fallbacks (ibge_cidades, ibge_censo, ibge_sidra). 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, open-world and non-destructive, so the safety profile is covered; the description still adds that it is a live GET against the public SIDRA API and returns Markdown plus structuredContent. The statistics-mode side effects (campos/formato ignored, registros empty, ranking computed over ALL rows before truncation) are genuine behavioral disclosure. It stops short of auth/rate-limit 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?

Well front-loaded and sectioned, but it duplicates content already present at full fidelity in the schema: the nine-indicator list with Portuguese glosses, and the territorial-level legend (1=Brazil ... 6=Municipality). Roughly a third of the text is restatement rather than added value; the material that does earn its place is the sibling routing and the examples.

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 open-world query tool with an output schema, annotations and 100% schema coverage, the description supplies everything else an agent needs: indicator taxonomy, mode semantics, territorial levels, sibling disambiguation and concrete examples. Return-format explanation is a bonus since the output schema already covers it.

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 operational meaning the schema lacks: examples tie localidade to a territorial level ('Deaths in SP: indicador="obitos", nivel_territorial="3", localidade="35"') and explain the statistics/ranking mode's intent. It does not, however, add format details for periodo or campos 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 concrete verb and resource ('Queries Brazil health indicators, served through IBGE's SIDRA') and enumerates the indicator families it covers. It explicitly separates itself from ibge_indicadores ('general economic/social series such as GDP, prices, labor and population estimates'), so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use ('Use this tool for health, mortality, fertility, sanitation and health-coverage indicators') and a dedicated 'Use a different tool when' block naming ibge_cidades, ibge_censo and ibge_sidra with the exact condition that selects each. Worked examples further pin down invocation for three distinct query shapes.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description still adds value: it discloses the live GET against the public SIDRA API, the Markdown + structuredContent return shape, and the surprising mode side effect that campos/formato are ignored and registros comes back empty when estatisticas=true.

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-structured with category headings, bullets and examples, and the core purpose is front-loaded. Every section (indicator list, examples, statistics mode, sibling routing, behavior) earns its place for a 10-parameter tool, though it is denser than strictly necessary.

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

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

Covers indicator vocabulary, examples, the non-obvious statistics mode, and sibling routing, and an output schema exists so return values need not be detailed. Nothing an agent needs to invoke 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%, so baseline is 3. The description goes further by explaining statistics-mode interactions (ignores pagina/campos/formato), agruparPor group-ranking and label-resolution behavior, and by supplying concrete example values for indicador, periodos and nivel_territorial.

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 ('IBGE economic and social indicators'), then enumerates the exact indicators available grouped by category. It explicitly differentiates from siblings (ibge_sidra, ibge_comparar, ibge_censo, ibge_cidades) so an agent can route without opening 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?

Contains an explicit 'Use a different tool when:' block naming each alternative and its selecting condition, plus worked examples mapping parameters to questions. The statistics-mode guidance states exactly when to set estatisticas=true.

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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses provenance (versioned official IBGE/GeoFTP snapshots audited by the laboratory), the return format (Markdown plus typed structuredContent), and a hard contract boundary ('THEMATIC GEOMETRY IS NOT PART OF THIS TOOL'S CONTRACT'). These are behavioral facts the annotations cannot convey.

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 recortes, filtering, contract boundary, and routing. Slightly redundant in stating the geometry exclusion twice (once as a contract note, once under 'Use a different tool when'), which costs it the top score.

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 listing tool with an output schema, full parameter coverage, and rich annotations, the description supplies everything an agent needs: scope, enumeration, filter semantics, sibling routing, and return format. 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% and the schema already spells out the enum values, the cd_bioma vs. 7-digit municipality code rule, and the limite default/max with 'total always returned'. The description's parameter guidance largely restates the schema rather than adding syntax or edge-case meaning, 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 ('Lists what a THEMATIC territorial recorte of Brazil contains'), enumerates all eight recortes, and explicitly distinguishes itself from the sibling ibge_malhas. An agent can identify the tool's scope and output shape 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?

Explicit routing is given: 'Use a different tool when: Administrative meshes WITH geometry → ibge_malhas', plus the inverse rule that thematic geometry is out of contract. It also tells the agent how to get a plain listing ('Ask without codigo to list records') and that 'listar' bypasses the source entirely.

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 readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered. The description adds value beyond that by naming the backing source (public IBGE Países API) and the return shape (Markdown plus typed structuredContent with provenance).

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 cleanly sectioned into Features, regions, codes, examples, and behavior. It is somewhat long and repeats region values already present in the schema, but no sentence is wasted and the structure is easy to scan.

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

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

With an output schema present, the description needn't detail returns, and it still sketches the response format. Combined with annotations covering safety and a fully-documented 5-parameter schema, 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, but the description goes further by pairing parameters in worked examples (e.g., tipo="detalhes" with pais="BR", tipo="listar" with regiao="americas"), clarifying valid combinations. The region and ISO-ALPHA-2 details largely restate 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 international country data via IBGE") and enumerates the four query modes. The 'países/countries' resource is clearly distinct from the state, municipality, and locality siblings, so an agent can route without ambiguity.

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 shows concrete invocation patterns for every mode (listar, detalhes, buscar, region filter, indicadores), giving clear context for how to use the tool. It stops short of stating when-not-to-use or naming a sibling alternative, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, 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 the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantive traits: the exact upstream sources (IBGE Localidades, Malhas v3, SIDRA for population), the topological-vs-approximate nature of each mode, and the return format (Markdown list). This is real context an agent cannot get from annotations alone.

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

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

Well front-loaded: purpose first, then features, examples, and behavior. Sections earn their place, though the raio/centroid explanation is repeated in both Features and Behavior, which is mild redundancy rather than waste.

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?

Output schema exists, so return-value documentation is not required, but the description still notes the Markdown-list format. Combined with mode semantics, data provenance, and examples, an agent has everything needed to call this 4-parameter 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 it by tying raio's presence to a mode switch and by showing concrete invocation shapes for municipio, uf, and incluir_dados. It does not add format details (e.g. acceptable sigla/nome variants) beyond what the schema already states.

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

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

States a specific verb and resource ('Finds nearby/neighboring municipalities') and immediately names the sibling it is not ('For listing/searching municipalities, use ibge_municipios'). An agent can distinguish it from the other 20+ 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?

Explicitly contrasts the two operating modes (contiguous neighbors vs. radius by centroid distance) and states the selection condition, plus routes listing/searching to ibge_municipios. Worked examples for code, name+uf, and population enrichment 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 cover read-only, idempotent and non-destructive, so the description only needs to add context — and it does: results are cached in memory from the public source, an empty list signals no match, and the index is explicitly not a data source. It does not discuss ranking mechanics or catalog staleness, but the annotation burden is already met.

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 the tool does and returns, then guidelines, then query semantics, then behavior — a sensible ordering with no true filler. However, the accent/case sentence duplicates the schema and the Deep Research contract paragraph is longer than the routing information it carries.

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 expansion, and the description still summarizes cardinality and ordering. For a single-parameter search tool sitting inside a 22-tool catalog, everything an agent needs to select it, query it, and route its output is present.

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

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

Schema description coverage is 100% and the single `query` param is already documented in the schema, including the accent/case insensitivity the description repeats. The description's only marginal addition is that Portuguese or English both work, which is a small gain over the structured field — 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 — searches the IBGE catalog — and pins the exact return shape ({ id, title, url }, up to 10, relevance-ordered). It explicitly distinguishes itself from siblings by naming the ibge_* data tools and fetch as the downstream consumer of returned ids.

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 / Responses API contract requiring exactly `search` and `fetch`), when-not-to-use (direct questions and data/values/rankings should go to ibge_sidra, ibge_cidades, ibge_indicadores, ibge_comparar), and the follow-up action (pass a returned id to `fetch`).

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