IBGE Brasil MCP

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior beyond that: the id-validity constraint, the error case for unknown ids, and the fact that it performs 'a live GET against the public source when the document needs it.' No contradiction with annotations exists.

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

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

The description is well-structured with a lead sentence covering the core purpose, followed by context, behavioral notes, and alternatives. It is not bloated, but it slightly repeats annotation information ('read-only and idempotent') and has a minor capitalization/formatting issue, so it is not perfectly concise.

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

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

For a tool with one parameter and an output schema, the description is complete: it defines the input source, valid ids, error behavior, return shape, domain context, relationship to siblings, and safety profile. Nothing essential is missing for an agent 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?

The schema already documents the sole required parameter `id` at 100% coverage, so the baseline is 3. The description adds value by explaining the id must come from `search`, that only such ids are valid, and that invalid ids return an error, which gives the agent more semantic understanding than the schema alone.

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

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

The description states a specific verb and resource: 'Returns the full document for an id obtained from `search`', and even lists the exact return shape ({ id, title, text, url, metadata }) with clarifications for `text` and `url`. It clearly distinguishes itself from the many `ibge_*` sibling tools by positioning itself as the companion of `search` and noting that the `ibge_*` tools remain 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?

It gives an explicit usage rule: only ids returned by `search` are valid, and unknown ids produce an error. It also names alternatives, saying the `ibge_*` tools are the ones for data queries, so an agent has a clear when-to-use vs. when-not-to-use decision.

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 mark the tool as read-only and idempotent, and the description reinforces this while adding new context: it is a live GET against the public IBGE Calendário API and returns a Markdown list. The event-type clarification (Release vs Collection) further aids the agent in understanding what the tool exposes.

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

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

The description is well-structured with a one-sentence summary, bullet-point features, an event-type breakdown, practical examples, and a routing note. Every sentence earns its place, and the most important purpose information is front-loaded.

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

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

Given an output schema exists and the input schema is fully covered, the description adds everything needed: usage examples, event-type semantics, API behavior, return format, and a sibling alternative. No critical gap remains for an agent to invoke 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, but the description adds meaningful enrichment: examples mapping produto to 'IPCA', de/ate to date ranges, and tipo to 'coleta'. It explains the semantics of the two event types, which supplements the schema's enum descriptions without redundancy.

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

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

The description opens with a specific verb ('Queries') and resource ('IBGE release and collection calendar'), then breaks down the tool's features. It also explicitly distinguishes itself from ibge_noticias by naming the sibling for published news, removing any ambiguity about scope.

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

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

The description gives clear usage context with bullet-pointed features and concrete examples for different filters. It explicitly states 'Use a different tool when: Already-published news and releases → ibge_noticias', providing a direct alternative and exclusion.

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 carry readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the bar is lower. The description adds useful context beyond those: "a live GET against the public IBGE SIDRA API," the return shape ("Returns Markdown plus a typed structuredContent payload"), and the statistics-mode side effects ("campos/formato are ignored and registros comes empty; agruparPor... ranks groups by descending sum"). It is consistent with the annotations — no contradiction — and the only absent items (rate limits, pagination details) are minor for a public read-only GET.

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

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

The core purpose is front-loaded in the opening sentence, followed by compact list-form years and themes that include English translations. The examples are one-line code-style snippets, the statistics-mode paragraph is dense but necessary, and the routing section is a tight three-item bulleted list. Though longer than average, every sentence earns its place — this is information density, not bloat, for a tool with 9 optional parameters.

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, zero-required tool with 100% schema coverage, an output schema, and four annotation hints, the description covers the essential call patterns, statistics-mode behavior, and sibling routing. One minor gap: the description's 'Available themes' list shows only 9 themes while the schema enum allows 17 (missing migracao, indigenas, quilombolas, saneamento, deficiencia, nupcialidade, fecundidade), which could under-suggest valid options. The note about Markdown plus structuredContent payload closes the return-format loop that the output schema does not fully address.

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

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

Schema description coverage is 100%, so the baseline is 3 — and the description does add value beyond the schema. It provides concrete usage combinations ("Population 2022: ano='2022', tema='populacao'", "Literacy 2010 by state: ano='2010', tema='alfabetizacao', nivel_territorial='3'"), explains the special 'listar' theme value, and clarifies the interaction semantics of estatisticas with agruparPor/topN/campos/formato. These examples teach call patterns the individual parameter descriptions do not.

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 first sentence states a specific verb and resource: "Queries IBGE Demographic Census data (1970-2022)" with a clear time range. It further distinguishes itself from siblings by self-identifying as a "Simplified tool to access census data without knowing SIDRA table codes," and the 'Use a different tool when' section explicitly names ibge_cidades, ibge_comparar, and ibge_sidra as the alternatives it is not. An agent can immediately tell this from its siblings without opening the schema.

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

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

The description gives explicit when-to-use guidance: "for largest/smallest/mean/median/distribution/ranking questions over census data ... use estatisticas=true." It then gives explicit when-not-to-use guidance naming alternatives and their conditions: "One municipality's current panel (estimate, HDI, GDP) → ibge_cidades; Comparing/ranking localities → ibge_comparar; An arbitrary SIDRA table → ibge_sidra." Both the trigger conditions and the routing targets 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, and non-destructive behavior; the description reinforces this and adds 'a live GET against the public IBGE APIs' plus the return shape ('Markdown plus a typed structuredContent payload'). It doesn't mention rate limits or data freshness, but given the annotation coverage this is a minor gap.

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

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

Well-structured with labeled sections: features, available indicators, examples, sibling routing, and behavior. The single-municipality scope is boldly emphasized. No filler or redundant sentences.

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

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

Covers purpose, scope, exclusions, examples, valid indicator vocabulary, and return format. With full schema coverage, annotations, and output schema present, nothing essential is missing for an agent to call this tool correctly.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3; the description adds value by listing valid indicator names and giving examples that map tipo, municipio, and indicador to specific calls (e.g., São Paulo panorama). This goes beyond the schema's brief Portuguese 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?

Opens with a specific verb and resource — 'Queries municipal indicators from IBGE' — and immediately names the Cidades@ portal. It explicitly says 'This tool is the panel for a SINGLE municipality' and contrasts it with censo/comparar/indicadores, so an agent can distinguish it from sibling tools.

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

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

Provides concrete 'Use a different tool when' routing rules naming ibge_censo, ibge_comparar, and ibge_indicadores. It also gives worked examples for each tipo value, making invocation conditions and parameter combinations explicit.

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

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

The description states it is read-only, idempotent, performs a live GET against the public IBGE CNAE API, and returns Markdown. This goes beyond the annotations by disclosing the transport mechanism and output format, with no contradiction.

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

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

The description is well-structured with purpose, hierarchy, features, examples, and behavior. It is front-loaded with the core purpose, and each section adds useful information without redundant 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?

Given the tool's complexity, the hierarchical taxonomy is explained clearly, all search modes are covered, and the output format is disclosed. The output schema and per-parameter descriptions fill in remaining details, leaving no meaningful gap for an agent to invoke 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 description coverage is 100%, so the schema already documents all four parameters well. The description adds illustrative usage examples, but these do not materially expand the semantic meaning beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Queries CNAE (National Classification of Economic Activities) from IBGE.' It further defines CNAE and lists concrete features, making the tool's unique purpose clear among the many IBGE sibling tools.

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

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

The features and examples clearly indicate when to use the tool — searching CNAE by code, by description, or by hierarchical level. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous for an agent.

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, and non-destructive behavior, and the description reinforces this by stating it is a 'live GET against the public IBGE APIs.' It also adds useful context about the return type: Markdown plus a typed structuredContent payload.

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

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

The description is well-structured with a clear summary, indicator list, feature list, examples, and routing guidance. It is front-loaded with the core purpose and every section earns its place given the tool's complexity.

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

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

Covers the tool's scope, accepted inputs, all indicators, output formats, examples, and behavioral expectations. With a rich output schema present and complete parameter descriptions, nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The input schema already covers all parameters exhaustively with enum descriptions and 100% coverage. The description adds value with concrete examples, code-length conventions, and feature context like ranking and statistics, raising it above the schema-only 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?

The description clearly states the tool compares data between localities and explicitly scopes it to ranking/comparing 2–10 localities on one indicator. It names sibling tools for single-locality lookups, making the distinction immediate.

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

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

Provides explicit usage boundaries: 'Use this tool ONLY to rank/compare 2–10 localities on one indicator.' It also lists specific alternatives (ibge_cidades, ibge_censo, ibge_sidra) for the single-locality case, giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations, the description discloses that it is a live GET against the public IBGE SIDRA API and that it returns Markdown plus typed structuredContent. It also reveals important mode-specific behavior: in estatisticas=true mode, campos/formato are ignored and registros comes empty. None of this contradicts the annotations.

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

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

The description is longer than average and partially duplicates the indicator list already present in the schema, but it is well organized with headings, examples, and a clear alternatives section. The extra length earns its place by adding examples and mode-specific caveats rather than 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?

For a 9-parameter tool with multiple modes, the description is remarkably complete: it covers the indicator vocabulary, territorial levels, example requests, statistics-mode behavior, exclusions/alternatives, and high-level behavior. Because an output schema exists, the lack of a detailed return-value explanation is acceptable.

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?

Even though schema description coverage is 100%, the description adds concrete usage meaning: example parameter combinations ('Deaths in SP: indicador="obitos", nivel_territorial="3", localidade="35"'), the meaning of territorial codes, and advanced semantics for agruparPor and estatisticas. It even lists a valid indicator, autoavaliacao_saude, that is absent from the schema's indicador list.

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

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

The description opens with a specific verb and resource ('Queries Brazil health indicators') and then enumerates the indicator families and territorial levels, making the tool's scope unmistakable. It also names adjacent tools (ibge_cidades, ibge_censo, ibge_sidra) for nearby use cases, so an agent can tell it apart from siblings.

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

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

The description is explicit about when to use the tool and when not to: it gives a 'Use a different tool when' section with concrete alternatives, and it tells the agent to enable estatisticas=true for largest/smallest/mean/median/ranking questions. This leaves 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, and destructiveHint=false. The description adds valuable context by stating it is a 'live GET against the public IBGE Localidades API' and that it 'Returns a Markdown table,' which enriches the behavioral profile beyond the structured annotations.

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

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

The description is well-structured with a leading purpose statement, concise feature bullets, examples, sibling-tool routing, and a behavior note. Every section earns its place and no unnecessary filler is present.

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 simple list tool with two optional enumerated parameters, an output schema, and annotations covering safety, the description is complete. It discloses the API source, the Markdown table return format, filtering and sorting behavior, and exactly when to delegate to sibling tools.

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

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

Schema coverage is 100% and both parameters already have descriptions and enums. The description adds practical meaning by mapping region names to codes, explaining sort fields in plain language, and giving concrete examples such as regiao='NE' and ordenar='sigla', which helps the agent use the parameters correctly.

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

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

The description opens with a specific verb and resource: 'Lists all Brazilian states from IBGE.' It further differentiates from siblings by naming ibge_municipios and ibge_localidade as alternatives for municipalities and locality details, so an agent can clearly tell this tool apart.

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

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

The 'Use a different tool when' section explicitly excludes municipalities and locality-detail cases, pointing to the correct sibling tools. Examples also show when to call with no parameters, with a region filter, or with a sort field, making invocation conditions clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful operational context beyond annotations: it is 'a live GET against the public IBGE Localidades API' and 'Returns Markdown.' It doesn't mention rate limits or error cases, but it provides meaningful extra transparency.

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

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

The description is well-organized with bullets, code-structure details, examples, and routing guidance. There is minor redundancy between the opening summary, the features list, and the closing 'This tool decodes...' sentence, but overall it is scannable and front-loaded with the most important 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 tool with three optional parameters and an output schema, the description covers purpose, accepted formats, usage examples, behavioral guarantees, return format, and explicit alternatives. Nothing essential for an agent to select and invoke this tool correctly is missing.

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

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

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by giving concrete examples (codigo='3550308', nome='São Paulo', nome='Campinas', uf='SP') and by explaining the code hierarchy that governs which param format is valid.

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

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

The description opens with a specific action and resource: 'Decodes IBGE codes or searches codes by locality name.' It further clarifies scope by explaining code structure at region, state, municipality, and district levels and explicitly names sibling tools it is not (ibge_municipios, ibge_localidade).

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

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

The description provides explicit when-to-use guidance and an explicit 'Use a different tool when' section naming alternatives and their conditions. This lets an agent clearly distinguish this tool from ibge_municipios and ibge_localidade without inspecting their schemas.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds beyond that: it states the implementation is a live GET against the public IBGE SIDRA API, returns Markdown plus structuredContent, and discloses that in statistics mode campos/formato are ignored and registros comes empty. No contradiction with annotations.

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

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

The description is long but every block earns its place: a front-loaded purpose sentence, grouped indicator catalog, compact examples, statistics-mode rules, sibling routing, and a one-line behavior note. Markdown headings and bullet lists make it skimmable rather than a wall of text.

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, 0-required tool with an output schema, the description is complete: indicator vocabulary, statistics/grouping semantics, exclusions in stats mode, alternatives, and API/response behavior are all covered. The remaining parameters (localidades, categoria, topN) are adequately documented in the schema, so nothing needed for correct invocation is missing.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds substantial value: it enumerates valid indicador values with meanings, clarifies estatisticas=true semantics (full distribution, top/bottom over all rows before truncation), explains agruparPor ranking behavior, and illustrates periodos and nivel_territorial usage. This is exactly the kind of semantic information an agent needs beyond the schema.

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

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

Opens with a specific verb and object — 'Queries IBGE economic and social indicators' — then names all available indicators grouped by category. The 'Use a different tool when' section explicitly contrasts ibge_comparar, ibge_censo, and ibge_cidades, so an agent can discriminate it from siblings.

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

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

Provides explicit routing guidance: use a different tool for locality comparison, census themes, or single-municipality panels. It also gives concrete parameter examples (indicador, periodos, nivel_territorial, estatisticas) and a clear condition for statistics mode, 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=true, idempotentHint=true, and destructiveHint=false. The description goes further by adding 'a live GET against the public IBGE Localidades API' (network call, no auth gate), 'Returns a Markdown record' (output format), and 'complete hierarchy' details. This enriches the annotation-backed safety profile with concrete operational context, though it stops short of discussing error cases.

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

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

The description is well-organized with a leading purpose sentence, bulleted features, practical examples, alternative-tool routing, and a concise behavior note. Every section earns its place, and the most important scoping statement is front-loaded early.

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 simple two-parameter schema, an existing output schema, and comprehensive annotations, the description covers all essential angles: exact purpose, parameter examples, differentiation from siblings, and behavioral expectations. An agent can invoke this tool correctly without needing further clarification.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving real-world examples mapping code lengths to entity types (35, 3550308, 355030805) and by describing the hierarchy output that codigo unlocks. It does not, however, deepen the meaning of the optional tipo parameter beyond the schema's inference note.

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 clear action and resource: 'Returns details of a specific locality by IBGE code.' It differentiates from siblings by explicitly naming ibge_municipios and ibge_geocodigo and the conditions under which they should be used instead, so an agent can correctly identify this tool's unique scope.

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

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

The description gives explicit when-to-use guidance: 'returns the full record of ONE locality you already have the code for.' It then names exact alternatives and their triggers, such as using ibge_municipios or ibge_geocodigo when you have a name but not a code, and ibge_geocodigo for code decomposition. This leaves no ambiguity about selection.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false), lowering the burden on the description. The description adds an operational detail: "a live GET against the public IBGE Malhas API", which conveys that no authentication is needed and that the operation is a network read. It consistently reinforces the annotations rather than contradicting them; only rate-limit and error behavior are unaddressed, which is minor for a public read-only endpoint.

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

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

The description is long but every section earns its place for a 6-parameter tool with non-obvious locality semantics; it uses bullet groups and short headers to stay scannable and front-loads the core purpose before details. Minor redundancy exists where the Features list restates the formato/qualidade enums already present in the schema, but no section reads as filler.

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

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

For a complex tool with 4 enum parameters and intricate locality/resolution semantics, the description covers the hard parts: formats, locality codes, resolution levels, quality options, worked examples, and alternative-tool routing, and it states the return behavior. The output schema exists, so return-value structure needs no elaboration. The only gap is the interaction between `tipo` and `localidade` (which overrides which) and the conditional `intrarregiao` filter, both left to the 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 description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it decodes locality values ('BR'/'1' = Brazil, state abbreviations, state codes, 7-digit municipality codes) and resolution semantics (0=outline, 2=states, 5=municipalities), with worked examples mapping parameters to real use cases. The `tipo` and `intrarregiao` parameters remain schema-only, but their schema descriptions are adequate.

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: "Gets geographic meshes (maps) from IBGE" in three named formats, which is far beyond the minimal title "Malhas geográficas". It also explicitly distinguishes itself from the sibling ibge_malhas_tema by noting what it is not (thematic meshes). An agent can tell exactly what this tool produces 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 routing examples ("Brazil with states: localidade="BR", resolucao="2"") that demonstrate when to call this tool. It includes an explicit exclusion clause — "Use a different tool when: Thematic meshes... → ibge_malhas_tema" — which routes the agent to the correct sibling without requiring the sibling's schema. This is the strongest form of usage guidance: when-to-use and when-not-to-use are both stated.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond that: it is a 'live GET against the public IBGE Malhas API' and returns the mesh in the requested format. This reinforces and slightly extends the annotation information without contradicting it.

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

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

The description is well-organized with clear sections for themes, biome codes, examples, routing to alternatives, and behavior. It is longer than strictly necessary because it repeats some enum values already in the schema, but every section earns its place by clarifying usage or adding non-obvious details.

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 rich annotations, the description covers the core needs: what the tool does, what themes exist, how to use codigo for biomes, when to use ibge_malhas instead, and behavioral safety. It does not explicitly explain whether codigo is required for each non-biome theme, but the 'listar' theme and examples mitigate that gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value on top: it maps biome codes to names (1=Amazon through 6=Pantanal), provides example combinations of tema and codigo, and shows how to use resolucao. This goes beyond the schema's generic 'código específico do tema' phrasing.

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

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

The description opens with a specific verb and resource: 'Gets thematic geographic meshes from IBGE.' It clearly distinguishes the tool from its administrative counterpart by explicitly routing administrative mesh requests to ibge_malhas, so an agent can tell exactly what this tool covers.

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?

Usage guidance is explicit: it lists all supported themes, gives concrete examples for common cases, and explicitly states 'Use a different tool when: Administrative meshes' with the target sibling tool named. This tells the agent both when to use this tool and when to switch.

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, and non-destructive behavior. The description adds useful operational context: it is a live GET against the public IBGE Localidades API and returns a Markdown table, which clarifies network dependency and output format beyond the annotations.

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

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

The description is well-structured with a clear lead sentence, bulleted features, examples, sibling routing, and behavioral notes. Every section serves a distinct purpose and no sentence is wasted.

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

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

Given three optional parameters, a rich sibling set, and an output schema, the description covers what the tool does, how to filter, what it returns, when not to use it, and its live/read-only nature. An agent has enough context to select and invoke it correctly without further research.

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 value with practical examples like uf='SP', busca='Campinas', and combined uf='MG', busca='Belo'. It also states that the return includes a 7-digit IBGE code, clarifying output semantics not covered by the input 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 opens with a specific verb and resource: 'Lists Brazilian municipalities from IBGE.' It clearly defines the core features (by state, all municipalities, name search) and explicitly names sibling tools it is not, making differentiation immediate.

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

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

The 'Use a different tool when' section explicitly routes agents to ibge_geocodigo, ibge_localidade, and ibge_vizinhos for related but distinct use cases. It also provides concrete parameter examples that show when to use uf, busca, or both.

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

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

The description explicitly states the tool is read-only, idempotent, a live GET against the public IBGE Nomes API, and that it returns a Markdown table. This adds meaningful behavioral context beyond the annotations, and there is no contradiction.

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

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

The description is well-structured with a purpose statement, feature bullets, examples, and a behavior note. It is front-loaded, uses high-signal examples, and every section earns its place without redundant 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?

Together with the fully described schema, enums, output schema, and annotations, the description covers modes, required parameters, optional filters, examples, API behavior, return format, and safety. An agent has everything needed to select and invoke 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?

The input schema already describes all six parameters with 100% coverage, including enums, defaults, and constraints. The description adds value by showing cross-parameter usage through examples, clarifying comma-separated names, and documenting the 1930-2010 decade range, which goes beyond the schema.

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

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

The opening sentence, 'Queries name frequency and rankings in Brazil (IBGE),' names the exact verb, resource, and scope. It then enumerates two distinct query modes (frequencia and ranking), which clearly differentiates it from sibling tools that cover censuses, cities, indicators, and other IBGE datasets.

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

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

The description provides clear context through mode-specific feature lists and concrete examples for frequency, ranking, and filtering. It does not explicitly name alternatives or say when not to use this tool, so it stops short of a full when-to-use/when-not-to-use guide.

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=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral detail beyond those flags: results are sorted newest-first, no parameters returns the 10 most recent items, it is a live GET against the public API, and it returns a Markdown list with a header reporting total count and current page. No contradiction with annotations.

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

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

The description is long but every section earns its place: purpose, when-to-use, parameter explanations, output shape, concrete examples, and a clear pointer to an alternative tool. It is well-structured with headers and bullet-like lists, front-loads the core purpose, and contains no filler or tautology.

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

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

For a read-only list tool with seven optional parameters, the description is complete: it explains the return fields, sorting order, defaults, pagination, max limits, examples, and the single important sibling distinction. The output schema and annotations cover the remaining structured details, so nothing critical is missing for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by explaining 'tipo' as 'release' (official publication of survey results) versus 'noticia' (general news), noting 'omit for both', giving explicit date format examples, and clarifying pagination and quantidade behavior with defaults and max. This goes beyond simply 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?

The description starts with a specific verb-resource pair: 'Searches and lists already-published IBGE news articles and press releases.' It clearly distinguishes this from related tools by saying scheduled/upcoming publications belong to ibge_calendario, and it names concrete use cases like finding indicator releases or mentions of '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?

Usage context is explicit: 'Use this to find recent IBGE publications or announcements about a survey or topic' and it gives concrete examples. It also names the exact alternative for a different scenario: 'Use a different tool when: Scheduled/upcoming release dates (not yet published) → ibge_calendario.' This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description reinforces these with 'read-only and idempotent' and adds operational detail: 'a live GET against the public IBGE Países API' and 'Returns Markdown.' This goes beyond the structured annotations and gives the agent concrete expectations about network dependency and output format.

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

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

The description is well organized with a one-line summary, feature bullets, region list, code convention, examples, and a behavior note. Each section is short and non-redundant; no filler sentences are present.

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

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

For a tool with five optional parameters and an output schema, the description covers all operation modes, required code format, available regions, example invocations, and return format. The output schema handles return-value details. Nothing critical is missing for an agent to 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?

The input schema has 100% coverage, so the baseline is 3. The description adds value by providing worked examples that bind values to use cases (listar, detalhes, buscar, regiao) and enumerating the valid region strings. It supplements the schema without replacing it, which justifies a small uplift.

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

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

The description opens with 'Queries international country data via IBGE' and enumerates specific operations (list, details, search, filter by region). This clearly identifies the resource (international countries) and distinguishes it from sibling tools like ibge_estados and ibge_municipios, which focus on Brazilian geographic units.

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

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

The description provides concrete usage examples for each tipo value, lists valid regions, and specifies the ISO-ALPHA-2 code convention. It does not explicitly name alternative tools to use instead, but the 'international country data' framing and region list make the intended scope clear enough for an agent to decide when to use 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, and openWorldHint. The description adds concrete details beyond those annotations: 'a live GET against the public IBGE SIDRA/Pesquisas API' and 'Returns a Markdown list.' It could also mention error or rate-limit behavior, but for a read-only list tool the disclosure is solid and non-contradictory.

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

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

The description is well-structured with Purpose, Features, Main surveys, Examples, and Routing sections, and the core statement is front-loaded. The main-survey list is slightly extra but informative for an agent unfamiliar with IBGE domains, and overall the text is not bloated.

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

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

The tool is simple: zero required parameters, 100% schema coverage, an output schema, and clear annotations. The description covers what it does, how to invoke it, what it does not do, and its read-only behavior. An agent has everything needed to call it correctly without further inference.

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 value by mapping parameters to concrete examples: busca="população" and detalhes="pnad". It also characterizes busca as searching by name/code and detalhes as showing details and tables, going beyond the bare schema 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?

The description opens with a specific verb and resource: 'Lists available IBGE surveys and their tables.' The Features list enumerates search, details, and categorization capabilities, and the closing 'This lists surveys, not data' explicitly distinguishes it from data-query siblings. An agent can clearly tell this tool apart from ibge_sidra, ibge_sidra_tabelas, and the wrapper tools.

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

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

The description explicitly routes to alternatives: 'To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper...).' The examples further clarify when to call with no parameters, with busca, and with detalhes. This leaves little ambiguity about when to select this tool versus its siblings.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already cover the safety profile, so the bar is raised — and the description clears it. It adds the concrete mechanism ('a live GET against the public IBGE SIDRA API'), the return shape ('Markdown plus a typed structuredContent payload'), and several non-obvious behaviors: estatisticas=true ignores pagina/campos/formato, processes ALL rows before pagination, returns an empty registros, excludes SIDRA absence markers, and respects the 100,000-value cap. This is exactly the hard-won context 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-structured and front-loaded: definition → common tables → territorial levels → examples → complex stats mode → sibling routing → behavior statement. The length is justified by 12 parameters and a genuinely complex special mode, and each section earns its place. It is not maximally tight — the territorial-level list repeats schema content and the statistics paragraph is dense — but the organization compensates.

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 low-level engine with 22 siblings, the description covers everything needed to select and invoke it correctly: purpose, data scope, common table codes, examples, special-mode behavior, parameter interactions, cap limits, sibling routing, and safety profile. An output schema exists, so return-value details need no elaboration here. No material gap remains.

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

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

Schema description coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description earns a point above baseline by supplying real table-code examples ('tabela="6579", periodos="2023"', 'localidades="3550308"'), a curated quick-reference of territorial levels, and cross-parameter semantics: estatisticas=true ignoring pagina/campos/formato, agruparPor ranking behavior ('grupos[0] = maior total'), and SIDRA absence markers excluded from n. The territorial-level list partially duplicates the schema's nivel_territorial description, which prevents 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 SIDRA tables (IBGE's Automatic Recovery System)' — and immediately distinguishes itself from siblings: 'ibge_sidra is the low-level engine. Prefer a friendlier wrapper when it fits,' naming ibge_censo, ibge_indicadores, ibge_comparar, and ibge_cidades. An agent can tell this tool apart from the rest of the 22-tool family from the description alone.

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

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

Provides explicit when-to-use routing with conditions: Census themes → ibge_censo, economic/social time series → ibge_indicadores, rank/compare 2–10 localities → ibge_comparar, one-municipality panel → ibge_cidades, and directs the agent to ibge_sidra_tabelas and ibge_sidra_metadados before querying. It also defines when the estatisticas=true mode is the right choice: 'for largest/smallest/mean/median/distribution/ranking questions'.

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, and the description repeats these rather than contradicting them. It adds useful behavioral context beyond the annotations: it is a live GET against the public IBGE SIDRA API and returns Markdown.

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

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

The description is well-structured with a clear opening, feature bullets, examples, and a behavior note. It is slightly redundant because the workflow guidance appears twice ('BEFORE querying' and 'Use this after finding... before querying'), but overall every section 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?

Given the moderate complexity, full schema coverage, existing output schema, and strong annotations, the description provides enough context: workflow placement, example table codes, metadata content categories, return format, and API behavior. The optional parameters are adequately documented in the schema, so their absence from the description is not a significant gap.

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

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

The schema already covers 100% of the parameter descriptions, so the baseline is 3. The description adds illustrative examples (tabela='6579', '9514', '4714') that help contextualize realistic values, but it does not add much semantic meaning beyond the schema's existing parameter documentation.

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: 'Returns metadata for a specific SIDRA table.' It also differentiates from siblings by placing it in the workflow between ibge_sidra_tabelas and ibge_sidra, so an agent can tell it apart from the related list and data-query tools.

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

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

The usage guidance is explicit: use this tool to understand table structure BEFORE querying data with ibge_sidra, after finding a table code via ibge_sidra_tabelas. This directly tells the agent when to use this tool relative to its closest sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the bar is lower. The description adds valuable behavioral context beyond annotations: it is 'a live GET against the public IBGE SIDRA API' and 'Returns a Markdown table.' This tells the agent about network dependence and output format. It slightly redundantly restates read-only/idempotent, but the extra context justifies a 4.

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

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

The description is longer than average but well-structured: a crisp one-sentence summary, a feature bullet list, brief background on SIDRA surveys, examples, workflow placement, and behavior. Each section earns its place. It could be tightened by removing the survey-list background, but the organization and front-loaded purpose keep it effective.

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?

All three parameters are optional and documented, the workflow is fully laid out, alternatives are named, and the return format is stated ('Returns a Markdown table'). The presence of an output schema further reduces the need for return-value detail. Nothing an agent needs to decide whether and how to call 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 input schema covers 100% of parameters with descriptions, including default and bounds for limite. The description adds practical examples ('busca="população"', 'pesquisa="censo"', list with no parameters), which reinforce the schema but don't significantly extend it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a clear verb+resource statement: 'Lists and searches available SIDRA tables.' It then enumerates concrete capabilities (list, search, filter, show code/name) and explicitly positions itself as step 1 of a workflow, distinguishing it from sibling tools like ibge_sidra_metadados and ibge_sidra. The differentiation from wrapper tools is also explicit.

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

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

The description gives direct when-to-use guidance: 'This is step 1 of the SIDRA workflow: find a table code → ibge_sidra_metadados (structure) → ibge_sidra (query).' It also names alternatives and a decision rule: 'For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades.' This is exactly the kind of routing an agent needs.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds meaningful behavior beyond those: it performs a live GET against the public IBGE Localidades API, returns a Markdown list, uses mesoregion as a geographical proxy, and can optionally include population data. It stops short of a 5 because the raio parameter creates some ambiguity about whether the mesoregion approximation is always used.

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

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

The description is well structured with features, examples, and a behavior note, and it front-loads the core purpose. However, the limitation about mesoregion being an approximation is stated twice ('Uses mesoregion as geographic proximity proxy' and later 'proximity is approximated by shared mesoregion'), which is redundant and costs it a higher score.

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

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

For a 4-parameter tool with strong annotations and a 100% schema coverage, the description is largely complete: it covers input modes, output format, read-only behavior, limitations, and an alternative tool. The main gap is that the raio parameter is absent from the narrative description, leaving its relationship to the mesoregion-based behavior unexplained.

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 input schema already explains each parameter, including the 7-digit code and the requirement for uf when using a municipality name. The description adds useful examples but no deeper semantic detail beyond the schema, and it never mentions the raio parameter even though it is part of 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 opens with a clear verb and resource: 'Finds nearby/neighboring municipalities.' It further clarifies the exact mechanism (same mesoregion as a proximity proxy) and differentiates itself from ibge_municipios by stating that listing/searching municipalities should use that sibling tool.

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

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

The description provides explicit routing guidance: 'For listing/searching municipalities, use ibge_municipios' and notes that exact spatial neighborhood would require mesh processing. It also gives concrete examples for code-based, name-based, and population-included calls. It does not explicitly enumerate all alternative tools, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable behavior beyond these: returns at most 10 results, empty list means no match, relevance ordering, language handling, caching, and the linkage to fetch. This contextual information helps the agent anticipate outcomes and error cases.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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