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

Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the description's job is to add domain context — which it does by disclosing the data source (ITBI since 2019), the IPCA correction, and the nearest-building fallback when the address has no recorded sales. It stops short of saying how the area estimate is derived or how results are ordered.

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?

A single dense paragraph that front-loads what is returned, then the user query it answers, then the fallback behavior. The parenthetical output list is information-dense rather than padded, though the sentence is long enough that the fallback rule is easy to skim past.

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 correctly carries the return shape by enumerating the metrics returned, and it covers data provenance and the zero-sales edge case. For a 3-parameter read-only lookup with full annotation coverage, the only material omission is how the estimate is computed from area.

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 all three parameters (area, slug, endereco) are already documented, and a baseline of 3 applies. The description adds only marginal meaning, tying 'estimativa para uma área' to the area parameter and showing the street+number format via its example; the slug alternative is not mentioned at all.

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 resource and scope: actual ITBI-paid prices for a single building or house in São Paulo since 2019, with an explicit list of what it returns (IPCA-corrected median m², sale count, recent range, trend, last sale, area estimate). The example query 'quanto vale meu apê na Rua X, 123?' pins the granularity to a street number, which implicitly separates it from the street-level (vendas_rua) and neighborhood-level (vendas_bairro) 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 supplies a concrete trigger phrase and a documented fallback: if there are no sales at that number, it returns the nearest buildings on the street. It does not explicitly name when to prefer vendas_rua, vendas_bairro, or comparaveis_endereco instead, so the alternative-routing guidance is left partly implicit.

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