IBGE Brasil MCP

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive. The description reinforces this and adds beyond it: the error behavior on unknown ids, the Markdown nature of `text`, the canonical `url` for citation, and the note that it performs a live GET against the public source when needed. Slightly more on caching/freshness would earn 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 return shape, then contract context, then routing to siblings, then behavior. Every paragraph carries information, though the 'OpenAI Deep Research contract' framing is slightly more verbose 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?

For a one-parameter read tool, the description covers the return shape, error semantics, source semantics, and sibling routing. An output schema exists so return values need not be fully explained, yet the key fields are still highlighted — nothing an agent needs is missing.

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

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

Schema coverage is 100% and the single `id` parameter is documented in-schema as coming from `search`. The description still adds constraint semantics the schema lacks — that an unknown id produces an error — which is genuine added value over the baseline 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 opening sentence states a specific verb and resource — 'Returns the full document for an id obtained from `search`' — and immediately describes the return shape { id, title, text, url, metadata }. It also explicitly differentiates itself from the ibge_* siblings, stating those remain the tools for data queries.

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 guidance: only ids from `search` are valid, unknown ids error, and the ibge_* family is named as the alternative for actual data queries. Both the when-to-use and when-not-to-use conditions are stated, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the description's closing line largely restates them. It adds that it is a live GET against the public IBGE Calendário API and returns a Markdown list, but with an output schema present the return-format note is partly redundant. Modest added value beyond the structured fields.

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

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

Front-loaded with the core purpose and organized under clear headers (Features, Event types, Examples, Use a different tool when). Slightly long — the example lines partially overlap the schema descriptions — but every section is functional.

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 query tool: all six parameters are documented in schema, the enum semantics are explained in prose, and an output schema exists so return values need not be described. The routing to ibge_noticias closes the main ambiguity.

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 mapping 'Release'/'Collection' to the tipo enum values and showing worked examples (produto="IPCA", de/ate date strings, tipo="coleta"). This gives an agent usable calling patterns beyond the raw field descriptions.

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 distinguishes the two event types it returns (Release vs Collection). The routing line to ibge_noticias makes it separable from the nearest sibling 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 concrete when-to-use scenarios (upcoming releases, IPCA filter, 2024 calendar, field collections) and an explicit exclusion ('Already-published news and releases → ibge_noticias'). Nothing is left to inference about when to pick this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, and the description restates the read-only/idempotent nature plus return format (Markdown + structuredContent). It goes beyond the annotations by disclosing a non-obvious mode interaction: in statistics mode, campos/formato are ignored and registros comes back empty. Useful added context, though the safety profile is largely a restatement of 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 purpose and scope, then organized into themes, examples, alternatives, and mode behavior with clear headers. It runs long, but every section (years list, theme list, statistics mode, sibling routing) carries information an agent needs, so nothing feels like padding.

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

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

With a typed output schema present, the description needn't explain return values and doesn't try to. It fully covers scope, enumerations, mode behavior, and tool routing, so 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 description coverage is 100%, so the schema already documents all nine parameters and the baseline is 3. The description adds meaning the schema lacks by showing concrete parameter combinations in examples and explaining cross-parameter behavior (estatisticas overrides campos/formato and empties registros; agruparPor ranks groups and resolves short/partial labels).

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) with a clear scope (1970-2022) and explicitly positions itself as the simplified alternative to raw SIDRA table lookups. It names the siblings it is not (ibge_cidades, ibge_comparar, ibge_sidra) so an agent can distinguish it 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?

Has a dedicated 'Use a different tool when:' block that names three alternatives and the exact condition that selects each. It also provides worked examples covering single-year, historical-series, and spatial-level queries, leaving little 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 genuine context beyond them: it discloses that this is a live GET against public IBGE APIs and returns Markdown plus a typed structuredContent payload. Rate limits or error behavior are not mentioned, keeping it just short of a 5.

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

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

Front-loaded with purpose, then features, examples, exclusions, and behavior in clearly delimited sections. Bullets and labeled groups make it scannable; every line (indicator list, examples, exclusions) 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?

An output schema exists, so return values needn't be detailed, yet the description still notes the response shape. With annotations covering safety, 100% schema coverage, and explicit routing to alternatives, an agent has everything needed to select and call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by enumerating valid indicator names (populacao, area, pib_per_capita, ...) and pairing parameter values in worked examples, adding meaning the schema's terse 'ID do indicador ou nome para busca' 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?

States a specific verb+resource ('Queries municipal indicators from IBGE') and immediately scopes it as the panel for a SINGLE municipality (Cidades@). The feature bullets and the explicit sibling exclusions make it unmistakably distinct from ibge_censo, ibge_comparar, and ibge_indicadores.

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

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

Contains an explicit 'Use a different tool when:' block naming three alternatives and the condition that selects each. The examples show concrete parameter combinations per 'tipo', so an agent knows not just when but how to invoke it.

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 repetition. The line adds two genuinely new facts — it is a live GET against the public IBGE API (no auth/rate-limit detail) and responses come back as Markdown — which is modest value beyond the structured hints.

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?

Sectioned into purpose, hierarchy, features and examples with a front-loaded opening sentence, so an agent can skim to the relevant part. The reference counts for every hierarchy level are informational but slightly verbose, and the closing 'Behavior' line partly duplicates the annotations.

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 does not need to spell out return values, and it instead supplies the domain scaffolding (hierarchy levels, code formats) an agent needs to interpret the results correctly. Annotations cover the safety profile, so 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 description coverage is 100%, and the schema itself carries richer semantics than the description (accent/case-insensitivity, multi-word AND matching, everyday-term translation). The description's examples for busca/codigo/nivel mostly restate what the schema already documents, so baseline 3 applies.

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

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

States a specific verb and resource ('Queries CNAE... from IBGE') and immediately frames it as Brazil's official economic-activity classification, which separates it from the other ibge_* data tools. The hierarchical breakdown and feature list make the scope unambiguous.

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

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

The 'Features' bullets plus four concrete examples ('busca="software"', 'codigo="6201-5/01"', list by level) tell the agent exactly which parameter pattern to reach for in common situations. It never names a sibling tool or says when NOT to use this (e.g. vs ibge_pesquisas or ibge_sidra), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new context beyond that: it is a live GET against the public IBGE APIs (SIDRA and Localidades) and returns Markdown plus a typed structuredContent payload. It does not, however, mention rate limits, error behavior, or latency for these external calls.

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 indicators, features, examples, and routing constraints in scannable blocks. It is somewhat longer than needed because the indicator list duplicates the enum descriptions already in the schema, which is wasted space.

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

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

An output schema exists, so return values need not be explained, and the description still summarizes the Markdown + structuredContent shape. With indicators, constraints (2–10 localities, code formats), examples, and sibling routing all present, an agent has everything required to call it correctly.

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

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

Schema description coverage is 100% (both enums and the localities format are fully documented), so the baseline is 3. The description largely repeats the schema's indicator list; notably its 'pib: GDP per capita' label conflicts with the schema's 'PIB a preços correntes (Mil Reais)', a minor semantic mismatch rather than added clarity.

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: 'Compares data between localities (municipalities or states)'. It immediately names sibling alternatives (ibge_cidades, ibge_censo, ibge_sidra) and its unique scope ('rank/compare 2–10 localities on one indicator'), 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?

Explicit when-to-use ('Use this tool ONLY to rank/compare 2–10 localities'), when-not ('For a single locality'), and which siblings to use instead. Concrete examples for capitals, states, ranking, and listing further anchor the invocation pattern.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint/openWorldHint, and the description's 'read-only and idempotent — a live GET' line largely restates them, which would normally cap credit. However it goes beyond the annotations by disclosing the statistics-mode gotchas (campos/formato are ignored, registros comes empty) and the agruparPor ranking/tie-refusal behavior, which an agent could not infer from structured fields 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?

Long but well front-loaded: verb first, then grouped indicator lists, then territorial codes, then examples, then statistics mode, then sibling routing. A minor deduction because the indicator enumeration is duplicated verbatim in the schema's indicador description, so that block does not strictly earn its place here.

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 covers everything an agent needs: indicator vocabulary, territorial level codes, worked examples, the statistics-mode override contract, and explicit fallbacks to sibling tools. Return values are covered by the output schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns above it by showing parameter combinations in worked examples (indicador + nivel_territorial + localidade='35' for São Paulo deaths) and by explaining the interaction contract where estatisticas=true overrides pagina/campos/formato. It adds compositional meaning rather than restating field docs.

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 ('Queries Brazil health indicators, served through IBGE's SIDRA') and immediately scopes the domain by listing the actual indicator identifiers, so an agent knows exactly what data this returns. It also explicitly names the siblings it is not (ibge_cidades, ibge_censo, ibge_sidra), which makes disambiguation possible without opening any schema.

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

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

Contains a dedicated 'Use a different tool when' section naming drei concrete alternatives with the condition that selects each, plus explicit routing guidance for statistics questions ('which state has the highest infant mortality?') to estatisticas=true. This is about as complete as usage guidance gets.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior, and the description repeats read-only/idempotent while adding that it is a live GET against the public IBGE Localidades API and returns a Markdown table. That return-format and source-API context is useful beyond the annotations, though it does not cover rate limits, auth, or error 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?

The definition is front-loaded with a one-line purpose, then organized into features, examples, alternatives, and behavior. It is appropriately sized, though there is minor redundancy between the opening sentence and the first feature bullet ('Lists all 27 states').

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

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

Given the rich structured context — safety annotations, fully described enum parameters, and an output schema — the description covers purpose, usage examples, sibling alternatives, and behavior. Nothing essential for selecting or invoking this tool is missing.

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

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

The schema has 100% description coverage and enumerates both parameters with meanings and allowed values. The description's feature list and examples (regiao="NE", ordenar="sigla") are helpful but largely restate what the schema already documents, so this meets the baseline rather than adding substantially new semantic detail.

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

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

The description states a specific verb and resource: 'Lists all Brazilian states from IBGE.' It also distinguishes itself from sibling tools by naming ibge_municipios and ibge_localidade as alternatives for different scopes, so an agent can route correctly without opening schemas.

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

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

It gives explicit usage examples, including no-parameter listing, regional filtering, and sorting. It also provides clear when-not-to-use guidance by naming the tools for municipalities and single-locality details, leaving no ambiguity about when this tool is appropriate.

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 goes beyond them by disclosing the execution model ('a live GET against the public IBGE Localidades API') and the response format ('Returns Markdown'), which annotations cannot express.

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, code structure, examples, alternatives, and behavior. The 'Code structure' block largely repeats the schema's codigo description, so a small amount of redundancy exists, but the structure is scannable and every section is labeled.

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 explain return values, and it covers purpose, routing alternatives, input examples, code semantics, and runtime behavior. Nothing an agent needs in order 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 the baseline is 3 and the schema already documents all three params. The description adds value through worked examples, notably the combined call nome="Campinas", uf="SP", which demonstrates how the optional params interact in a way the schema does not state explicitly.

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 pair ('Decodes IBGE codes or searches codes by locality name') and enumerates the levels it operates on (region, state, municipality, district). It explicitly names the siblings it is not (ibge_municipios, ibge_localidade), so an agent can route correctly 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' section that names both alternatives and the exact condition that selects each ('only need to list/search municipalities' → ibge_municipios; 'full detailed record of one locality' → ibge_localidade). This is the strongest form of routing guidance.

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

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

Goes well beyond the annotations: discloses that it is a live GET against the public SIDRA API, that IBGE revises published figures and no earlier version is kept, that PNAD rolling quarters are moving three-month windows, and that statistics mode ignores campos/formato and returns empty registros. Annotations only cover the read-only/idempotent safety profile, so this adds substantial operational context.

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 a bolded category index, then examples, then caveats and sibling routing — a logical order. It is long, and the statistics-mode guidance overlaps with the estatisticas and agruparPor schema descriptions, but nearly every sentence carries operational value that the structured fields do not.

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, everything an agent needs is covered: the indicator catalogue, default/required-free calling, statistics mode semantics, period and territory levels, revision caveats, and explicit routing to alternatives. No return-format explanation is needed given the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the estatisticas/agruparPor interaction (ranking by descending sum, group mini-distributions, short-label resolution) and how periodos and nivel_territorial are used in practice. It stops short of describing every parameter (e.g. localidades codes, topN interaction) but reads as a net gain over 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 economic and social indicators") and then enumerates the exact indicator codes by category, so an agent knows precisely what it can retrieve. It also differentiates from siblings by naming ibge_sidra for other variables of the same table and routing comparison/census/municipality tasks to ibge_comparar, ibge_censo and ibge_cidades.

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

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

Gives concrete usage examples (indicador="pib", periodos="last 12", nivel_territorial="3"), an explicit trigger for estatisticas=true ("largest/smallest/mean/median/distribution/ranking questions"), and a dedicated "Use a different tool when" section with three named alternatives and the condition selecting each.

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 'read-only and idempotent' line earns no credit. It does add the live GET against the public IBGE Localidades API and a Markdown return record, but since an output schema exists the return-format note is marginal, leaving only modest value beyond the structured fields.

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

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

Front-loaded with the core purpose, then features, examples, routing rules and behavior in clearly labeled blocks; every section is useful. Slight waste in restating the read-only/idempotent annotations already covered by structured fields.

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 rich annotations, 100% schema coverage and an output schema in place, the description only needs to cover purpose, routing and input formatting — all of which it does, including sibling disambiguation and code examples.

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 concrete worked examples of valid codigo values at each level (35, 3550308, 355030805) and repeats the size-based inference for the optional tipo, which helps an agent format a call correctly beyond the schema text.

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

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

States a specific verb and resource ('Returns details of a specific locality by IBGE code') and explicitly names the sibling tools it is not (ibge_municipios, ibge_geocodigo) plus the scenario it doesn't serve. 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?

Contains an explicit 'Use a different tool when' block with two conditions and the correct alternative for each (name-to-code, code decomposition). The precondition 'you already have the code for' is stated outright, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds value beyond that by disclosing it is 'a live GET against the public IBGE Malhas API' and that output is returned in the requested format. It doesn't discuss rate limits or error behavior, but the annotation bar is 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?

Well front-loaded with the operation in the first sentence and organized under clear headers. Some redundancy exists (resolution meanings are restated from the schema), which prevents a perfect score, 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?

With an output schema present, annotations carrying the safety profile, 100% parameter coverage, and an explicit sibling alternative, the description supplies everything an agent needs to call this tool correctly. No material gaps remain.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it classifies formats functionally (GeoJSON=data, TopoJSON=compact, SVG=image) and shows combined parameter usage (localidade + resolucao + formato) that the schema alone does not. The 'tipo' parameter is left to the schema, keeping this at 4 rather than 5.

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 (Gets) and resource (geographic meshes/maps from IBGE) plus the three output formats, and explicitly differentiates itself from the sibling ibge_malhas_tema for thematic meshes. An agent can identify the tool's function 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 (Brazil with states, São Paulo with municipalities, SVG format) and an explicit exclusion rule naming the alternative ('Thematic meshes → ibge_malhas_tema'). Both when-to-use and when-not-to-use are covered, with the alternative named.

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, and the description adds genuinely new behavioral facts: geometry is deliberately excluded because a single biome polygon exceeds 9 MB, a canonical WFS URL is returned instead, the call is a live GET against IBGE Geosserviços WFS (a different service from the Malhas API), and the response shape is Markdown plus typed structuredContent. That is substantive context beyond the annotation set.

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 (purpose, recorte list, filtering, exclusions, behavior), but the bulleted recorte list largely duplicates the enum descriptions in the schema, adding length without new meaning. Efficient overall, with one redundant 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 three-parameter, enum-driven tool with an output schema and full annotation coverage, the description closes every remaining gap an agent would face: which recortes exist, which accept `codigo`, that geometry is intentionally absent and where to fetch it, and the upstream service. No material information is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description clears that bar by explaining that `codigo` is only honored by biomas/costeiro/fronteira and that biome codes originate from the source rather than a fixed table. It adds a little over the schema, though much of the recorte enumeration restates the enum descriptions already present in the schema.

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

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

The description names a specific verb and resource ('Lists what a THEMATIC territorial recorte of Brazil contains') and enumerates exactly what comes back: feature count, codes, names, and a geometry download URL. It also explicitly differentiates itself from the sibling ibge_malhas ('Administrative meshes WITH geometry'), 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?

It states when to use an alternative ('Use a different tool when: Administrative meshes WITH geometry → ibge_malhas') and gives the condition that selects each recorte, including a dedicated 'listar' mode to inspect the catalogue without hitting the source. It also spells out when `codigo` applies versus when the call is refused, 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the description's 'read-only and idempotent' phrasing is largely redundant. It does add genuinely new context though: the backing source (live GET against the public IBGE Localidades API) and the return format (Markdown table), which 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?

Well front-loaded: purpose first, then features, examples, exclusions, behavior. All sections are short and scannable. The closing 'read-only and idempotent' clause is the one line that partially restates annotations rather than earning its space.

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

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

For a three-optional-param lookup tool with a 100%-documented schema and an output schema in place, the description covers purpose, filtering modes, worked examples, sibling routing and data source. 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 the schema already documents uf/busca/limite, so the baseline would be 3. The examples add value beyond the schema by showing that busca performs substring matching ('Belo') and that uf and busca compose as a narrowed filter, plus noting the 7-digit code in the output.

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

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

States a specific verb and resource ('Lists Brazilian municipalities from IBGE') and enumerates the three concrete capabilities: filter by state, list all 5,570, and name search. It also names the sibling tools it is not (ibge_geocodigo, ibge_localidade, ibge_vizinhos), so an agent can route 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?

Explicit 'Use a different tool when' block gives three named alternatives with the exact condition that selects each (code resolution at any level, full hierarchy of one locality, neighbors). Usage examples with real parameter values reinforce how to invoke it.

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 reinforces this and adds genuinely new context: a live GET against the public IBGE Nomes (Censo) API and a Markdown-table return format. It does not note rate limits or error behavior, keeping it short of a 5.

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

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

Front-loaded purpose sentence followed by a scannable two-mode feature list, examples, and a one-line behavior note. Every section earns its place, though the examples partially duplicate the schema's enum 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?

An output schema exists, so return values need not be explained further, and the description still tells the agent the response is a Markdown table. Both query modes, the decade bound, sex/locality filters, and read-only behavior are covered, leaving nothing an agent needs 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 adds a real constraint absent from the schema: the available decade range 1930-2010, which bounds the free-form 'decada' number. It also frames nomes as comma-separated for multi-name queries, matching the schema's wording directly.

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

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

The description names a specific verb+resource pair (queries name frequency and rankings in Brazil via IBGE) and explicitly splits the tool's two operating modes (tipo='frequencia' vs tipo='ranking'), each with its own scope. An agent can distinguish this from ibge_censo or ibge_comparar without inspecting schemas.

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

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

It clearly states when to use each mode and supplies four concrete invocation examples, including comma-separated multi-name comparison and sex filtering. It does not, however, mention when to prefer a sibling such as ibge_censo or ibge_comparar, so routing at the tool-selection level is left implicit.

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 safety annotations (readOnly, idempotent, openWorld, non-destructive), it discloses sorting (newest-first), the no-parameter default (10 most recent), the pagination header behavior, and that it is a live GET returning Markdown. These are operational traits the annotations do not 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 purpose followed by clearly labeled parameters, examples, and exclusions. Slightly long, and the parameter list partially duplicates the schema descriptions, but the added enum semantics justify most 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?

For a 7-param, zero-required search tool with an output schema, the definition covers selection, defaults, parameter meaning, return-field inventory, and the alternative tool. 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%, but the description adds real meaning: it explains what 'release' vs 'noticia' semantically denote and that omitting 'tipo' returns both, plus worked date-format and search examples. This goes beyond restating 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 precise verb+resource ('Searches and lists already-published IBGE news articles and press releases') and immediately frames the scope as published-only content, which distinguishes it from the calendar sibling. An agent can select it 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?

Gives explicit when-to-use triggers (finding recent publications, release dates, term mentions), concrete examples, and a dedicated 'Use a different tool when' section routing scheduled/upcoming dates to ibge_calendario. Nothing about 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 cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description adds genuinely useful behavior: it is a live GET against the public IBGE API, returns Markdown, values carry a year/period (sometimes 3- or 5-year ranges), can be text like '<2.5', and are null when the source has none. The '<2.5' and null-handling caveats are exactly the kind of thing an agent cannot infer from 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 the core purpose, then organized into Features, value-semantics, allowed regions/codes, and labeled examples, so an agent can skim to the needed section. It is somewhat long and repeats the region list and default-indicator set that already live in the schema, 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?

For a five-parameter, four-mode tool with no required params, the description covers mode selection, code format, region vocabulary, indicator defaults and syntax, and data-freshness caveats, while an output schema already exists so return values need not be enumerated. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description exceeds the schema by stating the default indicator set returned when indicadores is omitted, the pipe-separated ID-or-alias syntax, and worked combinations of tipo with pais/regiao/indicadores/busca. This clarifies parameter interaction (which params apply to which tipo) rather than just restating field docs.

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 and resource ('Queries international country data via IBGE') and immediately enumerates the four query modes, which cleanly separates it from Brazilian-scope siblings like ibge_estados and ibge_municipios. An agent knows this is the international-country endpoint 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 one concrete example per mode (listar, detalhes, buscar, indicadores) plus examples of region filtering and custom indicator selection, so the agent can map intent to parameters. It stops short of naming when to prefer a sibling (e.g., ibge_comparar for multi-country comparisons) or stating exclusions, so it is clear context rather than full routing guidance.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive; the description repeats those but adds genuinely new context: a live GET against the public IBGE SIDRA/Pesquisas API (not cached) and a Markdown-list return. Return format is partly covered by the output schema, so the marginal gain is modest but real.

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 in one sentence, then features, examples, and behavior in scannable sections. The 'Main surveys' catalogue and duplicated examples are somewhat verbose relative to a two-parameter list tool, but every block is relevant and well-organized.

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 values need not be explained. Description covers purpose, routing, examples, and behavior fully; nothing an agent needs to select or invoke this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by demonstrating concrete parameter usage (busca="população", detalhes="pnad") and clarifying that no parameters lists everything, adding practical meaning beyond the schema's field descriptions.

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

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

States a specific verb (lists) and resource (IBGE surveys and their tables), and explicitly contrasts with siblings: 'This lists surveys, not data.' The agent can tell it apart from ibge_sidra and ibge_sidra_tabelas 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 routing: use ibge_sidra_tabelas for table codes, ibge_sidra or the wrappers for data. Names concrete alternatives and the condition selecting each, plus worked examples (busca="população", detalhes="pnad").

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, non-destructive, so the safety profile is covered; the description goes well beyond by disclosing that estatisticas computes over all rows before pagination and ignores pagina/campos/formato, that the source now has a lower ceiling via the Aggregates API (with a concrete all-municipalities x 12 periods failure example), that values are as-published-at-extraction with no earlier version retained, that absence markers are excluded from n, and that rolling PNAD quarters are moving windows.

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 organized with headers and bulleted examples, and the purpose plus wrapper-routing appear early. Some content (territorial level codes, clasificacoes format) restates the input schema descriptions, which is the main source of slack.

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 12-parameter tool, the description supplies table-code examples, territorial-level reference, working call examples, statistics-mode semantics, source limits, and revision caveats; an output schema exists, so it needn't explain return values, and it notes the Markdown plus typed structuredContent payload anyway.

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: worked examples combining tabela/nivel_territorial/localidades, the agruparPor short-name and partial-label resolution plus refusal on ambiguous labels, and the 'last'/'all'/'allxp' conventions. It does not fully compensate on every param, hence 4 rather than 5.

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

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

States a specific verb and resource ('Queries SIDRA tables') and immediately frames itself as the low-level engine relative to named siblings (ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades). An agent can distinguish it from the wrappers 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: prefer the friendly wrappers for census themes, time series, 2-10 locality comparisons, or single-municipality panels, and use ibge_sidra_tabelas/ibge_sidra_metadados to discover a table code first. It also states exactly when to switch on estatisticas=true ('largest/smallest/mean/median/distribution/ranking') and what to do when a query is refused.

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, non-destructive, and the description partially repeats them; however it adds real value by specifying the output format ('Returns Markdown') and that it is a live GET against the public IBGE SIDRA API. It does not mention auth or rate limits, which is a minor gap 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-loaded purpose sentence, then a scannable feature list, usage sequencing, and concrete examples. Slightly longer than strictly necessary, but each block (features, when-to-use, examples) earns its place for an agent.

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 values need not be explained, yet the description still previews the metadata sections. Combined with explicit workflow placement and examples, an agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100% and each parameter is documented in the schema, so the description need not explain them. It adds usage examples for 'tabela' values but no syntax or behavioral detail for incluir_periodos/incluir_localidades beyond what the schema states.

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

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

States a specific verb and resource ('Returns metadata for a specific SIDRA table') and enumerates exactly what that metadata contains (info, territorial levels, variables, classifications, periods). It is clearly distinguishable from ibge_sidra (data query) and ibge_sidra_tabelas (table discovery).

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

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

Explicit sequencing: 'Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra', plus a 'BEFORE querying' directive. Both the predecessor and successor tools are named, 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds live GET against the public IBGE SIDRA API, returns a Markdown table, and details search behavior (AND matching, accent/case insensitivity, vocabulary mapping with notas_vocabulario in the response). This is substantial 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 purpose and organized under clear headings, but somewhat long. The survey list and multiple examples add context but could be trimmed; every section is relevant though not 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?

Given the output schema exists, return values need not be explained. The description covers purpose, usage, alternatives, behavior, search semantics, and response format, leaving no critical gap for an agent to 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 description coverage is 100%, with detailed descriptions for busca, limite, and pesquisa. The description largely repeats schema semantics (AND, accent insensitivity, vocabulary mapping) and adds only minor examples (gênero→sexo, busca="população"), so the schema already carries the parameter burden.

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+resource ('Lists and searches available SIDRA tables') and distinguishes from siblings by positioning as step 1 of the SIDRA workflow and naming ibge_sidra_metadados and ibge_sidra. It also clarifies what each result shows (code and name).

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: step 1 of the SIDRA workflow to find a table code, and when to use alternatives ('For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades'). Provides concrete examples for listing and searching.

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, non-destructive, open-world, so safety is covered. The description adds meaningful context beyond that: it is a live GET against the public IBGE Localidades API and returns a Markdown list. It also discloses the important caveat that 'proximity' is a mesoregion proxy, not true spatial adjacency — a behavioral limitation not visible in structured fields.

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

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

The features and examples are front-loaded and useful, but the mesoregion-proxy caveat is stated twice in near-identical wording ('Uses mesoregion as geographic proximity proxy' and 'proximity is approximated by shared mesoregion'), which is wasteful. Trimming the duplicate would earn back a point.

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 correctly omitted; the description still notes the Markdown list format. Features, both input modes, examples, and the central proximity limitation are all covered. The only gap is that the raio parameter is unexplained while the description implies proximity is exclusively mesoregion-based.

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 and the baseline is 3. The description's examples illustrate municipio/uf combinations, adding minor value. However, it never addresses the 'raio' parameter (radius in km, centroid-based), and its repeated claim that proximity is only a mesoregion proxy sits in tension with the schema's raio semantics, which could mislead an agent about how proximity actually works.

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 ('Finds nearby/neighboring municipalities') and immediately distinguishes itself from the sibling ibge_municipios for listing/searching. The 'Features' block clarifies the two input modes (IBGE code or name) and the optional population enrichment. An agent can place this against its siblings without opening a schema.

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

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

Gives concrete usage context (search by code or name, optional population data), three worked examples, and an explicit alternative ('for listing/searching municipalities, use ibge_municipios'). It also states the condition under which this tool is not appropriate (exact spatial adjacency requires mesh processing). Lacks a broader when-not-to-use enumeration across the other ibge_* siblings, but the routing guidance 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 cover read-only, idempotent and non-destructive, and the description still adds real context beyond them: results are capped at 10, empty list signals no match, results are relevance-ordered, and the catalog comes from a public source cached in memory. The 'read-only and idempotent' sentence partially restates annotations but the surrounding facts are genuinely additive.

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 action and return shape, then workflow, then alternatives, then query semantics — a sensible order with no wasted sentences. Slight redundancy in the final paragraph, where 'read-only and idempotent' repeats the annotations rather than adding new 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 single-parameter read tool with an output schema and full annotations, the description covers everything an agent needs: what it searches, what it returns, how many, what empty means, and how it feeds `fetch`. Return-value detail is backed by the output schema, so 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 parameter's own description already covers natural-language/keyword input and accent/case insensitivity, so the baseline is 3. The description adds that queries may be in Portuguese or English, which the schema does not state, giving a modest lift above baseline.

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

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

States a specific verb (searches) and resource (the IBGE catalog), names the return shape { id, title, url } and the ordering (relevance), and explicitly distinguishes itself from the ibge_* siblings by calling itself 'a catalog index, not a data query'. An agent can tell this apart from ibge_sidra or ibge_indicadores without opening any schema.

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

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

Gives explicit when-to-use (the OpenAI Deep Research contract requiring exactly `search` and `fetch`), an explicit hand-off ('Pass one of the returned ids to `fetch`'), and an explicit when-not/prefer-instead rule routing data questions to the ibge_* tools. 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.