compare_regions

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

Sem annotations, a descrição carrega o peso de revelar comportamento. Ela menciona o detalhe importante sobre a base do parâmetro 'uf' nos anos 1992-1997, o que é um aviso comportamental relevante. No entanto, não informa se a operação é somente leitura, não descreve formato de retorno nem possíveis limitações de dados. Há transparência parcial, mas não completa.

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 descrição é curta (duas frases), front-loaded com o propósito principal e inclui apenas o caveat essencial sobre o significado de 'uf'. Não há redundância nem detalhes desnecessários. Cada palavra contribui para o entendimento.

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?

Para uma ferramenta com 6 parâmetros, sem output schema e sem annotations, a descrição fornece a finalidade e uma advertência crucial. Ela menciona que gera rankings, dando uma ideia do tipo de retorno. No entanto, não descreve a estrutura exata do resultado nem outros detalhes de saída, o que seria útil. A referência a get_available_years ajuda, mas ainda há espaço para mais especificidade.

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, dando baseline 3. A descrição adiciona valor além do schema ao explicar que o significado de 'uf' varia por ano, o que afeta diretamente o parâmetro compare_by. Isso é informação semântica útil que não está no schema. Portanto, nota 4 é apropriada.

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 afirma claramente que a ferramenta compara internações entre UFs ou regiões do Brasil, gera rankings e identifica variações regionais. Isso é específico e distingue de outras ferramentas de comparação, embora não mencione explicitamente alternativas como compare_icsap_trends. A menção ao significado especial de 'uf' em certos anos adiciona precisão ao propósito.

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?

A descrição indica quando usar (para comparar internações e gerar rankings) e referencia get_available_years para esclarecimentos, mas não fornece diretrizes explícitas sobre quando NÃO usar esta ferramenta em favor de outras, como compare_icsap_trends ou get_hospitalization_rates. Há contexto implícito de uso, mas falta orientação explícita sobre alternativas.

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