olist_contrato_incluir

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

Sem annotations, a descrição assume o encargo de revelar comportamento. Ela informa que a operação altera dados e exige confirmar=true, mas isso já está implícito no schema do parâmetro confirmar (const true). Faltam detalhes sobre efeitos colaterais, reversibilidade, permissões ou formato de retorno.

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 e vai direto ao ponto, com o nome, endpoint e link. O texto é um pouco truncado ('Documentação: URL Esta operação...') sem pontuação entre o link e a próxima frase, mas o conteúdo é essencial.

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 um objeto aninhado sem estrutura definida no schema e não possui output schema. A descrição deveria explicar o que é retornado ou quais são os pré-requisitos, mas apenas fornece um link externo. A informação é insuficiente para um agente operar corretamente sem consultar a documentação externa.

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. A descrição adiciona pouco além do endpoint e um link para o layout do objeto 'contrato'. O parâmetro 'contrato' é um objeto aberto com additionalProperties, e o link da documentação é útil, mas não detalha a estrutura.

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?

Descreve claramente 'Incluir Contrato' e especifica o endpoint API V2 'contrato.incluir', distinguindo-se de operações como 'olist_contrato_alterar' pelo nome. A frase 'Esta operação altera dados' confirma o caráter mutável, mas o objeto é inclusão. Há um link para documentação.

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 não fornece orientação sobre quando usar esta ferramenta versus alternativas como 'olist_contrato_alterar' ou 'olist_contratos_pesquisa'. A única orientação é a exigência de confirmar=true, que é uma condição de segurança, não um critério de seleção.

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