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

Annotations already declare readOnly/idempotent/closed-world, so the safety bar is met; the description adds genuine context by disclosing the two authoritative data sources (asking prices vs. ITBI recorded prices) and their geographic granularity (same building vs. district). It does not cover failure behavior, e.g. what happens with an unresolvable address or a building with no comparables, which is the main 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?

The Portuguese sentence is well front-loaded (input scope first, then outputs, then use cases) and wastes little. However, the English version is a near-verbatim full-length duplicate, roughly doubling the text without adding information, which is frontal-loading preserved but conciseness hurt.

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 an eight-parameter, all-optional tool with no output schema, the description does the important extra work of enumerating what comes back (comparables, median R$/m², estimate, ITBI prices) and constraining geography to São Paulo. It stops short of describing output shape/ordering or the empty-result case, but an agent has enough 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?

With 100% schema description coverage the schema already documents each of the eight parameters, so the baseline is 3. The description adds one thing the schema does not: that endereco and lat/lon are alternative input modes ('Para um endereço ... ou um ponto lat/lon'), which clarifies the mutual-exclusivity relationship; otherwise it only restates area/tipo behavior already documented 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?

The description names a specific verb and resource — it returns for-sale comparables, median asking R$/m², an asking-price estimate, and ITBI paid prices for a São Paulo address or lat/lon point. It is clearly distinguishable from ficha_imovel or resumo_bairro, but it never explicitly contrasts itself with the closest sibling, comparaveis_imovel, leaving the address-vs-property-id distinction implicit.

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?

Concrete question templates ('quanto vale meu apartamento na Rua X, 123?', 'esse preço está caro para essa rua?') give strong positive guidance about the situations this tool serves. What is missing is the negative side: no explicit statement of when NOT to use it, and no named alternative (e.g. use comparaveis_imovel when you have a listing rather than an address).

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