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

Sem anotações, a descrição carrega o peso da transparência e faz isso bem: revela as regras de cálculo (alíquotas progressivas 15% a 22,5%, isenção do único imóvel até R$ 440 mil, isenção por reinvestimento em 180 dias, redução da Lei 7.713 e fatores FR1/FR2). Isso informa o agente sobre o comportamento substancial da ferramenta, ainda que não descreva o formato exato da resposta.

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 é longa, mas concentra informações úteis em duas frases: a primeira define o propósito e as regras de cálculo, a segunda orienta sobre parâmetros. Embora repita parcialmente a existência dos parâmetros já presentes no schema, a instrução final sobre nomes exatos agrega valor.

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 complexa com 9 parâmetros e sem output schema, a descrição cobre os principais elementos de negócio, isenções e parâmetros obrigatórios/opcionais. Faltam apenas detalhes como tratamento de entradas inválidas ou formato do retorno, mas o núcleo para chamar e entender o comportamento está presente.

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?

A cobertura do schema é 100%, então o baseline é 3. A descrição lista os parâmetros obrigatórios e opcionais e instrui 'Use exatamente estes nomes, em inglês', o que ajuda na chamada, mas não adiciona significado semântico além do que já está documentado nas descrições 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 começa com verbo específico e recurso preciso: 'Calcula o imposto sobre o ganho de capital na venda de imóvel (DARF 4600)'. Os detalhes de alíquotas, isenções e fatores FR1/FR2 deixam claro que este não é um calculador genérico de DARF ou de imposto de renda, distinguindo-o dos muitos irmãos calculate_*.

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?

O contexto de uso fica implícito pelos detalhes do imposto sobre ganho de capital imobiliário e pela enumeração de parâmetros obrigatórios e opcionais. Porém, a descrição não diz explicitamente quando usar esta ferramenta em vez de alternativas próximas, como calculate_darf ou calculate_imposto_*.

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