IBGE Brasil MCP

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it's a live GET against the public IBGE SIDRA API and returns Markdown plus typed structuredContent. This confirms behavior 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 a summary, bullet lists for indicators and territorial levels, and usage examples. It is concise yet comprehensive, front-loading 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's complexity (6 parameters, multiple indicators, territorial levels), the description covers purpose, parameters, examples, and sibling differentiation. Output schema exists, so return values need not be described in detail. 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 description coverage is 100%, so baseline is 3. The description adds overall context and examples, but parameter-level details are already well-covered in the schema. Some extra value from usage examples but not significant 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 the tool queries Brazil health indicators from IBGE's SIDRA/DataSUS. It lists specific indicators, territorial levels, and provides examples, making the purpose distinct from sibling tools like ibge_cidades or ibge_sidra.

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

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

Explicit 'Use a different tool when' section directs to ibge_cidades for general municipal panels and ibge_censo/ibge_sidra for population counts. Examples illustrate correct usage for various 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds the return format (Markdown list) and that it's a live GET API call, which provides additional behavioral 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?

Well-structured with a summary, feature list, event types, examples, alternative tool mention, and behavior note. No redundant sentences; each part earns its place.

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

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

Despite no output schema, the description explains the return format (Markdown list) and covers purpose, parameter usage, and behavioral traits. With 6 optional parameters, this is sufficient for an agent to use 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 descriptions in Portuguese. Description provides usage examples for parameters (produto, de/ate, tipo) but does not add substantive new meaning beyond what the schema already defines, meeting the baseline.

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

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

The description clearly states it queries the IBGE release and collection calendar, lists specific features like filtering by product and period, and distinguishes from sibling tool ibge_noticias by specifying when to use that 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 a when-not condition: 'Use a different tool when: Already-published news and releases → ibge_noticias'. Also gives multiple examples of usage scenarios (no parameters, IPCA filter, date range, 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?

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying it is a 'live GET against the public IBGE CNAE API' and 'Returns Markdown', which provides behavioral 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 for hierarchy, features, and examples. It is front-loaded with the main purpose and each section adds relevant information. While slightly verbose, it remains efficient and earns its length.

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, no output schema, and annotations covering safety, the description provides adequate context: explains the classification system, features, and return format (Markdown). Lacks details on error handling or empty results, but overall 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?

The input schema covers all parameters with 100% description coverage (baseline 3). The description enriches understanding with practical examples (e.g., busca='software', codigo='6201-5/01') and explains the hierarchical code structure, adding 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 the tool queries CNAE from IBGE, explains what CNAE is, and provides a detailed hierarchical structure. While it does not explicitly distinguish from sibling tools, the specific focus on economic activities makes the purpose unambiguous.

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

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

The description lists features (search by code, description, hierarchy level) and provides examples, implying when to use the tool. However, it does not provide explicit guidance on when not to use this tool or mention alternative sibling tools, leaving usage context somewhat implied.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it is a live GET against a public API and returns a Markdown table, which is useful but not extensive.

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 for features, examples, and alternatives. It is concise but includes a minor redundancy (listing 27 states twice).

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 no output schema, the description covers return format (Markdown table), all parameters are documented, and sibling tools are referenced. 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 coverage is 100% with clear enum descriptions. The description adds value by providing usage examples and listing enum values in plain text, aiding agent 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 lists all Brazilian states, specifies the count (27 states), and distinguishes from sibling tools by directing users to ibge_municipios for municipalities and ibge_localidade for locality details.

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 (no parameters, region filter, sort) and when-not-to-use by specifying alternative tools for municipalities and locality details.

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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description confirms with 'read-only and idempotent — a live GET against the public IBGE Localidades API. Returns Markdown.' No contradiction; adds context about API call 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 with clear sections (features, code structure, examples, alternatives). It is slightly verbose but every part adds value. Front-loads purpose and features.

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 (code decoding), full parameter schema, rich annotations, and no output schema, the description is thorough. It explains what the tool returns (Markdown) and covers all usage scenarios, making it 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% with parameter descriptions. The description adds significant meaning: explains code structure (1/2/7/9 digits), provides multiple examples for each parameter, and clarifies how parameters interact (e.g., using uf to restrict municipality search).

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 decodes IBGE codes or searches codes by locality name, lists features, explains code structure, and provides examples. It distinguishes from sibling tools ibge_municipios and ibge_localidade by specifying 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?

The description explicitly says 'Use a different tool when:' and lists two specific alternatives with their purposes. Examples show how to use parameters for different scenarios (decode code, search by name, restrict by UF).

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds specificity: 'live GET against public IBGE API' and 'returns Markdown record', providing richer behavioral context.

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

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

Well-structured with front-loaded purpose, features list, examples, usage guidelines, and behavior summary. 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?

Covers input, output (Markdown record), behavior, and use cases. No missing information given the tool's simplicity and presence of annotations.

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%. Description adds examples mapping codes to types and clarifies that 'tipo' is optional and inferred from code length, providing 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?

Clear verb+resource: 'Returns details of a specific locality by IBGE code.' Examples and sibling differentiation make purpose unambiguous.

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

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

Explicitly states when to use this tool (when you have a code) and when to use alternatives (ibge_municipios, ibge_geocodigo) for names or code decomposition.

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

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

Annotations already declare readOnly and idempotent. Description adds that it's a live GET against the public IBGE Malhas API. This is good context but not critical 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, bullet points, and examples. Every sentence serves a purpose. Front-loaded with core functionality.

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 (4 enums) and no output schema, the description fully covers usage, parameters, alternatives, and behavior. Complete for agent invocation.

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. Description significantly adds value with detailed explanations of locality types, resolution meanings, and concrete examples, going beyond 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 the tool gets geographic meshes from IBGE in specific formats. It distinguishes itself from sibling ibge_malhas_tema by mentioning thematic meshes as a separate 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 tells when to use a different tool (ibge_malhas_tema for thematic meshes) and provides detailed examples for various locality types and resolutions.

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 context: 'read-only and idempotent — a live GET against the public IBGE Malhas API. Returns the mesh in the requested format.' While repeating idempotent is redundant, it provides useful API behavior clarity.

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 for themes, codes, examples, and alternatives. Front-loaded with purpose. Every sentence adds value, no fluff.

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 5 parameters with 100% schema coverage and no output schema, the description fully covers usage: parameter semantics, examples, behavioral notes, and sibling differentiation. 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%, and description adds significant meaning: lists biome codes with names, provides example parameter combinations (e.g., tema='biomas', codigo='1'), and explains format/quality/resolution options beyond enum values.

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 'Gets thematic geographic meshes from IBGE' followed by a comprehensive list of available themes and their codes. Provides multiple examples. Explicitly 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 when to use a different tool ('Administrative meshes → ibge_malhas'). Includes examples for various use cases (all biomes, specific biome, list themes, with municipalities), giving clear guidance on 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool is a 'live GET against the public IBGE Localidades API' and returns a 'Markdown table', extending behavioral understanding 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 concise yet structured with clear sections (Features, Examples, Use a different tool when, Behavior). 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 absence of an output schema, the description specifies the return format as a 'Markdown table'. It covers all functionality, parameters, and context for differentiation, making it fully complete for the tool's purpose.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds value with concrete usage examples (e.g., uf='SP' for São Paulo) and explanatory context for the 'limite' parameter, including default and maximum values.

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

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

The description starts with a clear verb+resource: 'Lists Brazilian municipalities from IBGE.' It further details capabilities (by state, all, search) and provides multiple examples. It explicitly distinguishes from sibling tools like ibge_geocodigo, ibge_localidade, and ibge_vizinhos.

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 includes a dedicated 'Use a different tool when' section that lists exactly when to use alternative tools, providing explicit context for 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 indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it performs a live GET against the IBGE API and returns a Markdown table, providing useful 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?

The description is well-structured with sections, bullet points, and examples. It is concise, front-loaded with purpose, and 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 the tool's complexity (two modes, multiple parameters, no output schema), the description covers all necessary context: available decades, filtering options, and return format (Markdown table).

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 parameters. The description further explains parameter usage in context (e.g., which parameters apply to each tipo), adding meaning beyond the raw 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 the tool queries name frequency and rankings in Brazil, with two distinct modes (frequencia and ranking). It differentiates from sibling tools like ibge_populacao or ibge_censo, which handle different 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 provides clear guidance on when to use each tipo with examples. It does not explicitly state when not to use this tool or list alternatives, but the context is sufficient for a specialized 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?

Description confirms read-only and idempotent behavior, matching annotations. Adds that it performs a live GET and returns a Markdown list, providing 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 clear sections and examples, but slightly verbose. Could be more concise without losing clarity, but still effective.

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

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

Given 7 parameters and no output schema, description fully explains output fields (title, type, date, etc.) and provides usage examples, making it 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%, but description adds meaningful context: groups parameters, explains defaults, date format, and output structure. Includes examples demonstrating 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?

Description clearly states the tool searches and lists IBGE news articles and press releases, using specific verbs and resources. Differentiates from sibling ibge_calendario by focusing on already-published content.

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) and when not (use ibge_calendario for scheduled releases). Provides multiple examples with parameters.

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 performs a live GET against the public API and returns Markdown. 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?

Description is well-structured with bullet points and examples, making it easy to scan. Could be slightly more concise but front-loaded with main 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 5 parameters, full annotations, and no output schema, the description provides sufficient behavioral and usage context including examples. Adequately covers edge cases.

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 context (e.g., ISO-ALPHA-2 codes, region names) but does not substantially enhance 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?

Description clearly states it queries international country data via IBGE, listing specific features like listing all countries, details, search, and filtering. It distinguishes itself from sibling IBGE tools 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?

Provides explicit guidance on when to use each 'tipo' parameter (listar, detalhes, buscar, indicadores) with concrete examples. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds that it performs a 'live GET against the public IBGE SIDRA/Pesquisas API' and returns a 'Markdown list', providing additional 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 bullet points and sections, front-loading the main purpose. Some redundancy in listing main surveys, but overall every sentence adds value and it is appropriately sized.

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 no output schema, description states 'Returns a Markdown list' and clarifies the scope (lists surveys, not data). Context from siblings and annotations makes it sufficiently complete without missing critical details.

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 both parameters. Description adds usage examples like 'Search population: busca="população"' and 'PNAD details: detalhes="pnad"', which enhance 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?

Clearly states 'Lists available IBGE surveys and their tables' with specific verb and resource. Distinguishes from siblings by explaining 'This lists surveys, not data' and directing to other 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?

Explicitly says when to use this tool vs alternatives: to list surveys, not query data. Provides examples and references sibling tools like ibge_sidra_tabelas and ibge_sidra for data retrieval.

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=true, idempotentHint=true, openWorldHint=true. The description adds context: 'read-only and idempotent — a live GET against the public IBGE SIDRA API' and 'Returns Markdown.' This adds value beyond annotations by specifying the API nature and return format, though rate limits or authentication are not mentioned.

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 with a bulleted list of features, usage guidance, examples, and a behavior note. Every sentence is informative and no redundancy. It is front-loaded with 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 no output schema, the description explains the return format ('Returns Markdown') and lists content categories (general info, territorial levels, variables, etc.). It provides examples of table codes and references sibling tools. Could be slightly more detailed on response structure, but overall adequate for a metadata retrieval 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?

Input schema has 100% description coverage for all 3 parameters. The description does not add new semantic meaning beyond the schema; it only implies the output content related to the boolean parameters. Baseline 3 is appropriate as the schema already documents parameters sufficiently.

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 'Returns metadata for a specific SIDRA table' and lists specific features (info, territorial levels, variables, classifications, periods). It distinguishes itself from siblings like ibge_sidra_tabelas (finds table codes) and ibge_sidra (queries data) by positioning itself as a pre-query metadata 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?

Explicitly instructs 'Use this tool to understand table structure BEFORE querying data with ibge_sidra' and outlines a workflow: 'Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.' Examples reinforce when 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool is read-only and idempotent, mentions it performs a live GET against the public IBGE SIDRA API, and states it returns a Markdown table. This 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?

The description is well-structured with bullet points and sections (Features, Examples, Workflow). It is front-loaded with the purpose. Every sentence adds value, and the length is appropriate 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 that there are 3 optional parameters, rich annotations, and no output schema, the description provides complete context: workflow (step 1), behavior (read-only, returns Markdown), and examples. It adequately informs an agent 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 coverage is 100%, so baseline is 3. The description adds examples showing how to use each parameter (busca='população', pesquisa='censo') and explains the purpose in the features list. This reinforces understanding, justifying a score above baseline.

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

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

The description clearly states the tool lists and searches SIDRA tables. It provides a specific verb 'list' and 'search', specifies the resource 'SIDRA tables', and distinguishes itself from siblings by explaining it is step 1 of the SIDRA workflow and that wrappers exist 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 says when to use this tool (step 1 of SIDRA workflow) and when not (use wrappers like ibge_censo for common data). It also mentions alternative tools (ibge_censo, ibge_indicadores, etc.) and provides examples for different use cases (list all, search, filter by survey).

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. Description adds that it's a live GET against the public IBGE Localidades API and returns a Markdown list, plus warns about proximity approximation. 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 (Features, Note, Examples), bullet points, and clear language. Every sentence is informative with no waste.

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

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

Given no output schema, the description explains return format (Markdown list). Covers all aspects: purpose, parameters, behavior, limitations, and examples. Complete for a read-only proximity search 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% (baseline 3). The description adds value by explaining raio (radius in km using centroids), incluir_dados (population inclusion), and providing usage examples for municipio with code or name.

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 finds nearby/neighboring municipalities. It lists features (search by code or name, mesoregion approximation, optional population data) and distinguishes from sibling tool ibge_municipios.

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: when to use, example queries for code and name, optional parameters (raio, incluir_dados), and a note about limitations and alternatives (ibge_municipios).

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