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

As annotations já declaram readOnlyHint=true e destructiveHint=false, e a descrição é consistente com uma operação de leitura. Ela acrescenta a fonte de dados (catalogo de parceiras) e o tipo de agregação, mas não revela possíveis limitações como autenticação, rate limits ou atualização dos dados. Como as annotations cobrem o perfil de segurança, a descrição entrega valor moderado.

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?

Uma frase densa e informativa, que começa com o verbo principal e lista métricas e uso. Não há palavras redundantes, embora seja longa e poderia ser dividida em duas frases para maior legibilidade. A estrutura é aceitável para a complexidade do conteúdo.

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?

A descrição detalha o conteúdo do retorno (total, percentis, distribuição por tipo e quartos, nº de imobiliárias) e a motivação de uso, suficiente para um tool sem output schema. Não menciona formato de resposta, mas isso não é essencial para uma ferramenta de estatísticas.

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?

O schema cobre 100% dos parâmetros, com descrições detalhadas: 'cidade' inclui exemplo e 'bairro' é opcional explicando que a omissão retorna stats da cidade inteira. A descrição da tool apenas repete a ideia de cidade ou cidade+bairro, sem acrescentar nova semântica além do 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?

A descrição especifica o verbo 'Retorna', o recurso (catalogo de imobiliarias parceiras da BrokerIA) e o escopo (cidade ou cidade+bairro), listando estatísticas concretas como total de imóveis, percentis e distribuições. Diferencia-se claramente de ferramentas irmãs como brokeria_buscar_imoveis ao focar em dados agregados em vez de listagens de imóveis.

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?

Indica explicitamente quando usar: 'Util pra orientar o usuario sobre faixa de preco tipica e oferta antes de uma busca'. Não menciona quando não usar nem alternativas, mas o contexto de uso pré-busca é claro e suficiente para diferenciar de outras ferramentas.

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