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

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description discloses that the tool performs 'a live GET against the public source when the document needs it' and that invalid ids error. This adds concrete behavioral context without contradicting any 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 and front-loaded, with the return value, usage context, and behavior in separate digestible parts. It is slightly redundant with annotations in the 'read-only and idempotent' phrase, and 'when the document needs it' is a bit vague, but overall it is efficient.

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

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

For a simple one-parameter read-only tool with an output schema and safety annotations, the description covers the required id source, error behavior, return semantics, and sibling-tool routing. Nothing essential for correct invocation is missing.

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

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

The schema already fully documents id as a document identifier returned by search, so the description mostly restates that constraint. It adds no format, length, or other parameter details beyond what the schema provides, making the high-coverage baseline of 3 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 opening sentence states a specific action, 'Returns the full document for an id obtained from search', and specifies the exact return shape as { id, title, text, url, metadata }. This clearly distinguishes fetch from the ibge_* data-query siblings and identifies it as the document-retrieval counterpart of search.

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 limits valid inputs to ids returned by search and warns that unknown ids produce an error. It also names the alternative tool family, ibge_*, for data queries, giving 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value beyond those by stating it is 'a live GET against the public IBGE Calendário API' and 'Returns a Markdown list,' which clarifies the execution model and output format. It does not mention rate limits or pagination behavior, but annotations already cover the safety profile.

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 and front-loaded with the core purpose, followed by concise feature bullets, event type definitions, practical examples, an explicit alternative, and a behavioral note. Every section earns its place without redundant filler.

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

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

For a read-only calendar tool with six optional parameters, an existing output schema, and clear annotations, the description is complete. It covers purpose, event types, parameter examples, the sibling tool to avoid, and behavioral expectations, leaving no critical gap for an agent deciding whether and how to 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 description coverage is 100%, so the schema already documents all six parameters, their formats, enums, and defaults. The description adds practical semantics through examples that map natural usage patterns to parameters, such as 'IPCA releases: produto="IPCA"' and 'Field collections: tipo="coleta"', and it clarifies the no-parameter default behavior.

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

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

The description opens with a specific verb and resource: 'Queries IBGE release and collection calendar.' It further defines the two event types (Release and Collection) and distinguishes itself from ibge_noticias, so an agent can tell exactly what this tool does relative to its siblings.

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

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

The description gives clear usage context through examples: no parameters for upcoming releases, produto='IPCA', de/ate for a date range, and tipo='coleta' for field collections. It also explicitly says to use a different tool, ibge_noticias, for already-published news and releases, making the when-to-use guidance unambiguous.

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 goes beyond the annotations by stating it is 'a live GET against the public IBGE SIDRA API' and specifying the return shape: 'Markdown plus a typed structuredContent payload.' It also discloses the important statistics-mode quirk that 'campos/formato are ignored and registros comes empty.' This is valuable behavioral context the annotations alone do not provide.

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, years, themes, examples, statistics mode, alternatives, and behavior. It front-loads the main purpose and uses bullet lists and code-style examples that are easy to scan. Although somewhat long, every section earns its place for a tool with 9 optional parameters.

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

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

For a complex 9-parameter tool with an output schema, the description is nearly complete: it covers valid years, commonly used themes, example parameter combinations, statistics mode, sibling routing, and network/return behavior. The only notable gap is that the 'Available themes' list presents itself as exhaustive while omitting several valid enum values; the schema fills the gap, but the description is slightly incomplete on its own.

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

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

The schema already covers all parameters at 100%, so the bar is lower. The description adds practical combinations and clarifies statistics-mode behavior (estatisticas, agruparPor, topN, ignored campos/formato). It falls slightly short because the 'Available themes' list is partial compared with the schema enum, omitting themes like migracao, indigenas, quilombolas, saneamento, deficiencia, nupcialidade, and fecundidade.

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

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

The description opens with a specific verb and resource: 'Queries IBGE Demographic Census data (1970-2022)' and positions it as a simplified alternative to SIDRA table codes. It distinguishes itself from siblings by explicitly naming what it is not (ibge_cidades, ibge_comparar, ibge_sidra), so an agent can select it confidently.

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

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

The 'Use a different tool when' section gives explicit routing to alternatives: current municipal panel data to ibge_cidades, locality comparison/ranking to ibge_comparar, and arbitrary SIDRA tables to ibge_sidra. It also gives concrete examples for common queries and clearly states when to enable statistics mode.

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

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

The description states that the tool is read-only and idempotent, performs a live GET against the public IBGE APIs, and returns Markdown plus a typed structuredContent payload. This adds concrete behavioral context beyond the annotations, including the output format and API interaction style.

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

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

The description is well-structured with a clear opening, feature bullets, a compact indicator list, concrete examples, sibling routing, and a behavior note. Everything included earns its place and the most important scoping constraint 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 output schema, the 100% schema coverage, and the annotation set, the description is complete enough for an agent to select this tool, understand its scope, and construct valid calls. It also covers the main alternative tools, which is rare and valuable for tool selection.

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 each parameter already has a description, but the tool description adds meaningful value by listing valid indicator names (populacao, area, densidade, etc.) and giving usage examples that clarify how tipo, municipio, and indicador combine. It stops short of exhaustively documenting every possible indicator or pesquisa ID.

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

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

The description opens with a specific verb and resource: 'Queries municipal indicators from IBGE' and clarifies it is the panel for a SINGLE municipality. It explicitly names sibling tools (ibge_censo, ibge_comparar, ibge_indicadores) and distinguishes this tool from them, so an agent can tell them apart.

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

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

Provides explicit routing guidance: 'Use a different tool when' covering census themes, multiple municipalities, and macro time series. Examples show concrete parameter combinations for overviews, history, surveys, and indicators, leaving little to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details beyond the annotations: it states the operation is a live GET against the public IBGE CNAE API and that it returns Markdown. This gives the agent useful execution expectations 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 and front-loaded with purpose, followed by useful hierarchy details, feature bullets, and concrete examples. It is slightly longer than strictly necessary, but every section earns its place by helping the agent understand CNAE levels and how to invoke the tool correctly.

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

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

For a read-only lookup tool with four optional parameters, all documented in the schema, plus an output schema, this description is thorough. It covers the domain, the hierarchy, all main query patterns, example values, and the Markdown return format. Minor gaps such as rate limits are not critical given the annotations already establish safety and idempotency.

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

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

Schema description coverage is 100%, and each parameter already has a clear Portuguese description with examples. The tool description reinforces the usage by providing hierarchical context and sample codes like '6201-5/01' and codigo='J', but it does not add substantial semantic meaning beyond what the schema already provides. A 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 opens with a specific verb and resource: 'Queries CNAE (National Classification of Economic Activities) from IBGE.' It clearly defines the domain and differentiates it from sibling IBGE tools, which cover other datasets. The hierarchy breakdown further clarifies exactly what kind of data the tool returns.

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

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

The description gives clear context for when to use it: anytime an agent needs Brazilian economic activity classifications. It lists concrete usage patterns (search by code, by description, list by level) and examples. It does not explicitly name sibling exclusions, but the domain is specific enough that confusion with siblings like ibge_sidra or ibge_paises is unlikely.

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, openWorld, and non-destructive behavior. The description adds context beyond annotations by naming the live GET against public IBGE APIs (SIDRA and Localidades) and specifying the Markdown plus structuredContent return shape. Minor gap: no mention of rate limits or authentication expectations, but annotations reduce the burden.

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 clear sections: indicators, features, examples, usage guidance, and behavior. Each section earns its place, though the indicator list partly duplicates the schema's enum 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?

Given the output schema, annotations, and enum-constrained parameters, the description covers scope, constraints, alternatives, API behavior, and output format. The only notable completeness issue is the pib description mismatch, which could mislead an agent about what the indicator actually measures.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add useful examples, the 10-locality limit, and code-format clarification, but it also introduces a misleading label: 'pib: GDP per capita' conflicts with the schema's 'PIB a preços correntes (Mil Reais)'. This prevents a higher score.

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

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

States a specific verb and resource: 'Compares data between localities (municipalities or states).' It also clearly differentiates itself from siblings by positioning itself as the comparison/ranking tool and naming single-locality alternatives. The indicator list and examples reinforce what the tool does.

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

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

Provides explicit usage boundaries: 'Use this tool ONLY to rank/compare 2–10 localities on one indicator.' It also names alternative tools for single-locality queries (ibge_cidades, ibge_censo, ibge_sidra), which is strong routing 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=true, idempotentHint=true, destructiveHint=false, and the description's 'read-only and idempotent — a live GET' confirms without contradicting them. It adds value beyond annotations by disclosing the public API source, the return shape (Markdown + typed structuredContent), and the side effects of estatisticas=true (campos/formato ignored, registros empty). Only minor gaps remain, such as rate limits or pagination.

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 thematic headers, a compact examples block, and bulleted sibling routing. The descripcion is longer than average, but the tool is genuinely complex (9 parameters, statistics mode, multile indicator families), so the length is earned. The opening sentence frontloads the core purpose before diving into details.

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

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

Complete for this complexity level: an output schema covers return structure (and the description still mentions Markdown + structuredContent), all 9 parameters are documented across schema and description, the statistics mode's edge cases are spelled out, and the description even compensates for the schema by documenting autoavaliacao_saude, which the indicador enum description omits.

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, so baseline is 3. The description exceels baseline by explaining parameter interactions (estatisticas=true ignores cam pos/formato, agruparPor ranks groups by descending sum) and providing concrete usage mappings (indicador='obitos', nvel_territorial='3', localidade='35') that the schema's per-field text does not convey.

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

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

Opens with a specific verb + resource — 'Queries Brazil health indicators' — and names the data source (IBGE's SIDRA, some originally DataSUS). The thematic indicator list (mortality, demographics, sanitation, coverage) scopes the tool precisely and lets an agent distinguish it from siblings like ibge_censo (population counts) and ibge_cidades (municipality panels).

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?

Contains an explicit 'Use a different tool when' section routing to ibge_cidades for single-municipality panels and to ibge_censo/ibge_sidra for population counts. It also states the exact condition for estatisticas=true (largest/smallest/mean/median/distribution/ranking questions) with natural-language examples, leaving no ambiguity about mode 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds value beyond annotations by disclosing it is 'a live GET against the public IBGE Localidades API' and that it 'Returns a Markdown table' — behavioral context not present in the structured fields. No contradiction with annotations.

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

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

Purpose is front-loaded in the first sentence, followed by tight bullet sections: features, examples, exclusions, and behavior. Every section earns its place and none repeats schema content verbatim. The structure lets an agent scan to the relevant section quickly.

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, zero-required-param list tool with full schema coverage and rich annotations, nothing is missing. Purpose, usage patterns, exclusions, behavior, and return format are all stated; the output schema and annotations carry the remaining structural detail. The definition is complete as-is.

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 demonstrating real parameter-value combinations in examples (regiao='NE', ordenar='sigla') and summarizing the filter/sort capabilities as features. This shows the agent how to construct valid invocations beyond what the enum definitions alone communicate.

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 states a specific verb and resource: 'Lists all Brazilian states from IBGE.' It then differentiates from potentially confusing siblings by explicitly naming ibge_municipios and ibge_localidade as alternatives for different locality queries. An agent can unambiguously select this tool for state-level listing.

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

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

Provides concrete usage examples ('List all states: no parameters', 'Northeast states: regiao="NE"', 'Sorted by abbreviation: ordenar="sigla"') and an explicit 'Use a different tool when' section naming alternatives and the conditions that route away from this tool. This is exactly the when/when-not guidance the dimension asks for.

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 hints, and the description adds concrete behavior: 'a live GET against the public IBGE Localidades API' and 'Returns Markdown.' It enriches the structured hints without contradicting them.

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

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

The description is well-structured with features, code structure, examples, tool-selection guidance, and behavior. It is longer than average but every section serves a distinct purpose, and the core 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 an output schema present and three optional parameters, the description fully covers what the tool does, how parameters combine, code format rules, alternatives, and behavioral characteristics. Nothing an agent needs to call it correctly is missing.

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

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

The schema already covers all three parameters with descriptions, so the baseline is 3. The description adds value by explaining code-length structure, region number mapping, and practical usage combinations like nome='Campinas', uf='SP', going 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: 'Decodes IBGE codes or searches codes by locality name.' It also distinguishes itself by naming sibling tools it is not, making its purpose unmistakable.

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 ibge_municipios for listing/searching municipalities and ibge_localidade for full detailed records. This gives clear routing guidance beyond stating what the tool does.

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 non-destructive behavior, and the description reinforces those with the live GET against the public IBGE SIDRA API. It also discloses the return shape (Markdown plus typed structuredContent payload) and the important side effect that campos/formato are ignored and registros is empty in statistics mode.

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 highly organized with headers, examples, routing rules, and a behavior note. Every section earns its place given the tool's 10 parameters and rich indicator catalog, and the core purpose is stated in the first sentence.

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

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

With 10 parameters, 16+ sibling tools, and no required parameters, the description covers all essential decision points: available indicators, parameter usage examples, statistics-mode behavior, sibling disambiguation, and the underlying API call. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it maps every indicator key to a human-readable concept, gives concrete parameter examples for periodos and nivel_territorial, and explains estatisticas and agruparPor semantics beyond their schema descriptions. This is more than the baseline schema coverage alone provides.

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

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

The description opens with a clear verb and resource: 'Queries IBGE economic and social indicators.' It then enumerates the indicator families and examples, and distinguishes itself from siblings by explicitly routing comparison, census, and municipality-panel tasks 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?

The description gives explicit when-to-use guidance for statistics mode, including concrete natural-language questions and the agruparPor behavior. It also names specific alternative tools for specific situations ('Comparing/ranking localities → ibge_comparar'), so an agent can choose correctly without guessing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those facts, though it does. It adds value by stating it is 'a live GET against the public IBGE Localidades API' and that it returns a Markdown record, which is behavioral context beyond the structured annotations.

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

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

The description is well-organized with a clear purpose statement, feature bullets, concrete examples, explicit alternative routing, and behavioral note. Each section earns its place, and there is no unnecessary filler or repetition beyond minor restatement of scope.

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 2-parameter tool with an output schema and rich annotations, the description is complete: it covers purpose, usage boundaries, return format, examples, and behavior. The agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds concrete examples mapping codigo values to state, municipality, and district levels, and clarifies the type inference behavior already present in the schema. This reinforces parameter semantics without being redundant.

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: 'Returns details of a specific locality by IBGE code.' It clearly limits scope to one already-known locality and explicitly names sibling tools for different tasks, so an agent can distinguish it from ibge_geocodigo and 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?

The description provides explicit routing: 'Use a different tool when: You have a name and need the code → ibge_municipios or ibge_geocodigo; You want to decompose/understand a code's structure → ibge_geocodigo.' This directly tells the agent when not to use this tool and which sibling to choose instead.

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

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

The description states the operation is read-only and idempotent, performed as a live GET against the public IBGE Malhas API, which reinforces and slightly extends the annotations. It does not reveal rate limits or payload size expectations, but for an annotations-rich read-only tool that is a minor gap.

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

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

The description is a bit long but well structured with labeled sections, examples, and a targeted alternative-tool note. The key facts are front-loaded and the bulleted lists make the details scannable.

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

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

For a 6-parameter tool with an output schema, the description covers formats, locality values, resolution levels, examples, behavior, and the main sibling alternative. It omits constraints such as intrarregiao only applying to BR, but those are present in the input schema, so the overall package is complete enough.

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 already 100%, and the description adds extra value by explaining localidade forms ('BR', 'SP', '35', '3550308'), resolution meanings, and concrete format/locality examples. It doesn't expand on tipo or intrarregiao, but those are already described in the schema.

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

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

The description opens with a specific verb and resource: 'Gets geographic meshes (maps) from IBGE' and names the supported formats (GeoJSON, TopoJSON, SVG). It also differentiates itself from ibge_malhas_tema by explicitly saying thematic meshes belong to that sibling.

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

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

It gives explicit guidance for choosing ibge_malhas_tema for thematic meshes and lists concrete examples of when to use this tool (Brazil with states, SP with municipalities). The 'Use a different tool when' conditional is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description is not required to repeat those. It adds useful context by stating this is a live GET against the public IBGE Malhas API and that it returns GeoJSON, TopoJSON, or SVG, giving the agent a concrete behavioral model.

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

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

The description is well-structured with a purpose statement, bulleted theme and code lists, concrete examples, and an explicit alternative-tool note. Every section earns its place and the most important scoping information is front-loaded.

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

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

Given the strong annotations and presence of an output schema, the description covers the essential behavioral and routing context. The only minor gap is that `codigo` values are fully documented only for biomes, not for other themes like metropolitana or ride, but the examples and schema mitigate this.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by adding English theme names, biome codes, and realistic parameter combinations such as tema='biomas' with codigo='1' and resolucao='5'. This meaningfully clarifies the otherwise generic `codigo` parameter, though not every theme's codes are enumerated.

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 states a specific verb ('Gets') and resource ('thematic geographic meshes from IBGE'), and the theme list plus examples make the scope concrete. It also differentiates from the sibling ibge_malhas by explicitly naming administrative meshes as out of scope.

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

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

The description explicitly says when to use a different tool ('Administrative meshes → ibge_malhas') and provides concrete examples for common calls. This gives an agent clear when/when-not guidance alongside the named alternative.

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

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

Beyond the annotations, the description adds meaningful behavioral context: it is a live GET against the public IBGE Localidades API, read-only, idempotent, and returns a Markdown table. This tells the agent about external network dependencies, safety, and output 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 organized with a clear opening, feature bullets, examples, sibling routing, and behavioral notes. It is slightly long but every section serves a distinct purpose, and the most important information is front-loaded.

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

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

For a relatively simple listing tool with full parameter documentation, an output schema, and strong annotations, this description covers all necessary context: variants, examples, alternative tools, live API behavior, and output format. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents uf, busca, and limite. The description reinforces this with examples like uf='SP', busca='Campinas', and combinations, but it does not add substantial new meaning beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Lists Brazilian municipalities from IBGE.' It then enumerates distinct capabilities (list by state, list all, search by name) and explicitly differentiates from sibling tools, making the tool's purpose unmistakable.

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

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

The description explicitly states when to use a different tool, naming ibge_geocodigo, ibge_localidade, and ibge_vizinhos for specific alternative cases. It also provides concrete examples with parameter values, giving clear guidance on how to invoke the tool 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 readOnly, idempotent, openWorld, and non-destructive hints, so the incremental burden is low. The description adds useful behavioral context: it is 'a live GET against the public IBGE Nomes (Censo) API' and 'Returns a Markdown table', plus the available decade range.

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: a one-line purpose, two feature bullets, a short decade constraint, four illustrative examples, and a brief behavior note. Every section earns its place, and key facts are 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?

For a six-parameter tool with a full input schema, an output schema, and safety annotations, the description is effectively complete. It explains both query modes, supported filters, example usage, decade restrictions, and return format, leaving an agent with enough context to invoke the tool correctly.

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

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

The input schema already documents all six parameters with descriptions, enums, and defaults (100% coverage), so the baseline is 3. The description adds value beyond the schema by giving mode-specific combinations, comma-separated name syntax, the supported decade range, and concrete examples for each parameter pattern.

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

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

The description opens with a specific verb and resource: 'Queries name frequency and rankings in Brazil (IBGE)'. It then clearly distinguishes the two query modes—'frequencia' and 'ranking'—which directly mirrors the `tipo` parameter and separates this tool from its many IBGE siblings.

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

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

The description gives clear context for when to use each mode, with explicit examples such as using `tipo='frequencia'` for specific names and `tipo='ranking'` for popular names. It does not explicitly name sibling tools or state when not to use them, but the mode-level guidance is concrete 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 behavior. The description adds further useful context: results are newest-first, no parameters returns the 10 most recent items, it is a live GET against the public API, and the response is a Markdown list. There is no contradiction with 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 organized into purpose, usage guidance, parameter semantics, return shape, examples, and exclusions. Every section earns its place with concrete information, and the structure makes it easy for an agent 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?

For a 7-parameter read-only list tool, the description fully covers all parameters, default behavior, pagination, return fields, header metadata, and the main alternative tool. Combined with the annotations and output schema, nothing essential is missing for correct 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?

Even with 100% schema description coverage, the description adds substantial meaning: it explains 'busca' with examples, defines 'tipo' values, specifies the date format DD/MM/AAAA, documents default/max for quantidade, and explains pagination with pagina. This goes well beyond what the schema alone provides.

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

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

The description opens with a specific verb and resource: 'Searches and lists already-published IBGE news articles and press releases.' The phrase 'already-published' immediately distinguishes it from the calendario sibling, which covers scheduled/upcoming dates.

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

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

It explicitly says when to use the tool: finding recent IBGE announcements, indicator releases, or news mentioning a term like 'censo'. It gives concrete examples and explicitly routes the alternative case—'Scheduled/upcoming release dates (not yet published) → ibge_calendario'—so an agent knows when not to use it.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior; the description adds value by stating it is a 'live GET against the public IBGE Países API' and that it 'Returns Markdown.' It remains consistent with the annotations and gives an accurate operational model.

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

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

The description is front-loaded with purpose and organized into features, region/code conventions, and examples. It is longer than a minimal description, but the content is operational and non-redundant enough to 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?

For a read-only tool with five optional parameters and an output schema, the description covers the operation mode, API target, output format, accepted parameter values, and representative combinations. There is no meaningful gap an agent would need to resolve before invoking 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?

Despite 100% schema coverage, the description enriches every parameter with usage examples: ISO-ALPHA-2 country codes, the five region values, the meaning of tio='indicadores', and pipe-separated indicator IDs. This goes well beyond the schema's short field 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-resource pair: 'Queries international country data via IBGE,' and enumerates concrete capabilities (list, details, search, filter). The international-country scope clearly distinguishes it from sibling tools like ibge_estados, ibge_municipios, and ibge_cidades.

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

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

The description gives clear context through feature bullets and five concrete examples covering list, details, search, region filter, and indicators. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops 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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context beyond that: it is a 'live GET against the public IBGE SIDRA/Pesquisas API' and 'Returns a Markdown list', which helps set expectations 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 Features, Main surveys, Examples, and sibling differentiation, and the core purpose is front-loaded. It is somewhat long due to the main surveys list, but that list provides useful context for crafting search terms, so it 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?

For a list-and-detail tool, this description is complete: it states the main operation, gives search examples, explains the survey themes, clearly separates this tool from data-retrieval siblings, and describes behavior and return format. An output schema exists for structured return details, so not describing every field in the description is acceptable.

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

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

Schema coverage is 100%, so both parameters already have descriptions. The description adds concrete examples ('busca="população"', 'detalhes="pnad"') that illustrate the expected value formats and use cases, going beyond the schema's basic field 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 opening sentence uses a specific verb and resource: 'Lists available IBGE surveys and their tables.' It then explicitly differentiates from siblings with 'This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra', so an agent can distinguish it immediately.

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

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

The description gives explicit routing guidance: 'This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades).' It also provides concrete examples for list, search, and details, making when-to-use unambiguous.

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, and the description adds complementary behavioral context: 'a live GET against the public IBGE SIDRA API' and the return format ('Markdown plus a typed structuredContent payload'). It also details statistics-mode side effects such as ignored parameters and empty registros. There is no contradiction with annotations.

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

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

The description is long but well-structured and front-loaded: purpose, common tables, territorial levels, examples, statistics mode, tool routing, and behavior. Every section earns its place, and the statistics-mode paragraph is dense but necessary for correct usage.

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 12 parameters, multiple levels, and a special statistics mode, the description covers discovery, examples, limitations, and sibling routing. Since an output schema exists, the description does not need to document return values, and nothing essential for invoking the tool correctly is missing.

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

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

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema: common SIDRA table codes (6579, 9514, 4714, etc.), territorial-level code meanings, and concrete query examples like tabela="6579", periodos="2023". It also clarifies the behavior of topN and agruparPor in statistics mode.

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

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

The description states a specific verb and resource: 'Queries SIDRA tables (IBGE's Automatic Recovery System).' It further positions the tool as 'the low-level engine' and contrasts it with sibling wrappers like ibge_censo and ibge_indicadores, so an agent can distinguish it from similar tools without opening schemas.

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 tells the agent when to use this tool versus alternatives: 'Prefer a friendlier wrapper when it fits' followed by concrete mappings to census, time-series, comparison, and municipality tools. It also directs users to ibge_sidra_tabelas and ibge_sidra_metadados for discovery and explains when to enable estatisticas=true for ranking/distribution questions.

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

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

The description goes beyond the annotations by disclosing that the tool is 'a live GET against the public IBGE SIDRA API' and that it 'Returns Markdown.' This adds concrete behavioral context while not contradicting the readOnly, idempotent, or openWorld 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?

The description is well organized with a clear lead sentence, bulleted feature list, examples, and a behavior note. It loses a point for slight redundancy: the 'before querying with ibge_sidra' guidance appears twice in slightly different wording.

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 metadata-introspection tool, the description is complete: it lists the return contents, gives real example parameters, explains where it fits in the overall SIDRA workflow, and states the return format. With an output schema also available, no essential context is missing.

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

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

Schema coverage is 100%, and the schema already documents tabela, incluir_periodos, and incluir_localidades. The description adds useful example values for tabela ('6579', '9514', '4714'), but it does not explain the boolean flags or their effects beyond what the schema already states, so it lands at the baseline rather than above it.

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 object: 'Returns metadata for a specific SIDRA table,' then enumerates exactly what metadata is included (general info, territorial levels, variables, classifications, periods). It also distinguishes itself from sibling tools by positioning it between ibge_sidra_tabelas and ibge_sidra in the workflow.

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

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

Usage guidance is explicit: 'Use this tool to understand table structure BEFORE querying data with ibge_sidra' and 'Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.' This tells the agent when in the workflow to invoke it and names the relevant 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, open-world, and idempotent behavior; the description reinforces this by stating it performs a live GET against the public IBGE SIDRA API and returns a Markdown table. It does not add details about rate limits or failure modes, but the core behavioral traits are well covered.

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

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

Well-structured with bullets, examples, and a workflow note. Every section earns its place: capabilities, surveys, examples, and usage guidance are compact and 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 zero-required-params design, simple schema, output schema present, and rich annotations, the description covers what the tool does, when to use it, and where it fits in the workflow. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds examples (busca='população', pesquisa='censo') and explains the purpose of each field, but it does not go far 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?

Description states it lists and searches SIDRA tables, with concrete capabilities and examples that distinguish it from query/metadata stages. It explicitly positions itself as step 1 of a workflow, making the resource and verb 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?

Clearly explains when to use this tool: for finding a table code before consulting metadados and querying data. It also names easier wrappers (ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades) for common data, giving explicit routing guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description states that the tool is a live GET against the public IBGE Localidades API, is read-only and idempotent, and returns a Markdown list. It also discloses the mesoregion approximation caveat, which is valuable behavioral context not present in 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 first sentence, feature bullets, examples, and a behavioral note. However, the mesoregion approximation caveat is stated twice in slightly different wording, adding minor 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?

The description covers inputs, alternatives, approximation behavior, API behavior, and return format, and an output schema exists to document return details. The main gap is the unmentioned 'raio' parameter, which an agent might need to understand for radius-based searches.

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

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

The input schema already describes all four parameters at 100% coverage, so the description relies on the schema for parameter meaning. It adds useful examples for municipio and incluir_dados, but it does not clarify how the 'raio' parameter interacts with the mesoregion-based proximity logic, which is a missed opportunity.

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') and clearly distinguishes this tool from ibge_municipios, which is for listing/searching municipalities. It also clarifies that proximity is approximated via shared mesoregion, removing ambiguity about what 'neighboring' means.

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

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

The description gives concrete search options (by IBGE code or by name+UF), includes examples, and explicitly names the alternative tool: 'For listing/searching municipalities, use ibge_municipios.' It also notes that exact spatial neighborhood would require mesh processing, which helps an agent decide whether this tool is appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior; the description adds useful context on top: empty list means no match, results are relevance-ordered, the catalog is cached in memory, and queries ignore case/accents. This goes beyond the annotation coverage without contradicting it.

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

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

The description is front-loaded with the core behavior, then provides operational context and tool routing, and closes with query handling and read-only behavior. It is somewhat long but each sentence contributes, especially the sibling-tool exclusion and fetch handoff.

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 single-parameter search tool with an output schema and safety annotations, the description covers output shape, empty-result semantics, language handling, ordering, caching, and the correct path to related tools. Nothing an agent needs to call it correctly is missing.

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

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

There is only one parameter, `query`, and the schema already documents it fully. The description restates natural-language/keyword usage and accent/case behavior in English, but adds no fundamentally new semantic meaning beyond the schema description. Baseline 3 applies due to 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 a specific action and resource: 'Searches the IBGE ... catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance.' It also differentiates itself from the ibge_* siblings by calling itself 'a catalog index, not a data query,' so an agent can identify it without opening schemas.

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 pass returned ids to `fetch`, states that this exists for the Deep Research contract, and gives a clear exclusion rule: 'For direct questions and for data ... prefer the ibge_* tools.' This provides both 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.