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

As anotações já declaram readOnlyHint=true, idempotentHint=true e destructiveHint=false; a descrição agrega contexto comportamental importante: é uma operação lenta que gera um relatório, retorna job_id assíncrono, e traz apenas código de barras. Essas informações não são afirmadas no schema e complementam as anotações sem contradizer-las.

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?

O texto é compacto, sem redundância e cada frase sobe a descrição com uma informação útil: objetivo principal, performance e modalidade de execução, variação de entrada, conteúdo do retorno e limitação do resultado. Primeiro é uma frase resumo e os detalhes são imediatamente relevantes.

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 ferramenta tem 4 parâmetros, sem output schema e sem coverage no schema de descrição. Sem output schema, a descrição compensa bem ao explicar o que retorna (resumo com totais eamostra) e como obter um job_id async. Porém omite o significado de limit e account, criando pequenas lacunas que impedem a atribuição de 5.

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 é 0%, então a descrição precisa compensar. Ela explica o significado de codigo_barra e aguardar_segundos em contexto operacional, mas limpa e account ficam totalmente indefinidos no input-schema e na descrição do texto, exigindo que o agente inferi-o. As explicações parciais elevam acima do nada, mas são insuficientes para um parâmetro quase sem cobertura no 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 'Posição atual de estoque (saldo por código de barras)', definindo claramente o recurso consultado e a natureza da operação. Distingue-se dos irmãos ao delimitar o escopo (estoque), o modo de retorno (resumo ou saldo específico) e a limitação de trazer apenas código de barras, sem nome do produto.

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?

Explicita claramente quando informar codigo_barra para saldo específico e quando usar vazio para obter o resumo. Também orienta sobre o comportamento lento, o parâmetro aguardar_segundos e o caminho alternativo via cigam_job quando não se espera o relatório, tornando o fluxo de uso inequívoco.

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