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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered; the description adds real context on the data source (ITBI registry), temporal coverage (medians since 2024, series since 2006 with IPCA correction) and that links are returned. What is missing is any caveat about data lag, gaps for streets with few transactions, or minimum-sample behavior.

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

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

The first sentence front-loads what the tool returns, followed by use-case examples and the disambiguation hint — a sensible order. The full Portuguese-to-English duplication adds length that does not earn much additional clarity, though it does not obscure the core content.

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 no output schema, the description does the necessary work of describing return contents (median m², yearly series, districts, buildings, links) for a fairly rich analytical tool. The only gap is operational caveats about data coverage, freshness, or sparse streets, which an agent would want before quoting numbers.

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 both parameters are already documented, including the 'bairro' disambiguation note. The description restates that same rule ('passe bairro') without adding new syntax or constraints, so it sits at the baseline for a fully documented 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 names a specific verb and resource ('vendas registradas no ITBI numa rua de São Paulo') and enumerates the concrete outputs — median m², yearly series, districts, top buildings. The street-level scope makes it immediately distinguishable from the bairro and prédio 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?

Two concrete example questions ('qual o preço do m² na Rua Oscar Freire?', 'a Alameda Olga valorizou?') show exactly when to reach for it, and the disambiguation rule ('Se houver ruas com o mesmo nome em bairros diferentes, passe bairro') is clear. It never names siblings like vendas_bairro or vendas_predio as alternatives, so the routing is implied rather than explicit.

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