Indicadores de saúde

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

Annotations already declare read-only, idempotent, open-world and non-destructive, so the safety profile is covered; the description still adds that it is a live GET against the public SIDRA API and returns Markdown plus structuredContent. The statistics-mode side effects (campos/formato ignored, registros empty, ranking computed over ALL rows before truncation) are genuine behavioral disclosure. It stops short of auth/rate-limit or error behavior, 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?

Well front-loaded and sectioned, but it duplicates content already present at full fidelity in the schema: the nine-indicator list with Portuguese glosses, and the territorial-level legend (1=Brazil ... 6=Municipality). Roughly a third of the text is restatement rather than added value; the material that does earn its place is the sibling routing and the examples.

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 open-world query tool with an output schema, annotations and 100% schema coverage, the description supplies everything else an agent needs: indicator taxonomy, mode semantics, territorial levels, sibling disambiguation and concrete examples. Return-format explanation is a bonus since the output schema already covers it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds operational meaning the schema lacks: examples tie localidade to a territorial level ('Deaths in SP: indicador="obitos", nivel_territorial="3", localidade="35"') and explain the statistics/ranking mode's intent. It does not, however, add format details for periodo or campos beyond what the schema already documents.

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 and resource ('Queries Brazil health indicators, served through IBGE's SIDRA') and enumerates the indicator families it covers. It explicitly separates itself from ibge_indicadores ('general economic/social series such as GDP, prices, labor and population estimates'), so an agent can route correctly without opening 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?

Gives explicit when-to-use ('Use this tool for health, mortality, fertility, sanitation and health-coverage indicators') and a dedicated 'Use a different tool when' block naming ibge_cidades, ibge_censo and ibge_sidra with the exact condition that selects each. Worked examples further pin down invocation for three distinct query shapes.

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