IBGE Brasil MCP

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

Annotations already declare read-only, idempotent, and non-destructive. Description confirms these and adds return format (Markdown list) and API source. 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 clear sections: Features, Event types, Examples, Use other tool, Behavior. Each sentence is purposeful and concise, 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 parameters (none required), high schema coverage, annotations, and output schema presence, the description covers purpose, usage, behavior, examples, and alternatives thoroughly.

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. The description adds value through concrete examples and English translations for enum values (e.g., 'divulgacao' → 'publications'), making parameters more understandable.

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 queries the IBGE release and collection calendar, listing specific features and event types. It distinguishes from sibling ibge_noticias, which handles already-published news.

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 guidance through examples (upcoming releases, filtering by product/period, event types). Explicitly states when to use a different tool: for already-published news → ibge_noticias.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds that it is a live GET against the public IBGE SIDRA API and returns both Markdown and structuredContent, which goes 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 clear sections: purpose, years, themes, examples, alternatives, behavior. Front-loaded with the main purpose. Every sentence adds value with 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 the tool's complexity (6 parameters, many enums, no required params), the description is fully complete. It covers all parameters through examples, lists themes extensively, and mentions output format (Markdown + structuredContent).

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 detailed enum descriptions. The description adds value with usage examples (e.g., historical series with 'todos', listing tables with 'listar') and explains the 'campos' parameter to reduce response volume.

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 queries IBGE Demographic Census data (1970-2022) and lists available years and themes. It distinguishes from siblings by providing specific alternatives (ibge_populacao, ibge_cidades, 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?

Explicitly provides when to use this tool (census data) and when to use other tools (current population, municipality panels, comparisons, arbitrary SIDRA tables). Includes concrete examples of valid inputs.

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 adds behavioral context beyond annotations: specifies it is a live GET against public IBGE APIs, returns Markdown plus typed structured content. Annotations already declare readOnly, idempotent, and non-destructive, and description reinforces 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 concise (short paragraphs, bullet points, and examples), well-structured with clear sections, and front-loaded with the main purpose. Every sentence provides 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?

Given tool complexity (5 parameters, multiple query types), description completely covers functionality: available indicators, example uses, return format, and relationship to siblings. Output schema exists, so no need to detail return fields.

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. Description adds value by listing available indicator names (populacao, area, etc.) and providing concrete examples showing parameter combinations, though schema already documents each parameter well.

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 queries municipal indicators from IBGE's Cidades@ portal, lists specific features (panorama, historical, surveys), and provides examples. It distinguishes itself from 4 sibling tools by name and use case.

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 this tool (single municipality panel) and when not to, listing 4 alternative tools (ibge_populacao, ibge_censo, ibge_comparar, ibge_indicadores) with specific scenarios.

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, and performs a live GET against the IBGE API, returning Markdown. This adds valuable behavioral context beyond the annotations, which already mark readOnlyHint and idempotentHint. 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 clear sections (purpose, hierarchy, features, examples, behavior). It is slightly verbose but each sentence adds information; front-loaded with the main verb. Could be trimmed slightly without losing clarity.

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 (hierarchical classification, multiple search modes), the description covers all necessary aspects: what it does, structure, search features, examples, and behavior. Output schema exists to handle return details, so description is appropriately 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?

The input schema already provides thorough descriptions for all 4 parameters (100% coverage). The tool description adds value by including concrete usage examples (e.g., busca='software'), which help the agent understand typical usage patterns 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 it queries CNAE from IBGE, explains the hierarchical structure, and lists specific search features. The tool name itself indicates the domain, and the description distinguishes it from sibling IBGE tools by focusing on economic classification.

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 usage context through examples and feature list, but does not explicitly compare with sibling tools. However, the domain-specific name and unique features (CNAE hierarchy) make the intended use obvious.

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 that it's a live GET against IBGE APIs and returns Markdown plus structuredContent payload, providing 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?

Well-structured with bullet points and examples. While detailed, all information is relevant and front-loaded; minor redundancy with schema descriptions.

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

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

Thorough coverage: purpose, alternatives, behavior, parameter semantics, output format, and examples. Output schema exists, so return values are handled.

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. Description further adds examples, constraints (max 10 localities), and indicator list context, surpassing the baseline 3.

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

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

Clear verb 'compares' and resource 'localities data' with specific scope (municipalities/states). Distinguishes from siblings like ibge_cidades (single locality) and 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?

Explicitly states 'Use this tool ONLY to rank/compare 2–10 localities on one indicator' and lists alternatives for single locality queries (ibge_cidades, ibge_censo, ibge_sidra).

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds context: 'read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.' 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?

Well-structured with sections, bullet points, and examples. Each part earns its place—no waste. Front-loaded with purpose and key indicators.

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, many indicators, territorial levels, output schema exists), the description is thorough: covers data source, indicator list, territorial codes, behavioral notes, and output format. Nothing essential is missing.

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

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

Schema coverage is 100% (baseline 3). The description adds value by providing examples of parameter usage (e.g., indicador='mortalidade_infantil', nivel_territorial='3', localidade='35') and explaining territorial level codes. This goes beyond the schema's parameter 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 Brazil health indicators via IBGE's SIDRA, listing specific indicators and territorial levels. It differentiates from sibling tools like ibge_cidades, ibge_censo, and ibge_sidra by explaining when to use them 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?

Provides explicit guidance on when to use alternative tools: for a single municipality's general panel (ibge_cidades) and for population/demographic counts (ibge_censo or ibge_sidra). Also includes examples of parameter usage.

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?

Discloses read-only, idempotent nature, and that it performs a live GET against the public IBGE API. Annotations already provide readOnlyHint, idempotentHint, etc., but description adds implementation detail and return format (Markdown table), adding 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?

Extremely concise: three short paragraphs plus bullet features and examples. No wasted words. Information is front-loaded with the main purpose in the first sentence. Examples are compact and informative.

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 (2 optional parameters, no required ones, 100% schema coverage), the description is fully complete. It covers purpose, parameters, behavior, output format, and distinguishes from siblings. Output schema exists but description adds that returns are Markdown table, which is sufficient.

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% (both parameters described in schema). Description enriches with concrete examples (e.g., regiao='NE', ordenar='sigla'), showing how to use each parameter effectively beyond the schema's enum lists.

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 'Lists all Brazilian states from IBGE' with specific verb and resource. It distinguishes from sibling tools by explicitly naming alternatives (ibge_municipios, ibge_localidade) for related but different 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?

Provides clear guidance on when to use this tool (list states) and when to use others, with explicit 'Use a different tool when' section. Includes parameter usage examples for filtering and sorting.

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 valuable context: 'read-only and idempotent — a live GET against the public IBGE Localidades API. Returns Markdown.' This confirms and elaborates 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?

The description is well-structured with bullet points and sections, front-loading the main purpose. It is concise enough given the complexity, though slightly lengthy; each 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?

The description covers all necessary aspects: purpose, parameters with examples, code structure, behavior, return format (Markdown), and alternatives. Given the tool's complexity and the presence of an output schema, it is fully 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?

Input schema covers all parameters with descriptions (100% coverage). The description goes further by explaining code structure and providing detailed examples, adding meaning 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 the tool's purpose: decoding IBGE codes and searching codes by locality name. It lists distinct features and explicitly distinguishes from sibling tools (ibge_municipios, ibge_localidade), making it easy for an agent to select the right 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 guidance on when to use this tool vs alternatives, with named siblings and specific use cases (e.g., 'Only need to list/search municipalities → ibge_municipios'). Examples further clarify usage contexts.

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. The description adds that it is a read-only, idempotent live GET against the public IBGE SIDRA API, and returns Markdown plus a typed structuredContent payload. This enriches 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 bullet points for indicator categories and examples. Concise yet comprehensive, with front-loaded purpose and clear formatting.

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, none required, and an output schema, the description provides a complete overview: purpose, available indicators, usage examples, behavior, and alternatives. 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 covers 100% of parameters with descriptions. The description lists available indicator names and usage examples but does not significantly add to parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it queries IBGE economic and social indicators, listing specific categories and indicators. It distinguishes from siblings by naming alternative tools for different use cases (ibge_comparar, ibge_censo, 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 localities → ibge_comparar, census themes → ibge_censo, municipal panel → ibge_cidades. Includes examples of typical queries (GDP, IPCA, unemployment).

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 that the tool is read-only and idempotent, which aligns with the annotations. It also adds context beyond annotations by mentioning it is a 'live GET against the public IBGE Localidades API' and that it 'returns a Markdown record,' providing additional behavioral detail.

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, well-structured with bullet points for features and examples, and front-loaded with the primary purpose. Every sentence adds value, with no redundant or unnecessary 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 presence of an output schema, the description adequately covers all necessary aspects: purpose, usage conditions, behavioral traits, output format (Markdown record), and examples. It is complete for the tool's complexity.

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 providing concrete examples of code values (e.g., 35 for São Paulo state) that illustrate the parameter usage, helping to clarify the meaning 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 that the tool returns details of a specific locality by IBGE code, using a specific verb ('returns') and resource ('locality'). It distinguishes from sibling tools by explicitly mentioning alternatives for other use cases (e.g., ibge_municipios, ibge_geocodigo).

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 guidance on when to use this tool (when you already have the code for one locality) and when not to use it (when you have a name and need the code, or want to decompose a code's structure), with direct references to alternative 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, openWorldHint, idempotentHint, destructiveHint. Description adds explicit confirmation of read-only, idempotent behavior and states it returns the mesh in requested format. 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 sections, bullet points, and examples. Front-loaded with purpose. Some minor redundancy (formats listed twice) 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?

For a tool with 6 parameters, 4 enums, and IBGE domain, the description covers locality types, resolution, quality, format, and usage guidance. Includes examples and alternatives. Output schema handles return values.

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 all 6 parameters. Description adds meaning beyond schema by explaining locality types (e.g., 'BR', 'SP', '35') and resolution values (0=outline, 2=states, 5=municipalities) with examples.

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 'Gets geographic meshes (maps) from IBGE' and lists specific resources (Brazil, regions, states, municipalities) and formats. It distinguishes from sibling tool ibge_malhas_tema for thematic meshes.

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 says when to use this tool and when to use ibge_malhas_tema instead. Provides examples for different locality types and resolutions, guiding agent 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 readOnlyHint and idempotentHint. Description adds that it's a live GET against the public API and returns the mesh in requested formats, which is consistent but not extensive 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 themes, codes, and examples. Slightly verbose but front-loaded with purpose. Each sentence contributes meaning, though could be trimmed slightly.

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 output schema exists, description does not need to explain return values. Covers all parameters, theme options, disambiguation from siblings, and behavioral context. Complete for a complex thematic mesh 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 has 100% coverage with descriptions for each parameter. Description adds value by providing examples, biome code mappings, and usage patterns (e.g., codigo='1' for Amazon biome), enhancing parameter understanding 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 it gets thematic geographic meshes from IBGE and lists specific themes. It distinguishes from sibling ibge_malhas for administrative meshes.

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 'Use a different tool when' and directs to ibge_malhas for administrative meshes. Provides examples for various themes and parameters, guiding appropriate usage.

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, destructiveHint=false. The description adds that it 'is a live GET against the public IBGE Localidades API' and confirms 'read-only and idempotent', but does not go beyond what annotations imply. The mention of returning a Markdown table is a useful extra.

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 initial statement, bulleted features, examples, and a dedicated 'Use a different tool when' section. It is concise with no superfluous text, earning its place in every sentence.

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 3 parameters with full schema coverage, no required parameters, rich annotations, and an output schema is present (implying structured return). The description covers all key aspects: purpose, usage, parameter examples, behavioral notes, and alternatives, making it fully complete 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 coverage is 100%, so baseline is 3. The description provides examples (uf='SP', busca='Campinas') that illustrate usage but does not add new meaning beyond the schema's parameter descriptions. It mentions default and max for 'limite', but those are already 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 starts with 'Lists Brazilian municipalities from IBGE' and lists specific features (by state, all, search, returns 7-digit code), clearly distinguishing from sibling tools by naming ibge_geocodigo, ibge_localidade, and ibge_vizinhos for different purposes.

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: 'Use a different tool when: Resolve/decode a code... → ibge_geocodigo; Full details/hierarchy... → ibge_localidade; Neighboring municipalities → ibge_vizinhos'. Also provides concrete examples for parameter combinations.

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 that it is a live GET against the public IBGE API and returns a Markdown table, enhancing transparency 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 sections, bullet points, and examples. It is concise, with every sentence adding value, and front-loads the core purpose.

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, an output schema, and moderate complexity, the description covers all modes, parameters, examples, and behavior. It is complete and self-contained.

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%. The description adds context by explaining parameter usage (e.g., nomes for frequency, decada for ranking) and provides examples that clarify combinations, adding value over 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 it queries name frequency and rankings in Brazil (IBGE). It distinguishes itself from sibling tools by focusing specifically on names, with explicit features for frequency and ranking.

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 examples of when to use each tipo (frequency vs ranking) and includes filter parameters. However, it does not explicitly mention when not to use this tool compared to siblings, though the context makes it 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 and idempotentHint. Description adds 'live GET' and 'Returns a Markdown list', reinforcing non-destructive behavior with implementation detail.

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

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

Front-loaded purpose sentence, followed by usage context, parameter details with examples, sibling distinction, and behavioral note. Every sentence is purposeful and well-organized.

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

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

For a tool with 7 params, full schema coverage, output schema, and rich annotations, the description covers all necessary context: purpose, parameters, return structure, behavior, and alternatives.

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 coverage, description still adds substantial value: explains each parameter in plain language, provides examples, default values, and date format (DD/MM/AAAA) not in 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?

Starts with specific verb 'Searches and lists' and resource 'already-published IBGE news articles and press releases', clearly distinguishing from siblings via explicit cross-reference to ibge_calendario.

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 ('find recent IBGE publications... when an indicator was released') and when to use ibge_calendario for scheduled/upcoming dates, providing a concrete 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it is a live GET against the public IBGE Países API and returns Markdown, 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. Every sentence earns its place, providing essential 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?

Given the presence of an output schema and the tool's relative simplicity (no required params, few enums), the description covers all necessary context: features, usage patterns, and behavior. No gaps identified.

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?

Despite 100% schema coverage, the description adds considerable value by explaining the meaning of 'tipo' values, showing examples of each, clarifying regional filters, and specifying country code formats (ISO-ALPHA-2).

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 international country data via IBGE, listing specific features like listing all countries, getting details, searching by name, and filtering by region. It uniquely identifies this tool among many IBGE siblings by focusing on countries.

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 query types (listar, detalhes, buscar) and usage of parameters like regiao and pais. However, it does not explicitly state when not to use it or compare to sibling tools, leaving some 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, etc. Description adds behavioral context: 'live GET against the public IBGE SIDRA/Pesquisas API' and 'Returns a Markdown list.' Does not contradict annotations, but adds only modest extra detail beyond what annotations convey.

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

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

Well-structured with sections (Features, Main surveys, Examples, etc.). Information is front-loaded with main purpose. Every sentence contributes value, though slightly longer than minimal; but justified by clarity.

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 rich annotations and output schema (implied), the description covers purpose, usage, behavior, parameter examples, and sibling differentiation. It also clarifies scope (lists only, not data). Complete for its complexity.

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 both parameters with descriptions (100% coverage). Description adds usage examples (busca='população', detalhes='pnad') that clarify how to use parameters, adding value beyond schema baseline. No further parameter details needed.

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 IBGE surveys and their tables, with specific verb 'lists' and resource 'IBGE surveys'. It distinguishes from siblings by noting it does not provide data, directing to ibge_sidra_tabelas and ibge_sidra for that.

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?

Includes explicit when to use: list surveys, search, get details. States what not to use for: 'This lists surveys, not data.' Names alternative tools: ibge_sidra_tabelas, ibge_sidra, and wrappers. Provides examples 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, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds useful context: it's a live GET against the public IBGE API, and returns Markdown plus structuredContent. This enriches the behavioral profile 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 and clear sections, but it is slightly verbose (e.g., repeats that the tool is for Brazil's national projection). Still, it is easy to parse and front-loads key 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's simplicity (single enum parameter) and presence of an output schema, the description covers all necessary context: what it returns, source, behavior, and when to use alternatives. No gaps remain.

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

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

Schema coverage is 100% with a single parameter (localidade) that has an enum and default. The description does not add new parameter meaning, but the schema itself fully documents the parameter. Baseline score of 3 is appropriate.

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

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

The description explicitly states the tool returns a 'real-time Brazilian population projection' with specific features (current estimate, birth/death rates, daily increment). It distinguishes itself from siblings by listing alternative tools for other population queries, providing excellent purpose clarity.

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 when-to-use guidance: for Brazil's national projection only. It explicitly lists alternative tools for specific use cases (e.g., ibge_cidades for municipalities, ibge_censo for census data), making it easy for an agent to decide.

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 API and returns Markdown plus structuredContent. No contradictions; adds 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?

Well-organized with clear sections (common tables, territorial levels, examples, sibling tool comparison, behavior). Front-loaded with purpose and concrete data. Only slightly verbose due to thoroughness, but each 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?

Complex tool (9 params, 1 required) with rich sibling set. Description provides comprehensive examples, usage guidance, and behavioral notes. Output schema exists, so return format is covered. Could mention rate limits or pagination limits, but overall 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 description coverage is 100%, so baseline is 3. The description adds example usage (e.g., 'tabela="6579", periodos="2023"') and clarifies territorial level codes, but these are already well covered in the schema descriptions. No significant extra semantic depth.

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 SIDRA tables from IBGE, provides common table codes and territorial levels, and includes examples. It effectively distinguishes itself from sibling tools by naming alternatives like ibge_censo and ibge_indicadores.

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

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

Explicitly advises when to prefer friendlier wrappers (e.g., 'Prefer a friendlier wrapper when it fits') and recommends using ibge_sidra_tabelas and ibge_sidra_metadados to find table codes first. Provides clear context for this tool as the low-level engine.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint. The description adds that it is 'read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown.' This confirms and enriches the behavioral profile 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?

Well-structured with bullet points for features, followed by usage guidance, examples, and a behavioral note. The main purpose is front-loaded. Slightly verbose but still efficient; each 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 that annotations and output schema are available, the description covers the tool's purpose, usage context, and behavioral traits adequately. It notes the return format (Markdown) and the workflow order, making it complete for its complexity.

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 clear parameter descriptions. The tool description mentions features like 'Available territorial levels' and 'Available periods' but does not significantly add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it returns metadata for a specific SIDRA table and lists specific features (general info, territorial levels, variables, classifications, periods). It also explicitly distinguishes from sibling tools ibge_sidra and ibge_sidra_tabelas by stating when to use it relative to them.

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: 'Use this tool to understand table structure BEFORE querying data with ibge_sidra' and 'Use this after finding a table code (ibge_sidra_tabelas)'. Also gives concrete examples of table codes, making it easy for the agent to apply.

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, idempotent, and non-destructive. The description adds that it is a 'live GET against the public IBGE SIDRA API' and 'Returns a Markdown table,' which enriches transparency beyond 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 concisely structured with bullet points, a list of surveys, examples, and workflow steps. It front-loads the main purpose and every sentence serves a clear role, avoiding verbosity.

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 (3 optional parameters, 100% schema coverage, output schema exists), the description fully covers purpose, usage, parameters, behavior, and workflow. It also mentions return format, meeting all informational needs.

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 by providing concrete examples: 'List tables: (no parameters)', 'Search population tables: busca="população"', and 'Census tables: pesquisa="censo"', helping users understand 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 clearly states it 'Lists and searches available SIDRA tables' and lists specific features like listing, searching by name, and filtering by survey. It distinguishes itself from sibling tools by positioning this as step 1 of the SIDRA workflow and noting wrapper tools for common data.

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 outlines the SIDRA workflow: 'find a table code → ibge_sidra_metadados (structure) → ibge_sidra (query).' It also advises that wrappers like ibge_censo, ibge_indicadores, etc., are easier for common data, providing clear when-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?

Discloses read-only, idempotent nature, API source (IBGE Localidades API), output format (Markdown list), and approximation method. Adds value beyond annotations by concretely describing behavior.

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

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

Well-structured with summary, features, notes, examples, and behavioral note. Slightly verbose but every sentence adds value; could be condensed slightly.

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 full schema, output schema, and annotations, description is complete: explains approximation, alternative, parameters, 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?

100% schema coverage; description adds examples, explains optional uf dependency when using name, and clarifies code vs name usage. Adds meaning 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 'Finds nearby/neighboring municipalities' with specific verb and resource. Distinguishes from sibling ibge_municipios by explicitly directing listing/searching to that 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?

Includes explicit alternative (ibge_municipios), notes limitations (mesoregion proxy vs exact adjacency), and provides examples for different parameter combinations.

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