IBGE Brasil MCP

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds beyond that by stating 'a live GET against the public IBGE Calendário API' and 'Returns a Markdown list', giving concrete behavioral context about the underlying call and output 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?

The description is well-structured with Features, Event types, Examples, and a dedicated section on when to use alternatives. Every element earns its place; it is detailed without being bloated, and the most important info (purpose and counter-indication) is front-loaded.

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

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

Given the tool has 6 parameters, no required fields, an output schema, and annotations covering read-only/idempotent behavior, the description covers all necessary context: event type definitions, filtering examples, an explicit alternative, and behavior. No critical gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description provides helpful examples (produto='IPCA', de/ate format, tipo='coleta') that illustrate parameter usage, but it does not add new semantic meaning beyond what the schema descriptions already offer.

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

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

The description opens with 'Queries IBGE release and collection calendar', a specific verb and resource. It clearly differentiates from the sibling ibge_noticias by noting that tool covers already-published news, making this tool's scope (calendar/upcoming releases) 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?

Explicit guidance is provided: 'Use a different tool when: Already-published news and releases → ibge_noticias'. Examples illustrate when to call with no params, filter by product, date range, or event type, giving clear 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 mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds value by stating it is a 'live GET against the public IBGE SIDRA API' and returns Markdown plus a typed structuredContent payload. It additionally discloses the statistics-mode quirk that campos/formato are ignored and registros comes empty, going well beyond annotation-provided safety signals.

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

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

The description is long but well-organized with bullet lists for years, themes, examples, and alternatives, and most sentences serve a purpose. Minor redundancy exists because the theme list partially duplicates the schema's enum descriptions, and the list is incomplete, but the structure remains easy to scan and 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?

For a tool with 9 parameters and a complex statistics mode, the description covers essential operational aspects: available years, themes, examples, statistics behavior, alternative tools, and read-only/idempotent nature. The existence of an output schema means return-value details are unnecessary, and the description fills gaps around use-case selection and mode behavior.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds value through concrete usage examples (e.g., ano='2022', tema='populacao'; ano='2010', tema='alfabetizacao', nivel_territorial='3') and explains the relationship between estatisticas and agruparPor. However, the 'Available themes' list omits several themes present in the schema, so it doesn't fully compensate for per-parameter nuance.

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

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

The description opens with a specific verb-resource pair ('Queries IBGE Demographic Census data') and states its simplified approach (no SIDRA codes). It explicitly differentiates from siblings by naming alternative tools for different data needs (ibge_populacao, ibge_cidades, ibge_comparar, ibge_sidra), making 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 provides explicit when-to-use guidance: it notes this is for census data without SIDRA codes and includes a 'Use a different tool when:' section listing four alternative tools and their scenarios. It also explains when to enable estatisticas=true with examples such as 'qual o maior/menor', 'média', etc., giving clear decision context.

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 and idempotentHint=true, but the description adds valuable context: "read-only and idempotent — a live GET against the public IBGE APIs (Cidades@/agregados)" and mentions the return format (Markdown plus structuredContent). This enriches the behavioral picture without contradicting the annotations.

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

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

The description is well-structured with a clear opening definition, bullet-point features, examples, and a behavior note. Each section earns its place: no fluff, and the content is front-loaded with the main purpose. The length is justified by 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?

For a tool with 5 optional parameters and multiple query modes, the description is thorough: it covers all 'tipo' options with examples, lists available indicators, and states the tool's scope relative to siblings. The existence of an output schema and the description's note about the return payload make it 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?

While the schema already documents all 5 parameters (100% coverage), the description goes beyond by listing valid indicator names (populacao, area, densidade, etc.) and providing usage examples for the 'tipo' parameter (panorama, historico, pesquisas, indicador). This gives practical meaning that the schema alone does not.

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

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

The description clearly states the tool's verb and resource: "Queries municipal indicators from IBGE (similar to Cidades@ portal)." It explicitly distinguishes itself from siblings with "This tool is the panel for a SINGLE municipality (Cidades@)" and provides concrete examples (e.g., São Paulo overview, population history). This makes the tool's scope unambiguous.

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

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

The description provides explicit when-to-use guidance: "Use a different tool when:" followed by four specific alternative tools and their use cases (e.g., real-time population → ibge_populacao, census themes → ibge_censo). It also states the tool's core purpose (single municipality), offering clear exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description reinforces these and adds valuable context: 'a live GET against the public IBGE CNAE API' and 'Returns Markdown.' This goes beyond the structured data, disclosing the integration method and output format, with no contradictions.

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

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

The description is well-organized with clear sections (hierarchy, features, examples, behavior). Every sentence adds value; the bullet points and examples are dense but not redundant. It is appropriately sized for a tool with moderate complexity, neither terse nor rambling.

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 moderate complexity, the description fully covers purpose, hierarchy, usage modes, examples, and behavior. An output schema exists, so detailed return structure is not needed. The description is self-contained and sufficient for an agent to select and invoke the tool correctly.

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

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

Schema descriptions already cover all four parameters (100% coverage), and the description adds meaningful examples: 'busca="software"', 'codigo="6201-5/01"', 'nivel="divisoes"'. It also explains the code format by level, complementing the schema's enum and description. This goes beyond the baseline and enriches parameter understanding.

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

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

The description opens with a clear, specific statement: 'Queries CNAE (National Classification of Economic Activities) from IBGE.' It then lists concrete features (search by code, description, hierarchy) and examples. This unambiguously identifies the resource and operations, distinguishing it from sibling IBGE tools.

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

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

Provides clear context for usage through feature list and practical examples (busca='software', codigo='6201-5/01', nivel='divisoes'). The hierarchical structure explanation helps users understand when to use each level. However, it does not explicitly mention alternative tools or exclusions, so it falls short of a 5.

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 meaningful behavioral context: 'a live GET against the public IBGE APIs (SIDRA and Localidades). Returns Markdown plus a typed structuredContent payload.' This goes beyond annotations by clarifying network behavior and response 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 sections for indicators, features, examples, usage guidelines, and behavior. It's longer than minimal, but the length is justified by the tool's complexity and the value of the usage guidance and examples. The indicator list duplicates the schema, which is slightly redundant but aids readability.

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 the tool's purpose, supported indicators, input formats, limits (up to 10 localities), output behavior, and alternatives. An output schema exists, so the description doesn't need to itemize return fields. 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 schema fully documents all three parameters. The description repeats the indicator list and adds examples, but these don't provide significant additional semantics beyond the schema. 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 the tool's function: 'Compares data between localities (municipalities or states).' It also specifies the verb 'compares' and the resource, and explicitly differentiates from siblings by stating 'Use this tool ONLY to rank/compare 2–10 localities on one indicator.'

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

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

The description provides explicit when-to-use guidance: 'Use this tool ONLY to rank/compare 2–10 localities on one indicator. For a single locality, use ibge_cidades (municipal panel), ibge_censo, or ibge_sidra.' This clearly states usage context and names 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?

Beyond annotations, the description discloses it is a live GET against the public IBGE SIDRA API, returns Markdown plus typed structuredContent, and details statistics mode behavior (e.g., campos/formato ignored, registros empty, ranking over ALL rows before truncation). This adds rich behavioral context 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 bold category headers, bullet lists, examples, and a dedicated alternatives section. It uses space efficiently, front-loads the purpose, and every sentence serves a clear role without unnecessary 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 9 parameters and complex statistics mode, the description covers indicators, territorial levels, examples, tool boundaries, and stats mode caveats comprehensively. An output schema exists, so return format explanation is sufficient; no significant gaps are apparent.

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 meaningful semantic grouping of indicators, territorial level examples, and practical usage examples (e.g., 'localidade="35"') that help combine parameters effectively; however, most parameter definitions are already in the schema, so this is a modest but real increment.

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 begins with 'Queries Brazil health indicators' with a specific verb and resource, and enumerates indicator categories (mortality, demographic, sanitation, coverage). It explicitly distinguishes from siblings via the 'Use a different tool when' section, naming ibge_cidades, ibge_censo, 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?

Provides explicit guidance: when to use estatisticas=true for statistical questions, and when to use alternative tools for municipality panels or population counts. This gives clear when-to-use and when-not-to-use context beyond generic tool boundaries.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds context by specifying it is a live GET against the public IBGE Localidades API and returns a Markdown table. While 'read-only and idempotent' repeats the annotations, the API source and return format are new and useful behavioral details.

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

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

The description is well-structured with a one-line summary, feature bullets, examples, alternative-tool guidance, and a behavior note. Each section is concise and serves a distinct purpose, with no redundant filler. Front-loaded with the core statement of what the tool does.

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

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

For a simple list tool with only two optional parameters, the description is complete. It covers all states, filtering, sorting, examples, alternatives, underlying API behavior, and return format (Markdown table). An output schema exists, so detailed return documentation is not needed here.

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

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

The input schema has 100% description coverage: both 'regiao' and 'ordenar' are documented with enums and defaults. The description's mention of filtering by region and sorting by ID/name/abbreviation essentially mirrors the schema without adding new meaning. The examples (regiao='NE', ordenar='sigla') slightly reinforce but do not enrich the semantic understanding.

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

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

The description opens with a specific verb+resource: 'Lists all Brazilian states from IBGE,' and immediately distinguishes itself from siblings by naming ibge_municipios and ibge_localidade for related but different queries. It clearly scopes the tool to state-level listing with filtering and sorting.

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?

An explicit 'Use a different tool when' section provides clear exclusions and names alternatives (municipalities → ibge_municipios, locality details → ibge_localidade). The examples also demonstrate typical usage (no params, regiao filter, ordenar sort), covering both default and filtered 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?

While annotations already declare read-only, idempotent, and non-destructive behavior, the description adds valuable context: 'a live GET against the public IBGE Localidades API' conveys network dependency and return format 'Markdown'. It also discloses the add-on behaviors of showing hierarchy and related codes. No contradictions with annotations.

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

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

The description is well-structured with clear sections (features, code structure, examples, alternatives, behavior). It is longer than a simple two-sentence description, but the length is justified by the tool's multiple operation modes and the need to differentiate from siblings. The opening sentence front-loads the core purpose, and there is minimal redundancy.

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

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

With an output schema present and thorough annotations, the description covers all essential aspects: the tool's dual purpose, input modes, geographic hierarchy, exclusions for alternative tools, and live API behavior. The examples and code structure make it complete for an agent to select and invoke the tool correctly in various scenarios.

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 100% coverage with detailed parameter descriptions, including code format lengths. The description adds semantic value by naming the regions (North, Northeast, etc.), giving example values that show valid parameter combinations (e.g., uf='SP' with nome='Campinas'), and illustrating how codigo lengths map to different geographic levels.

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

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

The opening sentence 'Decodes IBGE codes or searches codes by locality name' clearly states the tool's function with a specific verb and resource. It distinguishes itself from siblings by explicitly naming ibge_municipios and ibge_localidade as alternatives for other use cases. The feature list and code structure further clarify what 'decode' encompasses.

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 'Use a different tool when' guidance with named alternatives and specific scenarios (listing/searching municipalities, full locality records). It also gives multiple example call patterns (by code, by name, by name+UF) that illustrate when to use which parameter combination.

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: it is a 'live GET against the public IBGE SIDRA API' and returns Markdown plus a typed structuredContent payload. It also explains that statistics mode operates on all rows before truncation and that some parameters are ignored, which is meaningful behavioral disclosure.

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 headers (Economic, Prices, Labor, Population), bullet lists, examples, and a clear statistics mode section. Each section is concise and purposeful, avoiding redundancy. The length is justified by the tool's complexity, and the content 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 the tool's complexity (10 parameters, many indicator types, statistics mode, sibling tools), the description covers all essential aspects: available indicators, parameter behavior, examples, statistics mode semantics, and alternatives. It also references an output schema, so return values need not be described. The description is highly complete for effective selection and 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?

While the input schema has 100% description coverage, the tool description significantly enhances parameter understanding. It explains the 'listar' value for indicador, provides examples combining parameters, explains the semantics of agruparPor and estatisticas, and clarifies that certain parameters are ignored in statistics mode. This goes far beyond the basic schema descriptions.

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

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

The description opens with a specific verb ('Queries') and clearly identifies the resource (IBGE economic and social indicators). It provides a detailed list of available indicators across categories, making the scope unmistakable. It also distinguishes itself from siblings by explicitly pointing to alternative tools for related tasks.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Use a different tool when: Comparing/ranking localities → ibge_comparar, Census themes → ibge_censo, One municipality's panel → ibge_cidades'. It also includes concrete examples for common queries and a dedicated statistics mode explanation, giving clear instructions for various usage 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, and the description adds useful context beyond those: it is a live GET against the public IBGE API and returns a Markdown record. This gives the agent insight into network dependency and response format without contradicting the annotations.

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

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

The description is well-structured with a clear opening line, feature list, examples, usage guidance, and behavior note. It is slightly longer than necessary but every section serves a purpose and the information is front-loaded, making it easy to scan.

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 does not need to explain return values in detail. It covers the tool's scope, examples, alternatives, and behavioral traits (read-only, idempotent, live GET, Markdown response), making it complete for the agent to select and invoke correctly.

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

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

The input schema has 100% coverage for both parameters, so the baseline is 3. The description adds value with concrete examples (São Paulo state=35, city=3550308, district=355030805) and explains that tipo is inferred from code length when not provided, which helps the agent use the parameters correctly.

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

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

The description opens with a specific verb+resource statement: 'Returns details of a specific locality by IBGE code.' It clearly distinguishes the tool from siblings by stating it returns the full record of ONE locality you already have the code for, contrasting with ibge_municipios and 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?

Usage guidelines are explicit: use when you have a code and need the full record; use different tools when you have a name or need to decompose a code. It names the alternatives (ibge_municipios, ibge_geocodigo) with specific conditions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the baseline is lower. The description adds that this is 'a live GET against the public IBGE Malhas API' and that it returns the requested format, but it does not disclose rate limits, error behavior, or any auth requirements. This adds some context but not rich behavioral detail 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 longer than average but well-structured with bullet sections for features, locality types, resolution, examples, and exclusions. Some redundancy exists with the schema enums (formats, quality levels, resolution values), but the added examples and explanatory notes justify the 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's 6 parameters and 4 enum-based fields, the description covers the main usage patterns, provides concrete examples, names the sibling alternative, and states the underlying API behavior. An output schema exists, so return-value details are not needed in the description.

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?

Although schema coverage is 100%, the description greatly enriches parameter meaning: it explains locality shortcuts ('BR', '1', state abbreviations, state codes, 7-digit municipality codes), resolution semantics (0=outline, 2=states, 5=municipalities), and provides usage examples for format and resolution. This goes far 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?

The description opens with a specific verb+resource: 'Gets geographic meshes (maps) from IBGE in GeoJSON, TopoJSON, or SVG format.' It also distinguishes itself from the sibling tool by explicitly directing thematic mesh requests to ibge_malhas_tema, making the tool's scope clear.

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 explicit when-to-use guidance with locality types, resolution levels, and concrete examples (e.g., localidade='BR', resolucao='2'). It also provides a clear exclusion: 'Use a different tool when: Thematic meshes... → ibge_malhas_tema'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond annotations: 'a live GET against the public IBGE Malhas API' and 'Returns the mesh in the requested format (GeoJSON, TopoJSON, or SVG)' — enriching the agent's understanding of side effects and output.

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 (Available themes, Biome codes, Examples, Use a different tool, Behavior). Every sentence contributes useful information, and it is appropriately sized for a tool with multiple parameter options.

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

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

Given the output schema exists and annotations cover safety, the description completes the picture by explaining the live GET nature, available themes, codes, and when to use a sibling tool. It is comprehensive for an agent to select and invoke correctly without further clarification.

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

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

Although schema_description_coverage is 100%, the description adds significant value by providing the biome code mapping (1: Amazon, 2: Cerrado, etc.) and example parameter combinations ('tema="biomas", codigo="1"', 'tema="biomas", resolucao="5"'). This helps the agent choose correct parameter values 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 'Gets thematic geographic meshes from IBGE' with a specific verb and resource. It explicitly distinguishes from the sibling tool ibge_malhas by stating 'Use a different tool when: Administrative meshes... → ibge_malhas', making the scope unambiguous.

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

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

The description provides concrete usage examples for each theme, lists biome codes, and explicitly names the alternative tool for administrative boundaries ('ibge_malhas'). This gives the agent clear 'when to use' and 'when not to use' guidance.

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

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

Although annotations already declare readOnly/idempotent, the description adds 'a live GET against the public IBGE Localidades API' and 'Returns a Markdown table', which are not in annotations or schema. It also mentions the count of 5,570 municipalities and the 7-digit code, enriching the agent's understanding of the tool's behavior.

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

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

The description is well-structured with clear sections: summary, features, examples, exclusions, and behavior. Each section is concise, every sentence adds information, and there is no fluff or repetition.

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

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

The tool is simple (list/filter municipalities) and the description covers purpose, usage, alternatives, behavior, and return format. The output schema exists, so not explaining return values in detail is fine. Nothing important seems missing for an agent to safely invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving realistic example values for uf and busca and showing how to combine them (uf='MG', busca='Belo'). This goes beyond the schema's individual parameter descriptions, though the schema itself is already quite descriptive. Not quite a 5 because the schema covers most semantics.

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

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

The description opens with 'Lists Brazilian municipalities from IBGE', a specific verb+resource statement. It further clarifies functionality (by state, all Brazil, search by name) and explicitly differentiates from sibling tools by listing when to use ibge_geocodigo, ibge_localidade, and ibge_vizinhos 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?

Beyond stating its purpose, the description provides concrete examples (uf="SP", busca="Campinas", combined uf="MG"/busca="Belo") and an explicit 'Use a different tool when' section with named alternatives. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations by specifying it is a 'live GET against the public IBGE Nomes (Censo) API', returns a Markdown table, and restricts available decades to 1930-2010. This enhances understanding of behavior and constraints.

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

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

The description is well-organized with clear sections for features, examples, and behavior. It is concise yet comprehensive, delivering all necessary information in a scannable format without redundancy.

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

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

With two distinct modes, six parameters, complete schema descriptions, and annotations covering safety, the description is fully complete. It includes examples, parameter-mode associations, decade constraints, and return format, leaving no significant gaps for the agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond schema by explicitly mapping parameters to modes (e.g., nomes for frequencia, decada for ranking), providing examples for multiple names, and stating available decades (1930-2010) which is not in the schema. This adds practical usage meaning.

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)' with specific verbs and resource, and distinguishes between two modes (frequencia and ranking). It is distinct from sibling tools like ibge_populacao or ibge_cidades by focusing specifically on name 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 context on when to use the tool (querying name frequency or rankings) and gives examples for each mode. It does not explicitly name alternative tools or exclusion criteria, but the purpose is specific and well-scoped, making the intended usage clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description adds that it is 'a live GET against the public IBGE Notícias API' and 'Returns a Markdown list.' It also discloses result ordering (newest-first) and the default return count (10 most recent), providing context beyond the structured hints.

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

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

Although longer than a minimal description, it is well-structured: purpose, usage guidance, parameter list, output format, examples, alternative tool, and behavior. Each sentence contributes meaningful information; parameter descriptions and examples are concise and effectively formatted.

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 7-parameter tool and no visible output schema in the prompt, the description compensates by explicitly listing what each item returns (title, type, date, section, related products, featured flag, summary, link) and header metadata (total count, current page). It also covers ordering, defaults, and pagination, 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?

The input schema covers all 7 parameters with descriptions (100% coverage), so the baseline is 3. The description goes further by explaining each parameter's semantics in practical terms—e.g., 'tipo: "release" (official publication of survey results) or "noticia" (general news); omit for both'—and provides concrete examples like busca="censo" and date-format examples, adding value 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 opens with a specific verb and resource: 'Searches and lists already-published IBGE news articles and press releases.' It clearly distinguishes this tool from siblings by focusing on published items, while the alternative ibge_calendario handles scheduled/upcoming releases.

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

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

It explicitly states when to use the tool: 'Use this to find recent IBGE publications or announcements about a survey or topic' and mentions concrete use cases like indicator releases or searches for terms like 'censo'. It also provides an explicit exclusion: 'Use a different tool when: Scheduled/upcoming release dates (not yet published) → ibge_calendario'.

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

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

Annotations already declare read-only and idempotent, but the description adds that it performs a live GET against the public API and returns Markdown. This extra context helps the agent understand the external dependency and output format 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-organized with bullet points and examples that are directly useful. It is slightly longer than necessary but every section provides functional guidance, and the main purpose is front-loaded.

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

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

With 5 parameters, multiple operation modes, and an output schema present, the description covers all essential aspects: operations, regions, codes, examples, and output format. The tool's complexity is fully addressed, leaving 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?

The schema covers 100% of parameters with descriptions, and the description adds practical examples and clarifies expected values (e.g., ISO-ALPHA-2 codes, region names). The 'tipo' enum values are mapped to example usage, enhancing understanding 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 international country data via IBGE, listing specific operations (list, details, search, filter). This distinguishes it from sibling tools like ibge_estados or ibge_municipios by focusing on country-level 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 concrete examples for each value of the 'tipo' parameter, explains available regions, and specifies country code format. It gives clear context for when to use the tool, though it doesn't explicitly discuss exclusions or alternatives among siblings.

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

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

Annotations include readOnlyHint, idempotentHint, and destructiveHint=false. The description adds beyond these by stating 'Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA/Pesquisas API. Returns a Markdown list.' This reveals the network call nature and return format, though the read-only and idempotent aspects are already covered by annotations. Slight redundancy but still adds 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?

The description is organized with sections for features, main surveys, examples, and alternatives. It is longer than minimal but front-loaded with the core purpose and well-structured. Every section contributes, but some content (e.g., the list of main surveys) could be seen as optional context, keeping it from a 5.

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

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

The tool has an output schema, so return values are covered. The description covers purpose, usage, examples, alternatives, and behavioral traits. It also clarifies the tool's scope (surveys not data) and names specific sibling tools for different needs. Given the low parameter count and good annotation coverage, the description 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?

Schema coverage is 100% and both parameters are described in the schema. The description reinforces with examples (busca='população', detalhes='pnad') and feature bullets, but doesn't add substantial semantic detail beyond the schema. 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 the tool's function: 'Lists available IBGE surveys and their tables.' It uses a specific verb ('lists') and identifies the resource ('IBGE surveys and their tables'), and explicitly distinguishes itself from siblings by stating 'This lists surveys, not data' and naming alternatives like ibge_sidra_tabelas 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?

The description provides explicit guidance on when to use this tool vs alternatives: 'This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper...).' It also gives concrete usage examples for each parameter and notes that listing all requires no 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 readOnly, idempotent, and non-destructive behavior. The description adds context beyond annotations by noting it is a 'live GET against the public IBGE population-projection API' and that it returns 'Markdown plus a typed structuredContent payload.' It does not mention rate limits or failure modes, but the added context is valuable.

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

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

The description is well-structured with a clear lead sentence, bullet-pointed features, a source line, and a compact alternative-tools section. Every sentence adds useful information, and it is appropriately sized for the tool's simplicity without 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 the tool's simplicity (one optional parameter, output schema present), the description covers what the tool returns, its national-only scope, and how it differs from 20+ siblings. It even notes the response format (Markdown + structuredContent). This is complete for an agent to select and invoke the tool correctly.

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

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

The input schema fully describes the single parameter with an enum, default, and Portuguese-language description. The description's statement that the tool 'ONLY returns Brazil's real-time national projection' reinforces the schema's enum constraint but adds no new syntax or format details. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description opens with 'Returns real-time Brazilian population projection,' a specific verb and resource. The 'Features' list enumerates exact outputs (current estimate, birth/death rates, daily increment), and it clarifies this tool ONLY returns Brazil's national projection, distinguishing it from siblings like ibge_cidades and ibge_censo.

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

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

The description explicitly states the tool's scope ('ONLY returns Brazil's real-time national projection') and provides a concrete list of when to use alternative tools ('Use a different tool when:') with named siblings and their purposes. This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral detail beyond that: it is a 'live GET against the public IBGE SIDRA API', returns 'Markdown plus a typed structuredContent payload', and in statistics mode explains that pagina/campos/formato are ignored, absence markers are excluded, and the official 100,000 value cap applies. This enriches the agent's understanding without contradicting annotations.

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

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

While lengthy, the description is well-structured with clear sections (common tables, territorial levels, examples, statistics mode, alternatives). Every sentence earns its place, and the front-loaded one-liner establishes the core purpose immediately. The density of useful information justifies 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?

For a complex tool with 12 parameters, 1 required, and an output schema, the description is exceptionally complete. It covers purpose, usage alternatives, parameter semantics, examples, statistics mode edge cases, and return format. The presence of an output schema reduces the need to explain return values, but the description still mentions the structuredContent payload. This gives an agent everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant semantic value: common table codes with descriptions, territorial level code meanings, concrete examples, and detailed explanation of statistics mode behaviors affecting parameters like agruparPor, topN, and ignored parameters. This goes well beyond the schema descriptions.

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

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

The description clearly states it 'Queries SIDRA tables (IBGE's Automatic Recovery System)' with a specific verb and resource. It distinguishes from siblings by explicitly labeling itself as 'the low-level engine' and listing alternative tools for different use cases.

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

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

Provides explicit usage guidance: 'Prefer a friendlier wrapper when it fits' followed by specific tool mappings (e.g., Census themes → ibge_censo, time series → ibge_indicadores). Also explains when to use statistics mode with concrete question types like 'which municipality has the largest population?' thus giving clear when-to-use instructions.

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

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

The description adds context beyond annotations by stating 'a live GET against the public IBGE SIDRA API' and 'Returns Markdown'. While read-only and idempotent hints are already in annotations, the description enriches with the underlying mechanism and output format.

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

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

The description is well-structured with a summary, feature list, usage guidance, examples, and a behavior note. It is somewhat longer than minimal but every section supports decision-making effectively.

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 purpose, workflow, return format, and metadata content, which is sufficient for a tool with an output schema and complete parameter descriptions. It fully integrates with the tool ecosystem.

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 each parameter has a description. The description provides example values for 'tabela' but does not add semantic detail for the boolean flags. It relies appropriately on 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 'Returns metadata for a specific SIDRA table' and enumerates the metadata features. It distinguishes from sibling tools by positioning itself as the step between finding a table code (ibge_sidra_tabelas) and querying data (ibge_sidra).

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

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

Provides explicit workflow 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)'. This clearly indicates when to use the tool relative to alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that it performs 'a live GET against the public IBGE SIDRA API' and 'Returns a Markdown table.' It also clarifies that listing shows 'code and name of each table'. This contextual information 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?

The description is well-structured with clear sections: purpose, features, survey list, examples, workflow, and behavior. Each section is concise and contributes useful information without redundancy. The front-loaded purpose sentence makes the tool's role immediately clear.

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 fully covers purpose, usage, workflow, alternatives, behavior, and return format. With an output schema present and rich annotations, there is no significant missing context. An agent can confidently select and invoke this tool based on the provided information.

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 provides 100% description coverage for parameters. The description supplements this with concrete usage examples: 'Search population tables: busca="população"' and 'Census tables: pesquisa="censo"'. It also notes that calling with no parameters lists all tables, giving practical meaning to the optional parameters.

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

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

States 'Lists and searches available SIDRA tables' – a clear verb+resource pairing. It also lists specific features (list, search, filter) and distinguishes from sibling tools by positioning itself as step 1 of the SIDRA workflow with alternative wrappers mentioned.

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 defines when to use this tool: 'This is step 1 of the SIDRA workflow: find a table code → ibge_sidra_metadados (structure) → ibge_sidra (query).' It also names alternatives for common data: 'For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades.' This is direct and actionable.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it discloses the live GET against the public IBGE Localidades API, the Markdown list return format, and the crucial caveat that proximity is approximated by mesoregion rather than exact spatial adjacency. No contradiction exists.

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

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

The description is well-structured with features, examples, and notes, and it front-loads the purpose. However, the mesoregion approximation point is repeated three times (in features, first note, and second note), which is mildly redundant. Still, the overall 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 the output schema exists, return values need not be described, but the tool is still comprehensively covered. It includes the approximation limitation, clear usage examples, an explicit alternative sibling tool, and behavioral traits like read-only and idempotent. This is a complete, self-contained description for practical use.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds value beyond the schema by showing examples that combine municipio and uf (e.g., municipio='Campinas', uf='SP'), clarifying the 7-digit code format, and illustrating the incluir_dados flag. While not deeply needed, these usage patterns reinforce parameter semantics.

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

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

The description opens with a specific verb and resource: 'Finds nearby/neighboring municipalities.' It clearly scopes the tool as a proximity lookup and notes the mesoregion approximation. It distinguishes itself from ibge_municipios by explicitly pointing users to that sibling tool for listing/searching.

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

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

The description provides explicit when-to-use guidance: it notes that for exact spatial neighbors, 'mesh processing would be required' (implying a different tool like ibge_malhas), and states 'For listing/searching municipalities, use ibge_municipios.' It also gives three concrete examples covering code-based, name-based, and population-inclusive usage, making invocation conditions clear.

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