ibge_municipios

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

No annotations are provided, so the description carries the full burden. It discloses that name matching is partial ('total ou parcial'), which is valuable. But it does not mention return format, pagination, or error behavior. For a read-only search tool, this is a moderate gap, hence a 3.

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 compact, two sentences plus args. The main purpose is front-loaded, and the additional args are clearly listed with examples. No wasted words.

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

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

The tool is simple with two parameters, and an output schema exists (not detailed in the description, but inferred). The description covers the essential input semantics (partial name, optional UF) and leaves return format to the output schema. It's nearly complete; a minor addition could be specifying that the result is a list of matching municipalities, but that's likely covered by the output schema.

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 0%, so the description must compensate, and it does. It explains 'nome' allows partial matches and 'uf' is an optional filter with an example. This adds meaning beyond the schema, which only defines string types.

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

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

The description clearly states the verb 'busca' (search), the resource 'municípios brasileiros' (Brazilian municipalities), and the source (IBGE). It distinguishes itself from sibling tools like ibge_populacao or ibge_pib by focusing on municipality lookup rather than statistical data.

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

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

It explains the optional UF filter and gives examples, making the common use case clear. However, it does not explicitly contrast with alternatives or state when not to use it; but the sibling tools are clearly different (population, PIB, etc.), so the context is sufficient.

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