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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety bar is met structurally. The description adds non-obvious context beyond them: failure behavior on unknown ids, that it performs a live GET against the public source when needed, and the shape of the payload. It stops short of describing rate limits or latency characteristics.

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

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

Front-loaded with the return contract, then provenance, then routing to the `ibge_*` siblings. Each sentence carries information, though the inline field enumeration partially duplicates the output schema and could be tighter.

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 retrieval tool with a full output schema and complete annotations, everything an agent needs to call it correctly is present: provenance constraint, error condition, read semantics, and where to go instead for data queries. Return-value explanation is a bonus rather than a necessity.

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?

Only one parameter, and the schema description already states it is an identifier returned by `search` at 100% coverage. The description reinforces the provenance rule (invalid ids error out) but adds no syntax, format, or example 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?

Opens with a specific verb+resource ('Returns the full document for an id'), names the field set returned, and explicitly positions itself as the companion of `search` in the Deep Research contract. An agent can distinguish it from the ~20 `ibge_*` data-query siblings without opening any schema.

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 preconditions: only ids returned by `search` are valid, and an unknown id returns an error. It also names the alternative path for a different intent ('The `ibge_*` tools ... remain the tools for data queries'), which is exactly the when-not guidance an agent needs.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real context beyond that: it is a live GET against the public IBGE Calendário API and returns a Markdown list. It does not detail rate limits or pagination edge cases, so not a full 5.

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

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

Front-loaded purpose followed by clearly sectioned features, event types, examples, and routing guidance. It is somewhat long with several sections, but each block (especially the event-type definitions and examples) earns its place given 6 parameters and an enum.

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 annotations covering the safety profile, the description supplies everything else an agent needs: purpose, event-type semantics, filtering examples, and alternative-tool routing. Nothing material 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?

Schema coverage is 100%, so the baseline is 3, but the description earns extra by mapping parameters to concrete examples (produto="IPCA", tipo="coleta") and explaining the tipo enum semantics (Release = publication, Collection = field research period) beyond the schema's short labels.

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 ('Queries IBGE release and collection calendar') and immediately differentiates itself by explaining the two event types (release vs. collection). It also names the sibling it is not (ibge_noticias), so an agent can route without opening other 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?

Provides explicit usage examples (no params for upcoming, produto="IPCA", de/ate for a year, tipo="coleta") and an explicit 'use a different tool when' clause routing published news to ibge_noticias. When-to-use and when-not-to-use are both covered.

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 the description redundantly restates 'read-only and idempotent', so that sentence earns little. It does add genuine beyond-annotation behavior: statistics mode computes over ALL rows before truncation, silently ignores campos/formato, and returns empty registros — plus fuzzy label resolution for agruparPor with the 'aviso' field and refusal on ambiguous labels. Strong disclosure, minus the annotation duplication.

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

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

Front-loaded with purpose, then years, themes, examples, mode notes and routing — a sensible priority order that lets an agent stop reading early. However, the theme list is duplicated almost verbatim between the description and the tema enum description, and the examples are long, so some sentences do not earn their 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?

Given nine parameters, three enums, an existing output schema and a dense sibling set, this definition covers everything an agent needs: valid years, valid themes, territorial level codes, the statistics escape hatch, and explicit disambiguation from every plausible alternative. The return format is already covered by the output schema, so the brief Markdown/structuredContent note is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents ano/tema/topN/agruparPor thoroughly. The description adds value by showing parameter combinations (ano + tema + nivel_territorial="3") and by flagging the cross-parameter interaction where estatisticas=true suppresses pagina/campos/formato, which the schema only hints at per-parameter.

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 (queries IBGE Demographic Census data 1970-2022) and immediately frames the value proposition: census access without knowing SIDRA table codes. The 'Use a different tool when' block names four siblings (ibge_cidades, ibge_indicadores, ibge_comparar, ibge_sidra) with the exact condition that selects each, so an agent can route without opening any schema.

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 when-to-use routing with named alternatives and their discriminating conditions (one municipality's current panel → ibge_cidades; arbitrary SIDRA table → ibge_sidra; rankings → ibge_comparar). It also gives worked invocation examples for each common case, including the 'todos' historical-series pattern and tema="listar" for table discovery.

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/non-destructive, yet the description adds substantial context beyond them: the upstream sources used (IBGE Pesquisas, Localidades, SIDRA Table 9510, versioned Atlas Brasil 1991–2010 snapshot), the restriction that salario_medio is limited to municipalities with 50,000+ inhabitants, that panorama may fan out into several calls and reports partial upstream gaps, and the return format.

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

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

Front-loaded with purpose, then cleanly sectioned into Features, indicators, Examples, and Behavior. It is on the long side and the data-source paragraph is dense, but every block earns its place by disambiguating usage or 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 5-parameter, single-endpoint panel tool with an output schema present, the description covers routing, valid inputs, data provenance, and known data limitations. Return-format detail is brief, which is appropriate since a typed structuredContent output schema exists.

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, but the description adds real meaning the schema lacks: it enumerates the valid indicador values (populacao, area, densidade, pib_per_capita, idh, etc.) and shows worked parameter combinations per tipo, which the schema only describes generically as 'ID do indicador ou nome para busca'.

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 ('Queries municipal indicators from IBGE') and immediately scopes it as 'the panel for a SINGLE municipality (Cidades@)'. It explicitly names the siblings it is not (ibge_censo, ibge_comparar, ibge_indicadores) with the condition that selects each, so an agent can route correctly without opening any schema.

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

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

Provides explicit when-to-use guidance via four feature bullets, concrete worked examples per tipo value, and an explicit when-NOT-to-use block mapping alternatives (census themes, multi-municipality comparison, macro time series) to named siblings. Nothing is left 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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds genuinely new context beyond those: it is a live GET against the public IBGE CNAE API and returns Markdown. It still omits rate limits, pagination behavior tied to 'limite', and error behavior, which keeps it at 4.

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 hierarchy, features, examples, and behavior are laid out in labeled blocks that are easy to scan and front-loaded with the core purpose. It is somewhat longer than strictly required given the schema already carries examples, but every section is on-topic and no sentence is pure 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?

With an output schema present, return-value details need not be explained, yet the description still notes the Markdown format. Combined with full schema coverage and a clear hierarchy map, an agent has everything needed to call this zero-required-parameter lookup 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 description coverage is 100% and the schema already documents each parameter, including examples of code formats and the enum values for 'nivel'. The description's examples largely restate what the schema provides, so the baseline of 3 is appropriate; it adds little semantic meaning the schema lacks.

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 ('Queries') and resource ('CNAE - National Classification of Economic Activities') plus its domain scope (Brazilian official economic-activity classification). This clearly distinguishes it from geographic siblings like ibge_municipios, ibge_estados, or ibge_malhas, without needing to open any schema.

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 'Features' block and the concrete examples map each usage mode to its parameter (busca for descriptions, codigo for codes/levels, nivel for listing), giving an agent clear routing within the tool. It stops short of naming when NOT to use it or pointing at a sibling alternative, so it does not reach 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?

The annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond that: it is a live GET against public IBGE APIs, supports up to 10 localities, calculates statistics and ranked output, and returns Markdown plus structuredContent.

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 features, examples, and exclusions clearly separated. It is somewhat redundant because it repeats the indicator list already present in the schema, but the repetition aids tool selection and does not overwhelm the reader.

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

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

Given the rich schema, annotations, and output schema, the description provides everything an agent needs: scope, limits, examples, alternatives, and behavioral context. It does not need to explain return values in detail because an output schema exists.

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 the parameters, enums, and locality code formats. The description adds examples and the 10-locality limit, but it mostly duplicates schema content and contains a semantic mismatch: it calls pib “GDP per capita,” while the schema defines it as current-price GDP in thousand reais.

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: compares data between localities, with municipalities or states explicitly named. It also distinguishes the tool from siblings by saying it is for ranking/comparing 2–10 localities on one indicator, rather than for single-locality or time-series queries.

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

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

It gives explicit when-to-use and when-not-to-use guidance, naming alternatives such as ibge_indicadores, ibge_censo, ibge_sidra, and ibge_cidades. It also includes concrete examples and a clear constraint: use this tool only to rank or compare 2–10 localities on one indicator.

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/non-destructive, so the safety profile is covered. The description adds genuine behavioral detail beyond that: it is 'a live GET against the public IBGE SIDRA API', returns 'Markdown plus a typed structuredContent payload', and discloses that in statistics mode campos/formato are ignored and registros comes back empty. Missing only rate-limit/quota 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?

Front-loaded with purpose, then organized into clear labeled sections (indicators, territorial levels, usage, examples, statistics mode, alternatives, behavior). It is long (~380 words) but dense and every block earns its place; slightly verbose in the indicator enumeration.

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 9-parameter tool with an output schema present, the description need not explain return values. It covers routing, indicator semantics, territorial codes, statistics mode, and behavioral traits, leaving no material gap 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?

Schema coverage is 100%, so baseline is 3. The description goes further, restating the territorial-level code mapping (1=Brazil…6=Municipality), explaining agruparPor's ranking behavior, and defining when/what statistics mode does to the other parameters — meaningful semantics 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?

States a specific verb and resource ('Queries Brazil health indicators, served through IBGE's SIDRA') and enumerates the indicator families (mortality, demographic, sanitation, coverage) it covers. It explicitly names the sibling it is not ('Use ibge_indicadores for general economic/social series'), so an agent can distinguish 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?

Provides explicit when-to-use ('health, mortality, fertility, sanitation and health-coverage indicators'), when-not-to-use with named alternatives ('→ ibge_cidades', '→ ibge_censo or ibge_sidra', ibge_indicadores), concrete examples, and routing guidance for statistics questions. Nothing is left 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds value beyond them by naming the upstream API ('live GET against the public IBGE Localidades API') and the return format ('Markdown table'). It does not mention rate limits or error behavior, so it is not a full 5.

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

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

Front-loaded one-line purpose followed by tight Features/Examples/Routing/Behavior blocks that each carry distinct information. Slightly long overall, but no sentence is redundant and every block 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 zero-required-parameter list tool with full schema coverage, an output schema, and rich annotations, the description supplies everything an agent needs: scope, filters, sorting, sibling routing, and even the response format. No gap remains.

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 and the enums are already documented. The examples go further by demonstrating real invocation values ('regiao="NE"', 'ordenar="sigla"'), showing how the parameters combine in practice rather than just restating 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?

States a specific verb and resource ('Lists all Brazilian states from IBGE') and immediately scopes it to the 27 states. The 'Use a different tool when' section names the siblings it must not be confused with, so an agent can route correctly 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?

Explicit when-to-use coverage via three worked examples, plus explicit when-not-to-use routing ('Municipalities of a state → ibge_municipios', 'Details/hierarchy of one locality by code → ibge_localidade'). Nothing about selection is left 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description usefully adds the concrete backing ('a live GET against the public IBGE Localidades API') and the return medium (Markdown). It stops short of disclosing rate limits, latency, or partial-match/fuzzy behavior for name searches, which is the only remaining 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?

Well front-loaded and sectioned (Features, Code structure, Examples, Use a different tool when, Behavior), so an agent can skim to the relevant part. It is on the long side and the 'Features' bullets partially restate the opening sentence, but every section carries usable content and none is 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 zero-required-parameter decoder with a published output schema, the description covers the operation modes, the code grammar, the routing alternatives, and the read-only behavior — nothing an agent needs in order 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it: the code-structure ladder (1/2/7/9 digits with region and state ranges) and the 'Municipality in state: nome="Campinas", uf="SP"' example show how the optional uf parameter scopes a nome lookup, which the schema only implies. It does not explain what happens when both codigo and nome are supplied, leaving one interaction rule unstated.

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+resource pair ('Decodes IBGE codes or searches codes by locality name') and immediately enumerates the four concrete operations (decode, search by name, show hierarchy, return related codes). It explicitly names the siblings it is not (ibge_municipios, ibge_localidade), so an agent can separate it from the 20+ other ibge_* tools without opening a schema.

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

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

Includes a dedicated 'Use a different tool when' block with two explicit exclusions mapped to the correct alternatives, plus four worked examples showing the exact call shape for each mode (decode municipality, decode state, search by name, name+uf). This is as close to unambiguous routing as a description can get.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: it is a live GET against the public IBGE SIDRA API, returns Markdown plus a typed structuredContent payload, and that estatisticas=true suppresses campos/formato and empties registros. No contradiction; only rate limits/error behavior are unstated.

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

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

Front-loads purpose, then organizes the indicator inventory under Economic/Prices/Labor/Population headers, followed by examples, the statistics-mode note, and the alternative-tool routing. Every block earns its place for a 10-parameter tool; the indicator list is essential since indicador is an unconstrained string.

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 10 parameters, a statistics mode that silently changes behavior, and an existing output schema (so return values need not be re-explained), the definition covers the valid inputs, the mode switch, routing to alternatives, and the data source. An agent has everything needed to call it 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 description coverage is 100%, so the baseline is 3; the description still adds value by giving example parameter combinations and by explaining the cross-parameter interaction of estatisticas with campos/formato/registros and the ranking semantics of agruparPor. It does not, however, add much beyond what the already-verbose schema descriptions say.

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+resource ('Queries IBGE economic and social indicators') and enumerates the concrete indicador values (pib, ipca, desemprego, populacao, etc.), so the agent knows exactly what domain it covers. It also names the sibling tools it is NOT (ibge_comparar, ibge_censo, ibge_cidades, ibge_sidra) so it is trivially distinguishable.

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

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

Explicitly provides a 'Use a different tool when:' block mapping four distinct scenarios to alternatives, plus worked examples ('indicador="pib"', 'unemployment by state → nivel_territorial="3"') and a rule for when to enable estatisticas (largest/smallest/mean/median/distribution/ranking questions). Nothing is left 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still adds value by disclosing the backing source ('live GET against the public IBGE Localidades API') and the response format ('Markdown record'). It does not mention auth requirements or rate limits, so it falls short of a 5.

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

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

Front-loaded with the core purpose, then Features/Examples/alternatives/Behavior in clearly labeled blocks. The Features list partially restates what the output schema already returns, which is mild redundancy, but every block is scannable and none is wasted prose.

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 two-parameter read tool with an output schema and full annotation coverage, the description supplies purpose, examples, routing rules, and source behavior. Nothing an agent needs in order 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?

Schema coverage is 100%, so the baseline is 3, but the description adds concrete worked examples mapping real codes to each level (estado=35, municipio=3550308, distrito=355030805) and states that hierarchy is inferred. This reinforces the digit-length convention in a way 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?

States a specific verb and resource ('Returns details of a specific locality by IBGE code') and immediately scopes it to a single record keyed by a code you already hold. It explicitly names the sibling tools it is not (ibge_geocodigo, ibge_municipios), so an agent can route without opening any schema.

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' block with two disambiguating conditions and the exact alternative tool names for each. The precondition ('you already have the code for') is stated directly, leaving nothing 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 readOnly/idempotent/non-destructive/openWorld, but the description adds non-obvious behavior: that the call is a live GET against the public IBGE Malhas API and that full geometry lands in the Markdown/download channel while structuredContent carries only lightweight cartographic metadata (feature count, geometry types, bbox, vertex centroid, property keys). This channel-split detail is exactly the kind of behavioral context annotations cannot convey.

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

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

Well front-loaded — purpose sentence first, then grouped sections (Features, Locality types, Resolution, Examples, Use a different tool when). The block structure makes it scannable, though it is on the longer side and repeats some enum information already in the schema.

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?

There is an output schema, so return-value detail is not required, and the description nevertheless notes what structuredContent contains. Combined with the behavior note, format distinctions, locality formats, resolution mapping, and sibling routing, an agent has everything needed to invoke this 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 3, but the description adds real semantics: it spells out accepted localidade forms ("BR", state abbreviation, state code, 7-digit municipality code) with examples, and clarifies what each format means (GeoJSON=data, TopoJSON=compact, SVG=image) and resolution levels. It does not add much for tipo, qualidade, or intrarregiao, which stay 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?

Opens with a specific verb+resource ("Gets geographic meshes (maps) from IBGE") and names the output formats, so the agent immediately knows this returns cartographic geometry. It distinguishes itself from the sibling ibge_malhas_tema by scoping to standard IBGE meshes and routing thematic meshes elsewhere.

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 an explicit "Use a different tool when" block naming ibge_malhas_tema for thematic meshes, plus worked examples that show valid parameter combinations. It does not cover other plausible alternatives in the large sibling set (e.g., ibge_mapa or ibge_municipios), so routing guidance is clear but not exhaustive.

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/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: data provenance from versioned official IBGE/GeoFTP snapshots, the explicit exclusion of thematic geometry, and the return shape (Markdown plus typed structuredContent).

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

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

Front-loaded with the core purpose, then a scannable list of recortes, then filtering rules, then the sibling routing. It is somewhat long and the all-caps emphasis plus repetition of the recorte list (already in the enum) costs a little, but every block is functional.

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 lister with a full output schema, annotations, and 100% schema coverage, this description covers purpose, scope boundaries, filtering behavior, provenance, and the alternative tool. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already documents for `tema` and `codigo` (biome code vs. 7-digit municipality code), adding only the behavioral note that omitting `codigo` lists records rather than a semantic detail the schema lacks.

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: it lists what a thematic territorial recorte of Brazil contains, enumerating the eight supported recortes. It also explicitly carves out what it is NOT (geometry), which separates it from ibge_malhas without the agent needing to inspect either schema.

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 routes the agent: 'Use a different tool when: Administrative meshes WITH geometry → ibge_malhas'. It also gives operational guidance for the filter ('ask without codigo to list records') and explains which recortes accept which code namespace, leaving no ambiguity about when to call 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 readOnly/idempotent/non-destructive/openWorld, but the description adds real behavioral context beyond them: hard scope limits (2–50 municipalities, single state), the server-side derivation chain (fetches state mesh at minimum quality, filters), and the output shape (metadata plus structuredContent.svg). It stops short of error behavior or fetch latency, so not a 5.

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

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

Front-loaded with the core action, then well-organized bullet lists for scope, output, and alternatives. Most sentences carry information, though the closing 'Behavior: read-only and idempotent' sentence largely repeats the annotation block, which is minor waste.

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

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

An output schema exists, so return values need not be spelled out, yet the description still usefully notes SVG contents and structuredContent.svg. Scope constraints, indicator coverage, and sibling routing cover what an agent needs; only the undocumented width/title/class-count parameters leave a small gap.

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 only 17%, so the description must compensate. It clarifies municipios (2–50, same state) and classificacao (quantiles or equal intervals) and lists the indicator values, but leaves titulo, largura, and the classes count (2–7) undocumented in both schema and description. Partial compensation, so 3.

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

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

States a concrete verb+resource+output format: generates a municipal choropleth map as SVG from audited SIDRA indicators and official IBGE municipal meshes. It explicitly differentiates from siblings (ibge_malhas, ibge_comparar, ibge_malhas_tema), so an agent can route correctly 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 'Use a different tool when' block names three sibling alternatives and the exact condition that selects each (geometry/download URL, comparison/ranking, thematic territorial composition). When-to-use and when-not-to-use are both explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, so restating 'read-only and idempotent' adds little; however, the description goes further by disclosing the live GET against the public IBGE Localidades API and the Markdown-table return format, which annotations do not convey. It stops short of error/rate-limit behavior, so not a full 5.

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

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

Front-loaded one-line purpose, then tight feature bullets, examples, exclusions, and a single behavior line. No sentence is redundant, and the exclusion block is placed after usage so it does not bloat the opening.

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

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

With an output schema present, the description need not explain return fields, and it correctly focuses on routing, scope, and invocation. Coverage of purpose, alternatives, parameter combinations, and execution semantics is complete for a read-only list tool.

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

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

Schema coverage is 100%, so baseline is 3. The examples add meaning beyond the schema by showing that uf and busca can be combined (uf="MG", busca="Belo") and demonstrating accepted value forms, which the per-field schema text does not state.

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 ('Lists Brazilian municipalities from IBGE') and immediately enumerates the three scoping modes (by state, all of Brazil, by name). It is clearly distinguishable from siblings like ibge_geocodigo and ibge_localidade without opening any schema.

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 invocation examples and an explicit 'Use a different tool when' block that names three alternatives with the condition that selects each. An agent can route correctly with no 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 readOnly, idempotent, openWorld and non-destructive, and the description's 'read-only and idempotent — a live GET against the public IBGE Nomes (Censo) API' is consistent with them while adding useful context: the live-network nature and the Markdown-table response format. That return-shape disclosure is genuine added value beyond the annotation block.

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

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

Front-loaded purpose followed by a scannable feature list and examples; every section is useful. Minor redundancy exists (sex/locality filtering is stated under both modes, and the examples restate features already described), which keeps 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?

For a two-mode query tool with a complete schema, an output schema, and full annotation coverage, nothing an agent needs is missing: modes, valid decades, filtering options, parameter examples, and response format are all present.

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 parameters are largely self-documenting and baseline would be 3. The description adds real meaning not in the schema: the valid decade window (1930–2010) and worked examples of comma-separated multi-name input and sex filtering.

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 (queries name frequency and rankings from IBGE) and the two supported query modes are enumerated immediately after. Sibling tools cover entirely different IBGE resources (estados, municipios, sidra, malhas), so an agent can distinguish this one without ambiguity.

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?

Clear context is given for selecting each mode: tipo='frequencia' for specific/multiple names, tipo='ranking' for most-popular lists, reinforced by four concrete examples. It stops short of naming alternatives or exclusions (e.g., when to prefer ibge_censo or search), so it is strong but not fully routing-aware.

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, non-destructive and openWorld, so the safety profile is covered. The description still adds real context: it is a live GET against the public IBGE Notícias API, results are sorted newest-first, the default page size is 10, and the header reports total count and page — useful operational 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?

Front-loaded one-line purpose, then clearly sectioned parameters, examples and exclusions; the newest-first/default-10 behavior is stated up top. It is on the long side, and the 'each item returns...' enumeration overlaps with the output schema, which is the only mild 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?

An output schema exists, so the description need not carry return values, yet it still summarizes them briefly. For a 7-parameter, read-only search tool, the description plus annotations and schema give an agent everything needed to call it 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 the baseline is 3, but the description earns above it by explaining the semantic difference the schema omits: tipo='release' means official survey results versus 'noticia' for general news, plus the DD/MM/AAAA date format and quantidade's default/max. It adds meaning rather than restating 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?

States a specific verb and resource ('searches and lists already-published IBGE news articles and press releases') with the 'already-published' qualifier that separates it from scheduling tools. An agent can distinguish it from ibge_calendario and the indicator/survey tools without opening any schema.

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 when-to-use framing ('find recent IBGE publications or announcements... when an indicator was released'), four concrete examples, and a dedicated 'use a different tool when' section routing scheduled releases to ibge_calendario. Nothing is left 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, idempotentHint, and openWorldHint. The description adds context beyond annotations: it states the API source ('public IBGE Países API') and the return format ('Markdown plus typed structuredContent with provenance'). This extra detail is helpful, though it repeats the read-only/idempotent traits.

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

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

The description is front-loaded with the core purpose, then organized into features, examples, and behavior. It is appropriately sized with no redundant sentences; every section adds distinct information.

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

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

Given the tool's complexity (5 optional parameters, output schema present), the description covers all key aspects: what the tool does, parameter usage via examples, available regions, code formats, and behavioral notes. An agent has enough information to invoke it correctly without needing to consult other sources.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples of parameter combinations (e.g., tipo="detalhes", pais="BR") and clarifying that indicadores is used with tipo=detalhes, going beyond the schema's individual 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 states a specific verb and resource: 'Queries international country data via IBGE.' It then lists features that distinguish it from sibling tools like ibge_estados and ibge_municipios, making its scope immediately 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?

It provides concrete usage examples for different modes (listar, detalhes, buscar, filtrar por região) and lists available regions and code formats. However, it does not explicitly state when not to use this tool or name alternative sibling tools, 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, openWorldHint and destructiveHint=false, and the description largely restates these ('read-only and idempotent'), which earns no credit. It does add two useful facts beyond the structured fields: the call is a live GET against the public IBGE API and the return is a Markdown list. That is meaningful but thin, so a 3 fits.

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

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

Front-loaded with the core purpose and the critical routing sentence, then organized under Features/Main surveys/Examples/Behavior. It is somewhat long and the 'Main surveys' taxonomy is arguably optional, but each block is scannable and nothing is buried.

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 rich annotations, the description needn't explain return values in depth. It nonetheless covers purpose, scope, sibling routing, parameter examples and call behavior, leaving no gap an agent needs to invoke it 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 the baseline is 3, and the schema itself documents both busca and detalhes. The description goes slightly beyond by giving concrete usage examples (busca="população", detalhes="pnad"), showing that detalhes accepts a survey code and busca a free-text term, which clarifies intent beyond the terse schema strings.

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 ('Lists available IBGE surveys and their tables') and immediately distinguishes itself from siblings by declaring 'This lists surveys, not data.' An agent can separate it from ibge_sidra, ibge_sidra_tabelas and the wrapper tools without opening any schema.

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 routing is provided: use ibge_sidra_tabelas to find table codes, ibge_sidra (or ibge_censo/ibge_indicadores/ibge_comparar/ibge_cidades) to query data. Both the when-to-use and the when-not-to-use cases are spelled out with named 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 cover read-only/idempotent/open-world, but the description adds substantial context beyond them: statistics are computed BEFORE pagination, SIDRA absence markers ('-', '..', '...', 'X') are excluded from n, pagina/campos/formato are ignored in that mode, and the source-side Aggregates API ceiling refuses very large queries with a concrete workaround ('narrow periodos or raise nivel_territorial'). This is exactly the operational knowledge an agent needs and cannot get from structured fields.

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 structure is strong — purpose first, then table codes, territorial levels, worked examples, the dense statistics paragraph, and finally routing. It is long, but almost every section earns its place given 12 parameters and non-obvious semantics; the statistics paragraph is dense yet front-loads the trigger words and the mode's side effects.

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?

An output schema exists, so return values need no explanation, and the description covers what remains: valid table codes, full territorial-level codes, worked examples, mode interactions, source-side limits, and sibling routing. Nothing an agent needs in order to call this 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter interactions and intent: topN's default/cap is tied to estatisticas behavior, agruparPor is explained with short-label resolution and the 'aviso' feedback, and estatisticas is framed by the question types that should trigger it. The interaction between estatisticas and agruparPor (auto-grouping by 'Variável' when units differ) is only meaningful when read as a workflow.

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 ('Queries SIDRA tables') and immediately names the sibling wrappers it is not (ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades), positioning itself as the low-level engine. An agent can select or route away from it without opening any schema.

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 when-to-use routing rules map each question class (census themes, time series, rank/compare 2–10 localities, single-municipality panel) to the right sibling tool, and it tells the agent to consult ibge_sidra_tabelas/ibge_sidra_metadados first to find table codes. The statistics-mode trigger phrases ('largest/smallest/mean/median/distribution/ranking') give concrete selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the safety profile is covered. The description still adds value by noting it is 'a live GET against the public IBGE SIDRA API' and 'Returns Markdown', which annotations do not convey.

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

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

Front-loaded with the core purpose, then well-organized Features/Examples/Behavior sections. The scheduling guidance is stated twice (once at the top of the usage note and again as 'Use this after... and before...'), a minor redundancy that keeps it short of 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?

An output schema exists, so return values need not be described. For a read-only metadata lookup the description covers purpose, usage ordering, alternatives, return format, and concrete code examples—nothing an agent needs to invoke 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?

Schema description coverage is 100%, with all three parameters documented including defaults and examples, so the schema does the heavy lifting (baseline 3). The description's feature list (periods, territorial levels) loosely maps to the incluir_periodos/incluir_localidades toggles but adds no explicit parameter guidance 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?

States a specific verb+resource ('Returns metadata for a specific SIDRA table') and enumerates exactly what the metadata contains (name, survey, territorial levels, variables, classifications, periods). It is clearly distinguishable from the sibling ibge_sidra (query data) and ibge_sidra_tabelas (find table codes).

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?

Gives explicit ordering guidance: 'Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra', and 'to understand table structure BEFORE querying data'. Both the preceding and following alternatives are named with their selection conditions.

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 (which already cover read-only/idempotent/destructive), it discloses that this is a live GET against the public API, that the response is a Markdown table, and a non-obvious behavioral trait: everyday Portuguese terms are resolved to IBGE wording (renda→rendimento, desemprego→desocupação) with the substitution surfaced in notas_vocabulario. That is real context an agent could not infer from 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?

Purpose is front-loaded and the sections (Features, surveys, Examples, workflow, Behavior) are well organized. The survey bullet list and the 'read-only and idempotent' restatement of annotations are mild padding, but the whole is still efficient for the information conveyed.

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 3-param, no-required, output-schema-backed lookup tool, the description covers purpose, usage, alternatives, workflow position, behavior, and output format. 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?

Schema description coverage is 100%, so the schema already documents busca (accent/case/AND/translation), pesquisa, and limite. The description's examples (busca="população", pesquisa="censo") illustrate usage but largely restate semantics already present in the schema, so the baseline 3 applies.

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

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

States a specific verb pair (lists and searches) against a specific resource (SIDRA tables/aggregates). The description makes the boundary explicit versus ibge_sidra (query) and ibge_sidra_metadados (structure), so an agent can distinguish it from siblings without opening any schema.

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 positions the tool as 'step 1 of the SIDRA workflow: find a table code → ibge_sidra_metadados → ibge_sidra', and names the wrapper alternatives ('ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades') that are easier for common data. This is a textbook when-to-use / when-to-use-something-else routing.

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 safety (readOnly, idempotent, non-destructive, open world), yet the description still adds real value: the backing data sources (Localidades, Malhas v3, SIDRA for enrichment), the precision caveat that radius mode is an approximation while contiguity is topological, and the Markdown-list return format.

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

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

Front-loaded summary followed by features, examples, and a behavior note; every block is scannable. The features bullets partially restate what the schema already documents (code format, incluir_dados), which is mild redundancy rather than waste.

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

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

With an output schema present the description needn't explain return values, and it still notes the Markdown list output. All four parameters, the mode-selection rule, the sibling alternative, and the external data dependencies are covered for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the behavioral difference between supplying raio (centroid radius) and omitting it (mesh contiguity), plus the 7-digit code format and the conditional uf requirement, both reinforced by examples.

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

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

Specific verb (finds) plus resource (nearby/neighboring municipalities) with the exact mechanism distinguished: topological contiguity via the official mesh vs. centroid-radius approximation. It also names the sibling to avoid (ibge_municipios) for plain listing/searching, so an agent can separate the two without reading 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?

Explicitly states the routing rule ("For listing/searching municipalities, use ibge_municipios") and the condition selecting each internal mode: no raio = shared-boundary contiguity, with raio = centroid-distance approximation. Three worked examples disambiguate code-vs-name invocation and uf requirement.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still adds the result cap, relevance ordering, the empty-list-means-no-match signal, and the in-memory caching of the public source. It restates 'read-only and idempotent' from the annotations, which is redundant, keeping it short of a 5.

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

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

Front-loaded with the core action and return shape, then usage, then query semantics, then behavior — good ordering with no filler paragraphs. It is longer than strictly necessary because 'Behavior: read-only and idempotent' repeats the annotations, but every other sentence carries information an agent needs.

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?

An output schema exists, yet the description still summarizes the return form and the empty-result case so the contract is clear at selection time. All four needed pieces — what it returns, why it exists, when to prefer siblings, and how to feed `fetch` — are present for a single-parameter tool.

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

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

With 100% schema coverage and one parameter, the baseline is 3, and the description earns a bump by adding meaning the schema does not fully carry: queries may be natural language or keywords and may be in Portuguese *or English*, plus the explicit note that this is a catalog index rather than a data query. Accent/case insensitivity is duplicated from the schema but the language breadth is 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?

Names a specific verb (searches) and a concrete resource (the IBGE catalog of SIDRA tables, municipalities, indicators), states the exact return shape ({id, title, url}) and the cap of 10, and explicitly distinguishes itself from the ibge_* data tools and from `fetch`. An agent can route to it correctly without opening any schema.

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?

Gives explicit when-to-use (the Deep Research contract requires exactly `search` plus `fetch`), explicit when-not-to-use (direct questions and actual data values/series/rankings belong to `ibge_sidra`, `ibge_cidades`, etc.), and names the follow-up tool by describing the id handoff to `fetch`. Nothing about selection is left to inference.

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