Regras de Design de Ferramentas para Agentes Claude Seguros e Componíveis

Estas são as regras enumeradas que este site usa para projetar ferramentas que os agentes Claude chamam - escopo, nomeação e validação delas para que várias ferramentas se componham com segurança em vez de acumular risco oculto à medida que o conjunto de ferramentas de um agente cresce.

Como Usar Este Checklist

• Aplique estas regras ao definir qualquer nova ferramenta, não apenas para ferramentas com efeitos colaterais óbvios.
• Trate "escopo restrito" e "nomeação clara" como pré-requisitos para revisão - uma ferramenta que é difícil de descrever em uma frase geralmente está tentando fazer demais.
• Reaudite o conjunto completo de ferramentas de um agente periodicamente, não apenas cada ferramenta isoladamente - o risco de composibilidade aparece entre as ferramentas, não dentro de uma única.
• Use as regras de validação e permissão como um checklist pré-merge para qualquer ferramenta que toque dados ou sistemas de produção.

Regras de Escopo

1. Dê a cada ferramenta exatamente uma ação bem definida. Uma ferramenta chamada manage_order que pode pesquisar, modificar, cancelar e reembolsar são quatro ferramentas usando um nome - divida-a para que cada ação possa ser raciocinada, permitida e registrada independentemente.
2. Prefira várias ferramentas estreitas a uma ferramenta ampla "para flexibilidade". A flexibilidade na camada de definição da ferramenta se torna imprevisibilidade na camada de comportamento do agente - Claude usará qualquer superfície que uma ferramenta exponha, incluindo partes que você não pretendia para uso rotineiro.
3. Mantenha os efeitos colaterais de uma ferramenta correspondendo exatamente à sua descrição. Uma ferramenta get_user_profile que também atualiza um carimbo de data/hora de "última visualização" tem um efeito colateral não documentado - nomeie-a para refletir tudo o que ela faz, ou divida a escrita.
4. Limite os dados que uma ferramenta pode acessar ao que a tarefa realmente precisa. Uma ferramenta que consulta um registro completo do cliente quando a tarefa precisa apenas de um endereço de entrega está carregando risco desnecessário sem benefício funcional.
5. Trate ferramentas bash ou de comando genérico como a exceção, não o padrão. Uma ferramenta ampla de execução de shell dá ao agente alavancagem máxima e ao harness mínima capacidade de controlar, auditar ou paralelizar - promova ações específicas para ferramentas dedicadas em vez disso.

Regras de Nomeação

6. Nomeie ferramentas pelo que elas fazem, não como são implementadas. refund_order, não call_billing_endpoint - o modelo raciocina sobre o propósito da ferramenta, e um nome com formato de implementação o força a inferir a intenção a partir dos internos.
7. Use um padrão verbo-objeto consistentemente em todo o conjunto de ferramentas. create_ticket, search_orders, send_email - a nomeação consistente reduz a incerteza do modelo sobre qual ferramenta se aplica a uma determinada etapa.
8. Nunca reutilize um nome de ferramenta para uma ação funcionalmente diferente entre agentes. Se dois agentes no mesmo sistema expõem search, mas um pesquisa documentos e o outro pesquisa registros de clientes, um harness compartilhado ou um fragmento de prompt compartilhado pode rotear incorretamente silenciosamente.
9. Escreva descrições de ferramentas que indiquem quando chamá-la, não apenas o que ela faz. "Pesquisar saldos de contas" convida mais ambiguidade de acionamento do que "Chame esta quando o usuário perguntar seu saldo atual ou total de transações recentes."

Regras de Validação

10. Valide cada entrada da ferramenta antes que ela execute, nunca confie que está pré-sanitizada. Os argumentos do modelo são texto gerado, não dados verificados - aplique a mesma validação de entrada que você faria para um formulário enviado pelo usuário.
11. Valide cada saída da ferramenta antes que ela reentre no contexto do modelo. Um resultado inesperadamente grande, malformado ou de formato inesperado deve ser capturado e truncado ou rejeitado, não passado de volta ao modelo sem verificação.
12. Rejeite entradas silenciosamente erradas de forma explícita. Retornar um resultado de ferramenta com is_error: true e uma mensagem clara permite que Claude se adapte; retornar silenciosamente um valor vazio ou padrão ensina a ele que a chamada foi bem-sucedida quando não foi.
13. Aplique restrições de esquema que o modelo não possa argumentar para contornar. Use enums para conjuntos de valores fixos e campos obrigatórios para qualquer coisa que a ferramenta não possa funcionar sem - não confie apenas em uma descrição para impor uma restrição que o esquema pode impor diretamente.
14. Sanitize caminhos de arquivo e identificadores antes de tocar no sistema de arquivos ou em um banco de dados. Um caminho ou ID fornecido pelo modelo é uma entrada não confiável - resolva e valide-o contra uma raiz permitida ou um conjunto de IDs permitidos antes de usá-lo em qualquer operação com efeitos colaterais.

Regras de Permissão e Segurança

15. Bloqueie chamadas de ferramentas destrutivas ou irreversíveis por trás de confirmação explícita. Exclusões, pagamentos e escritas de produção nunca devem executar automaticamente sem uma etapa de aprovação humana ou uma justificativa forte e revisada para pular uma.
16. Escope credenciais por ferramenta, não por agente. Uma ferramenta que só precisa ler um calendário não deve compartilhar uma credencial que também pode escrever em faturamento - o raio de explosão de uma ferramenta comprometida ou mal utilizada deve ser limitado ao que essa ferramenta realmente precisa.
17. Registre cada chamada a uma ferramenta com efeitos colaterais, independentemente da transcrição da conversa. Um log de conversa pode ser editado, truncado ou perdido; um log de auditoria dedicado para chamadas de ferramentas sensíveis sobrevive independentemente.
18. Defina um limite rígido para quantas vezes uma ferramenta pode ser chamada em um único turno do agente. Uma retentativa ou loop ilimitado contra uma ferramenta com efeitos colaterais pode transformar um bug em um incidente mais rápido do que um humano pode intervir.

Regras de Composibilidade

19. Revise o conjunto completo de ferramentas quanto a propósito sobreposto, não apenas cada ferramenta individualmente. Duas ferramentas que podem tecnicamente realizar uma tarefa criam ambiguidade que o modelo precisa resolver por conta própria, muitas vezes de forma inconsistente entre as chamadas.
20. Mantenha a contagem de ferramentas focada - muitas ferramentas degradam a precisão da seleção. Um agente escolhendo entre quarenta ferramentas vagamente relacionadas faz escolhas piores do que um escolhendo entre oito ferramentas bem escopadas; use pesquisa de ferramentas ou conjuntos de ferramentas específicos da tarefa em vez de expor tudo em todos os lugares.
21. Teste interações de ferramentas, não apenas esquemas de ferramentas individuais. Uma ferramenta que funciona corretamente isoladamente ainda pode produzir um resultado ruim quando sua saída alimenta a entrada de uma segunda ferramenta de uma maneira que ninguém testou.
22. Documente quais ferramentas são seguras para chamar em paralelo e quais não são. Uma ferramenta de consulta somente leitura e uma ferramenta que modifica o estado se comportam de maneira diferente sob chamadas concorrentes - torne essa distinção explícita em vez de deixar o harness adivinhar.

FAQs

Relacionado

• Regras de Guardrail de Segurança que Todo Tech Lead Deve Aplicar - as regras de permissão e auditoria em nível de sistema que se baseiam no escopo em nível de ferramenta.
• Higiene de Prompt e Contexto: Regras para Manter Agentes Confiáveis - como os resultados das ferramentas voltam para o contexto que essas regras protegem.
• As Regras Principais do Claude: Uma Lista de Referência Rápida - a versão condensada destas regras ao lado de todas as outras categorias.
• Melhores Práticas das Regras Claude - todas as regras desta seção reescritas como um checklist.

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.