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 readOnly/idempotent/openWorld/non-destructive, so the description's restatement adds limited new safety information. It does add useful behavior beyond annotations: that it is a live GET against the public SIDRA API, that it returns Markdown plus structuredContent, and that estatisticas mode ignores campos/formato and leaves registros empty.

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

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

Front-loaded with purpose, then years, themes, examples, exclusions, and behavior in a scannable block structure. Some redundancy between the theme list in the description and the tema enum, but each section serves routing or usage.

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?

Nine optional parameters, an output schema present, and full theme/year enumeration are all covered; return shape, statistics mode, and sibling disambiguation are addressed. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by documenting cross-parameter interactions (estatisticas overrides campos/formato/pagina) and by giving worked call examples mapping ano/tema/nivel_territorial values. agruparPor's partial-label resolution caveat is also surfaced in prose.

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

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

States a specific verb and resource ('Queries IBGE Demographic Census data (1970-2022)') and immediately frames scope as a simplified alternative to raw SIDRA table access. The 'Use a different tool when' block distinguishes it from ibge_cidades, ibge_comparar and ibge_sidra explicitly.

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

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

Gives concrete when-to-use examples (population by year, historical series, literacy by state, listing tables) and explicit routing exclusions to three sibling tools. The statistics-mode trigger ('which municipality had the largest 2022 population?') removes ambiguity about 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?

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 read-only, idempotent, open-world, non-destructive, so the safety profile is covered; the description adds useful extra context about the live GET against public IBGE APIs (SIDRA and Localidades) and the Markdown plus structuredContent return. The 10-locality cap is also disclosed behaviourally. It stops short of noting failure modes (invalid codes, missing indicators).

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 indicator list, features, examples, and a routing line. Every block earns its place and the exclusions appear before 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?

With an output schema present and full annotations, the description only needs to cover intent, scope, routing, and input shape — all of which it does, including a 'listar' escape hatch for indicator discovery.

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 description adds little — and where it does it can mislead: it describes 'pib' as 'GDP per capita', while the schema defines pib as 'PIB a preços correntes (Mil Reais)', a total at current prices. An agent relying on the description would misinterpret the returned value. The code-format guidance (7-digit municipality, 2-digit UF) matches the schema rather than extending it.

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') and immediately scopes the resource type (municipalities or states, 2–10 at once, one indicator). The closing line 'Use this tool ONLY to rank/compare 2–10 localities on one indicator' makes it unambiguously distinguishable from siblings like ibge_indicadores or ibge_sidra.

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

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

Explicit both ways: 'Use this tool ONLY to rank/compare 2–10 localities on one indicator' gives the when, and 'For a single locality, use ibge_cidades, ibge_censo, or ibge_sidra' names the alternatives and the condition that selects them. Concrete example calls reinforce the routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered; the description still adds real value by disclosing that statistics mode ignores campos/formato, returns empty registros, and computes over ALL rows before truncation, plus the Markdown + structuredContent return shape. The 'read-only and idempotent' sentence largely restates annotations and is the only wasted line.

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: purpose first, then a scannable indicator taxonomy, territorial legend, worked examples, statistics-mode rules, and exclusions. The indicator list is partly duplicated from the schema's indicador description, which is the main redundancy, but no section is 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?

With an output schema, full annotation coverage, and 100% param documentation, the description only needs to cover selection and mode-switching semantics — which it does thoroughly, including edge behavior of statistics mode and the fallback routing to siblings. 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%, so baseline is 3; the description earns above that by documenting cross-parameter interactions the schema states only piecemeal (estatisticas overrides campos/formato; agruparPor ranks by descending sum) and by giving concrete usage examples for nivel_territorial and localidade. Territorial codes and indicator values are effectively demonstrated, not just listed.

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 Brazil health indicators, served through IBGE's SIDRA'), names the upstream producers (DataSUS) and enumerates all nine indicator groups with one-line glosses. An agent can immediately tell this apart from ibge_sidra, ibge_cidades or ibge_censo.

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 an explicit 'Use a different tool when' block routing to three named siblings with the selecting condition for each, plus dedicated guidance for statistics questions ('which state has the highest infant mortality?') with the estatisticas=true switch. Nothing about tool selection is left to inference.

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

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

Annotations already declare 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?

Annotations already cover read-only/idempotent, but the description goes well beyond them: it discloses the live GET against the public SIDRA API, the Markdown + structuredContent return shape, the revision policy (IBGE revises figures and no earlier version is kept, retrieved_at marks the extraction instant), and the PNAD rolling-quarter semantics that would otherwise be misread as calendar quarters. This is the kind of context annotations cannot carry.

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 indicator catalogue is front-loaded and every entry earns its place by giving unit and territorial scope; the closing behavior line is a single efficient sentence. It is long, and the 'Statistics mode' paragraph partially restates the estatisticas/agruparPor schema descriptions, which is the main redundancy preventing 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?

With 10 parameters, an output schema, and full annotation coverage, the description supplies everything else an agent needs: which indicator names exist, how periods and territorial levels map to examples, how statistics mode changes output shape, and how to interpret the returned labels. Nothing required for a correct call 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 genuinely adds meaning: it warns that the 'Variável' and period columns are the only source of truth for what a number means before comparing values, that estatisticas also controls topN list size, and that campos/formato are ignored and registros comes empty in statistics mode. It does not re-explain periodos syntax or localidades codes beyond the schema, keeping it short of a 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 IBGE economic and social indicators') and then enumerates every available indicator with its unit and scope, so an agent knows exactly what data domain this covers. It explicitly separates itself from siblings via the 'Use a different tool when' block and points to ibge_sidra for other variables from the same table.

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 four concrete invocation examples (GDP, IPCA last 12 months, unemployment by state, listing indicators), explicit routing rules to ibge_comparar / ibge_censo / ibge_cidades / ibge_sidra, and a clear trigger condition for estatisticas=true ('largest/smallest/mean/median/distribution/ranking'). When to use and when to use something else 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 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 readOnly/idempotent/openWorld, but the description adds substantial context beyond them: values are a point-in-time snapshot with no revision history, absence markers are excluded from n, estatisticas ignores pagina/campos/formato and returns empty registros, and the Aggregates API ceiling rejects all-municipalities × 12 periods while × 8 works. It also discloses the return shape (Markdown plus typed structuredContent).

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

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

Front-loaded with purpose and routing, which is right, but it runs very long and partly duplicates the schema: the table-code list and the territorial-level code list restate what is already in the tabela and nivel_territorial parameter descriptions. The 'What each number is' paragraph is valuable but buried mid-document rather than signposted.

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 12-parameter query engine: with an output schema present, return-value shape need only be named, and it is. Revisions, source-side size limits, statistics-mode overrides, and sibling routing together cover everything an agent needs to call this correctly on the first attempt.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by giving worked examples (tabela="6579", nivel_territorial="3", localidades="3550308") and explaining cross-parameter interactions, e.g. agruparPor ranking groups by descending sum with a named "Variável" auto-grouping when units differ. It stops short of explaining classificacoes or variaveis syntax, which the schema already covers.

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 SIDRA tables") and immediately scopes what SIDRA contains. It explicitly positions itself as "the low-level engine" and enumerates which sibling wrappers cover which use cases, so an agent can distinguish it from ibge_censo, ibge_indicadores, ibge_comparar and ibge_cidades without opening a schema.

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

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

Gives explicit routing rules for four sibling tools plus a prerequisite step ("Use ibge_sidra_tabelas and ibge_sidra_metadados to find a table code…before querying"). It also defines when to switch on estatisticas (largest/smallest/mean/median/ranking) and when to narrow periodos or raise nivel_territorial to avoid source refusals.

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.