IBGE Brasil MCP

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint false. The description adds that it is a live GET against the public API and returns a Markdown list, adding behavioral context beyond annotations.

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

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

Well-structured with sections: features, event types, examples, alternative tool. Front-loaded with clear purpose. Every sentence adds value; no redundancy.

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 6 optional parameters, full schema coverage, output schema present, strong annotations, the description covers all necessary aspects: purpose, usage, behavior, parameters, and alternatives. Complete for an AI agent.

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% with parameter descriptions. The description adds concrete examples (e.g., produto="IPCA", de="01/01/2024") and explains the tipo parameter with its enums, enhancing understanding beyond 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 clearly states it queries IBGE release and collection calendar, with specific verbs and resource. It distinguishes event types (release vs. collection) and provides examples. Differentiation from sibling ibge_noticias is 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?

Explicitly states when to use a different tool (ibge_noticias for already-published news). Examples cover common use cases, and the description implies usage for upcoming releases and field collections.

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?

Description states 'read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.' This adds details about the API call and return format beyond annotations that already mark readOnlyHint, idempotentHint, and destructiveHint false. 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 front-loaded with the core purpose, followed by bullet lists of years and themes, then examples, then usage alternatives. Every sentence adds value, and the structure is clear 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 tool has 6 parameters with no required fields, high schema coverage, and an output schema. The description covers purpose, usage guidelines, behavioral transparency, examples, and alternatives. It is fully adequate for an AI agent to understand when and how to use the tool.

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 description is not required to add parameter meaning, but it includes useful examples like 'Population 2022: ano="2022", tema="populacao"' and 'Literacy 2010 by state: ano="2010", tema="alfabetizacao", nivel_territorial="3"'. These examples enhance understanding, earning a 4.

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 the tool queries IBGE Demographic Census data from 1970-2022, simplifies access without needing SIDRA table codes, and lists available years and themes. It clearly distinguishes from siblings like ibge_sidra which require arbitrary SIDRA tables.

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 lists when to use a different tool: for real-time population (ibge_populacao), one municipality's panel (ibge_cidades), comparing localities (ibge_comparar), or arbitrary SIDRA tables (ibge_sidra). Provides clear context for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it is a live GET against public IBGE APIs and returns Markdown with typed structuredContent. This context beyond annotations earns a 4, though no contradictions.

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

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

The description is well-structured with bullet points, examples, and a behavior section. Every sentence adds value, no redundancy. Front-loaded with purpose and alternatives.

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 (multiple tipos, many indicators), the description covers all key aspects: features, examples, sibling differentiation, behavior, and return format. Output schema exists, so return details are covered.

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 lists available indicators and provides usage examples that clarify parameter combinations, but does not add significant detail beyond the 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 clearly states it queries municipal indicators from IBGE's Cidades@ portal, lists features, and provides examples. It distinguishes itself from sibling tools by explicitly naming alternative tools for different queries (e.g., real-time population, census themes, multi-municipality comparison).

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 states when to use this tool (single municipality queries) and when to use other tools (ibge_populacao, ibge_censo, etc.). It provides concrete examples for different tipos, making usage clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by specifying it performs a live GET against the public IBGE CNAE API and returns Markdown. It also restates idempotent behavior, but that is consistent 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 well-structured with clear sections (definition, hierarchy, features, examples, behavior) and front-loaded purpose. While it is relatively long, every sentence is informative. Minor redundancy could be trimmed (e.g., repeating 'idempotent' already in annotations), but overall efficient.

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

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

Given the tool has 4 parameters (none required), full schema coverage, output schema present, and rich annotations, the description sufficiently covers hierarchy explanation, usage patterns, result format, and behavior. No gaps remain for effective use.

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 description goes well beyond the schema by explaining the hierarchical levels (section, division, etc.), providing multiple examples for each parameter, and clarifying default behavior (e.g., nivel defaults to showing all relevant levels). This adds substantial meaning for correct parameter usage.

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

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

The description explicitly states that the tool queries CNAE (National Classification of Economic Activities) from IBGE, explains what CNAE is, and lists key features. This clearly differentiates it from sibling tools like ibge_calendario or ibge_sidra, which deal with different data domains.

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 usage examples for different parameters (e.g., busca, codigo, nivel) but does not explicitly state when to use this tool over alternatives or when not to use it. The context of sibling tools implies each IBGE tool is domain-specific, but no direct comparison or exclusion guidance is given.

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, idempotentHint, and destructiveHint. The description adds behavioral context: 'read-only and idempotent — a live GET against the public IBGE APIs (SIDRA and Localidades). Returns Markdown plus a typed structuredContent payload.' This enriches the annotations with implementation details and no contradictions.

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

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

The description is well-organized with sections, bullet points, and examples. Every sentence adds value, and it is front-loaded with core purpose and features. No wasted words.

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 complexity (multi-locality comparison, multiple indicators, output formats) and the presence of an output schema, the description covers all necessary aspects: constraints, features, examples, and behavioral traits. It is complete for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing usage examples, clarifying code formats (7-digit municipality codes, 2-digit state codes), and listing indicators with examples. This contextualization justifies a 4.

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 (municipalities or states) and lists available indicators. It distinguishes from sibling tools by explicitly directing users to other tools for single locality queries, e.g., 'For a single locality, use ibge_cidades, ibge_censo, 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?

The description provides explicit when-to-use ('Compare up to 10 localities at once') and when-not-to-use guidance ('For a single locality, use...'). It also specifies constraints like maximum number of localities and input code formats.

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. Description adds that it is a live GET returning Markdown and structuredContent, which adds value 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?

Description is well-organized with sections and bullet points, front-loaded with purpose, and provides examples; while somewhat lengthy, it earns 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?

Covers all relevant aspects: indicator list, territorial levels, examples, sibling differentiation, and output format. Given the tool's complexity, the description is complete.

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%, but description adds extra context by listing indicator options and territorial level codes (1,2,3,6) with examples, enhancing understanding.

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 it queries Brazil health indicators via IBGE's SIDRA, lists specific indicators, and distinguishes from sibling tools like ibge_cidades and ibge_censo by specifying when to use alternatives.

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 guidance on when to use other tools (ibge_cidades, ibge_censo, ibge_sidra) and includes examples for different indicators and territorial levels.

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. The description adds context: it is a live GET against the public IBGE Localidades API and returns a Markdown table. This goes beyond the annotations without contradicting them.

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 concise and well-structured: a one-line summary, followed by bulleted features and examples, and ends with alternative usage. Every sentence adds value, and the structure facilitates quick scanning.

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 0 required parameters and an output schema (not shown but implied), the description covers filtering, sorting, result format (Markdown table), and distinguishes from related tools. It is fully sufficient for correct tool selection and use.

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 both parameters. The description reinforces the enum values for region (e.g., 'N' for North) and sort field, and provides examples. This adds marginal value but not significantly 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 description clearly states 'Lists all Brazilian states from IBGE.' It specifies the verb (list) and resource (Brazilian states), and distinguishes from siblings like ibge_municipios and ibge_localidade by naming them 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?

The description provides explicit when-to-use guidance: 'List all states' with optional filtering and sorting. It also states when not to use: for municipalities or locality details, use specific alternative tools. Examples are provided for common use cases.

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, destructiveHint=false. Description adds 'Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns Markdown.' This confirms and expands on the annotations without 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?

Description is well-organized with clear sections (features, code structure, examples, usage guidance). Every sentence adds value, and it is appropriately concise for 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?

Given the tool's multiple capabilities (decode, search, hierarchy), the description covers all use cases, includes examples, mentions output format (Markdown), and references an output schema exists. No gaps.

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%, but description adds significant value: examples for each parameter, code structure explanation, and context on how parameters relate (e.g., nome with uf). This 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?

Description explicitly states 'Decodes IBGE codes or searches codes by locality name' and lists features like decode region/state/municipality/district, search by name, etc. It clearly distinguishes from siblings by naming ibge_municipios and ibge_localidade as alternatives.

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?

Description directly tells when to use a different tool: for listing/searching municipalities use ibge_municipios, for full detailed record of one locality use ibge_localidade. This provides clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by noting it's a live GET against the public IBGE SIDRA API and returns Markdown plus typed structuredContent. No contradictions.

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

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

Well-structured with categories, examples, and usage guidelines. Every sentence adds value, no redundancy.

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 7 parameters and many indicators, the description is complete: covers all indicator categories, provides examples, and references other tools. Output schema exists so return values are handled elsewhere.

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% with each parameter having a description. The description adds an explicit list of indicator names and examples, which adds some value beyond the schema. However, it does not provide deep semantic detail for each parameter beyond what's 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 clearly states it queries IBGE economic and social indicators, listing available indicators by category. It differentiates from siblings by specifying when to use other tools like ibge_comparar, ibge_censo, and ibge_cidades.

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

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

Explicitly states when to use alternative tools ('Comparing/ranking localities → ibge_comparar', 'Census themes → ibge_censo', 'One municipality's panel → ibge_cidades') and provides usage examples.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it's a live GET against the public IBGE Localidades API and returns a Markdown record, which provides useful context beyond annotations.

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

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

The description is concise and well-structured with bullet points and examples. It front-loads the main purpose and provides clear, actionable information without wasted words.

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 low complexity (2 parameters, output schema exists), the description is complete. It covers what the tool does, when to use it, parameter semantics, and the output format (Markdown record).

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%, but the description adds examples and explains that the 'tipo' parameter can be inferred from code length if not provided, which adds meaning beyond 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 clearly states the tool returns details of a specific locality by IBGE code, with examples of codes at different levels and mention of hierarchy. It distinguishes from sibling tools by specifying when to use ibge_municipios or ibge_geocodigo instead.

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 provides guidance on when not to use this tool: when you have a name and need a code, or need to decompose a code's structure. It names specific alternative tools, which helps an agent select the correct 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 read-only and idempotent; the description adds that it's a live GET request, confirming and extending transparency without 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?

Well-structured, front-loaded, with clear sections; slightly verbose but every part adds value.

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 (6 params, 1 required, no output schema), the description covers usage, parameters, examples, and alternatives adequately.

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?

Adds meaning beyond the schema by explaining locality types, resolution values, and providing examples, even though schema coverage is 100%.

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 fetches geographic meshes from IBGE in three formats, distinguishes from sibling ibge_malhas_tema, and specifies the resource types.

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 alternative for thematic meshes (ibge_malhas_tema) and includes usage examples, but does not list all cases when not to use.

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, etc. The description adds that it's a 'live GET against the public IBGE Malhas API' and mentions return formats, which enriches understanding without contradicting annotations.

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

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

The description is well-structured with clear sections for themes, codes, examples, and differentiation. While slightly long, every sentence adds value and it's efficiently 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?

For a tool with 5 parameters and 4 enums, the description covers all necessary context: themes, codes, example invocations, differentiation from sibling, behavior, and return format. Output schema exists, so no need to detail return structure.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value with examples, biome code mappings, and usage patterns (e.g., 'tema="listar"') that go beyond the enum definitions.

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 it 'gets thematic geographic meshes from IBGE', listing all available themes and providing a clear contrast with the sibling tool ibge_malhas for administrative meshes. The verb 'gets' and resource specification are precise.

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 a different tool: 'Administrative meshes... → ibge_malhas'. This provides clear usage context by naming an alternative.

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, idempotentHint, destructiveHint. Description adds that it is a live GET against a public API and returns a Markdown table, which complements but does not contradict 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?

Highly efficient: front-loaded purpose, structured bullet features, clear examples, and no extraneous words. Every sentence adds value.

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 3 parameters, full schema coverage, rich annotations, and existence of output schema, the description covers all necessary context: purpose, filtering, limits, behavior, return format, and when to use other 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% with descriptions for all 3 parameters. Description adds contextual examples and clarifies usage (e.g., uf can be abbreviation, name, or code) beyond 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?

Description clearly states it lists Brazilian municipalities, enumerates features (by state, search, all), includes IBGE code, and distinguishes from siblings by naming specific alternative tools for other tasks.

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 provides when-to-use guidance with examples (uf, busca) and lists specific alternatives (ibge_geocodigo, ibge_localidade, ibge_vizinhos) for different 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?

The description adds behavioral context beyond annotations: it states read-only and idempotent behavior, that it performs a live GET against the public IBGE API, and returns a Markdown table. These details complement the annotations (readOnlyHint, idempotentHint) without 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 sections, bullet points, and examples. It is concise, front-loaded, and every sentence serves a purpose. No wasted words or redundant 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?

Given the tool has 6 parameters (1 required) and a complex output (Markdown table from IBGE API), the description covers both modes, all filtering options, and provides concrete examples. It is complete enough for an agent to understand when and how to use 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 schema already describes all parameters with 100% coverage. The description adds value through examples that illustrate how parameters like 'nomes', 'decada', 'limite', and 'localidade' are used in context. This helps clarify their role beyond the schema definitions.

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 it queries name frequency and rankings in Brazil (IBGE). It distinguishes two modes: 'frequencia' for specific names and 'ranking' for most popular. This is a specific verb+resource with clear differentiation from other 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 description provides explicit examples for different scenarios (frequency, ranking) and explains filtering by sex, decade, and locality. It mentions available decades (1930-2010) and demonstrates parameter combinations. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds further context: 'Behavior: read-only and idempotent — a live GET against the public IBGE Notícias API. Returns a Markdown list.' This extends beyond annotations with API details and return 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-structured: purpose, usage guidelines, parameter details, return format, examples, and alternatives. It is front-loaded with the main action. While it is thorough, it is slightly verbose in the parameter listing section, which could be more concise, but overall it is 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?

Given the tool has 7 parameters, 0 required, and an output schema exists, the description covers all necessary aspects: when to use, parameter details with examples, return format, behavioral traits, and alternative tools. It is complete and leaves no significant gaps.

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. However, the description provides extensive additional meaning: it explains each parameter in plain language, gives date format examples, describes the meaning of 'tipo' values, and provides usage examples. This goes far beyond the schema's property 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 clearly states that the tool 'Searches and lists already-published IBGE news articles and press releases.' This is a specific verb+resource combination, and it differentiates from sibling tool ibge_calendario by explicitly noting the alternative for scheduled dates.

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 states when to use the tool ('find recent IBGE publications or announcements about a survey or topic') and provides a clear alternative: 'Use a different tool when: Scheduled/upcoming release dates (not yet published) → ibge_calendario'. This is direct 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 indicate read-only and idempotent behavior; the description confirms these traits and adds 'live GET against the public IBGE Países API' and 'Returns Markdown.', which provides additional context 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 bullet points and examples, front-loaded with the main purpose, and every sentence adds useful information without redundancy.

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 covers the main usage modes (list, details, search, indicators) and required codes; it is comprehensive enough for the tool's complexity, though could mention pagination or rate limits if applicable.

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%, but the description adds value by including examples, listing valid region values, and explaining how to use the 'indicadores' parameter with pipe-separated IDs.

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 'Queries international country data via IBGE.' and lists specific features like listing all countries, details, search, and filter, differentiating it from sibling tools which cover other IBGE domains.

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 different 'tipo' values, filter options, and valid region list, but does not explicitly state when to avoid this tool in favor of siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by stating 'Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA/Pesquisas API. Returns a Markdown list.' This reinforces behavioral traits and adds details about the API source and return format, complementing annotations without 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 clear sections: main purpose, features, list of main surveys, examples, and usage guidance. It is concise, front-loaded with the primary function, and every sentence adds value without redundancy.

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 (many siblings, rich annotations, and output schema), the description covers all necessary aspects: purpose, usage boundaries, behavior, parameter semantics via examples, and links to alternative tools. It fully equips an agent to understand when and how to use this tool.

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 both parameters documented. The description adds practical value by providing examples (e.g., 'busca="população"', 'detalhes="pnad"') and explaining their usage context ('Search by name or code', 'Show details and tables of a specific survey'). This goes beyond the schema's minimal 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 clearly states it lists available IBGE surveys and tables, with features and examples. It distinguishes itself from siblings by explicitly stating it does not return data, directing users to ibge_sidra_tabelas for table codes and ibge_sidra for data queries, which differentiates its purpose effectively.

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 and when-not-to-use guidance: 'This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades).' This gives clear alternatives and context for correct tool 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 declare read-only, idempotent, non-destructive. The description adds that it is a live GET against a public API and returns Markdown plus structuredContent, providing valuable context beyond annotations.

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

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

Description is well-organized with bullet points and clear sections. It is informative yet concise, though a slight reduction in detail could improve conciseness.

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 simplicity (one parameter, no required params, output schema present), the description fully covers what an agent needs to know, including return format and source.

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% with one parameter and a clear description. The description does not add new parameter details beyond what the schema provides, 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?

The description clearly states the tool returns real-time Brazilian population projection and lists specific features. It distinguishes itself from sibling tools by specifying what it does NOT do and naming alternatives.

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 the tool only works for Brazil's national projection and provides a bulleted list of conditions for using alternative tools, leaving no ambiguity.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, openWorldHint. The description adds behavioral context: 'read-only and idempotent — a live GET against the public IBGE SIDRA API' and mentions return format (Markdown + typed structuredContent). No contradictions.

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

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

The description is well-structured with sections (intro, common tables, territorial levels, examples, sibling recommendations, behavior note). Every sentence adds value; no redundancy or fluff. Appropriately sized for a complex tool.

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 complexity (9 parameters, output schema exists), the description is complete: explains purpose, provides examples, lists common parameters, advises on exploration, and notes output format. The output schema covers return details, so no need for more.

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

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

Schema coverage is 100%, baseline 3. The description adds value by listing common table codes and territorial level numbers with examples, which helps parameter selection beyond schema descriptions. It also explains effects like 'reduz o volume da resposta' for campos.

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 explicitly states it queries SIDRA tables from IBGE, lists common tables and territorial levels, and provides examples. It clearly distinguishes itself from sibling tools by positioning itself as the low-level engine with alternatives like ibge_censo for specific themes.

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 by listing sibling tools (ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades) for specific cases and advises using ibge_sidra_tabelas/metadados to find table codes first. This helps agents select the right tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying 'a live GET against the public IBGE SIDRA API' and 'Returns Markdown,' providing operational context beyond annotations.

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

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

The description is well-structured with bullet points, examples, and a behavioral note. Every line adds value; it is brief yet comprehensive.

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 presence of an output schema, the description need not detail return values. It covers purpose, usage, examples, and behavior, providing complete guidance for an agent.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's feature list loosely maps to parameters but does not add significant semantic depth beyond the existing 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 explicitly states 'Returns metadata for a specific SIDRA table' and lists specific features (general info, territorial levels, variable list, classifications, periods). It clearly distinguishes from siblings by specifying its role as a precursor to 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?

Provides explicit usage guidance: 'Use this tool to understand table structure BEFORE querying data with ibge_sidra' and 'Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.' Clearly defines the workflow.

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 valuable context: it's a live GET against the public API, returns a Markdown table, and is idempotent. 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 sections (features, examples, workflow, behavior), but it is somewhat verbose. Each sentence adds value, but could be tightened slightly without losing 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?

Given the rich annotations and presence of output schema, the description is complete: covers purpose, parameters, workflow step, alternatives, and behavioral traits. It fully equips an agent to use 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% with clear parameter descriptions. The description adds meaning by explaining the role of each param (search by table name, filter by survey) and showing usage in examples. It does not deeply elaborate beyond schema but provides enough context.

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 lists and searches SIDRA tables, with explicit features (list all, search by name, filter by survey). It distinguishes from siblings by positioning as step 1 of the SIDRA workflow and noting simpler wrappers for common data (ibge_censo, etc.).

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 (first step in SIDRA workflow, find a table code) and when-not-to-use (for common data, use wrappers). Examples demonstrate typical queries, and the workflow chain is clearly outlined.

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 declare readOnlyHint=true and idempotentHint=true. Description adds 'read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown list', providing API source and return format. Consistent 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?

Well-structured with bullets and examples, but contains slight redundancy: the mesoregion approximation note appears twice. Still front-loaded and each sentence is useful.

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 4 parameters, full schema coverage, and output schema present, the description is comprehensive. Explains limitations, provides examples, and describes behavior and return format. No gaps.

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%. Description adds meaning: explains municipio accepts code or name, uf required for name, incluir_dados for population, and provides example usage. This goes beyond schema properties.

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?

Clearly states 'Finds nearby/neighboring municipalities' with specific verb and resource. Differentiates from sibling ibge_municipios by noting alternative use.

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 context with examples and notes on approximation. Directs to alternative tool for exact spatial neighborhood and for listing municipalities.

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