🔧 O Que É uma Ferramenta
Uma ferramenta é uma função com nome, descrição e parâmetros que o LLM pode invocar. Sem ferramentas, um LLM é um cérebro sem mãos — pensa, mas não age. Com ferramentas, ele lê arquivos, escreve código, executa comandos e busca informações. É a diferença entre um chatbot e um agente.
Conceito: Ferramenta = Função Invocável pelo LLM
Nome único — identifica a ferramenta (ex: Read, Bash, Edit)
Descrição clara — o LLM lê a descrição para decidir quando usar cada ferramenta
Parâmetros definidos — JSON Schema define quais inputs a ferramenta aceita
Execução externa — o LLM gera a chamada, mas quem executa é o sistema host (não o LLM)
💡 Analogia: Ferramenta = Extensão do LLM
Pense em ferramentas como extensões de um navegador. O navegador (LLM) funciona sozinho, mas com extensões (ferramentas) ele ganha superpoderes. Cada extensão faz uma coisa específica, tem uma interface definida e pode ser adicionada ou removida sem afetar o core. Um agente com 4 ferramentas bem feitas é mais poderoso que um com 40 ferramentas mal descritas.
📐 Anatomia Completa
Toda ferramenta no Claude Code segue o mesmo padrão universal: name, description, parameters (JSON Schema), execution function e return value. O Claude Code implementa ~30 ferramentas usando esse padrão, cada uma como um método de uma classe base.
Métodos Essenciais de uma Ferramenta
| Método | O Que Faz |
|---|---|
| call() | Executa a ferramenta com os parâmetros fornecidos |
| inputSchema() | Retorna o JSON Schema dos parâmetros aceitos |
| checkPermissions() | Verifica se o usuário autorizou a execução |
| isConcurrencySafe() | Indica se pode rodar em paralelo com outras ferramentas |
| isReadOnly() | Indica se a ferramenta apenas lê (sem efeitos colaterais) |
| interruptBehavior() | Define o que acontece se o usuário cancelar durante execução |
📊 Dados: O Padrão Universal
~30 ferramentas built-in — o Claude Code vem com ~30 ferramentas pré-implementadas
Classe base Tool — todas herdam de uma classe abstrata com interface padronizada
Extensível via MCP — ferramentas externas seguem o mesmo schema e se integram nativamente
JSON Schema obrigatório — toda ferramenta precisa declarar seus parâmetros para o LLM saber como usá-la
🤖 Tool Calling
O LLM analisa a tarefa, vê as ferramentas disponíveis e gera uma chamada estruturada em JSON. Não é magia — é matching de intenção com descrição. Se a descrição da ferramenta é boa, o LLM acerta a escolha. Se é vaga, ele erra ou ignora.
Como o Tool Calling Funciona
1. Recebe a tarefa — o usuário pede algo ("leia o arquivo X")
2. Analisa ferramentas disponíveis — o LLM lê os nomes e descrições de todas as tools no contexto
3. Escolhe a ferramenta — faz matching entre a intenção do usuário e a descrição da tool
4. Gera chamada JSON — emite um bloco estruturado com nome da tool e parâmetros preenchidos
5. Sistema executa — o host recebe o JSON, executa a função e devolve o resultado ao LLM
💡 Como Escrever Boas Descrições de Ferramentas
A descrição da ferramenta é o fator #1 para o LLM usá-la corretamente. Seja específico: em vez de "manipula arquivos", escreva "lê o conteúdo de um arquivo dado seu caminho absoluto". Inclua quando usar e quando NÃO usar. Mencione edge cases. O Claude Code faz isso magistralmente — cada uma de suas ~30 ferramentas tem descrições detalhadas com instruções de uso, restrições e exemplos.
✅ Validação de Entrada
Verificar inputs ANTES de executar é regra número um de segurança. Um LLM pode alucinar parâmetros, passar tipos errados ou inventar caminhos de arquivo. Validação rigorosa previne execuções perigosas e erros cascateados.
Validação de Entrada em Ferramentas
Claude Code usa Zod — biblioteca TypeScript de validação em runtime com inferência de tipos
Python: Pydantic ou jsonschema — equivalentes no ecossistema Python para o mesmo fim
Validação antes da execução — se os parâmetros não passam no schema, a ferramenta nem roda
Mensagem de erro clara — o erro volta para o LLM, que pode corrigir e tentar de novo
Fazer
- ✓ Validar todos os parâmetros com schema antes de executar
- ✓ Retornar mensagens de erro descritivas para o LLM corrigir
- ✓ Usar tipos estritos (string, number, boolean) em vez de any
- ✓ Validar caminhos de arquivo (existência, permissões, path traversal)
Evitar
- ✗ Confiar cegamente nos parâmetros gerados pelo LLM
- ✗ Executar comandos shell sem sanitizar a entrada
- ✗ Usar validação apenas no client (o LLM é o client)
- ✗ Ignorar erros de validação e executar assim mesmo
🔐 Permissões e Segurança
Nem toda ferramenta pode rodar livremente. O Claude Code implementa 3 níveis de permissão: allow (automático), deny (bloqueado) e ask (pergunta ao usuário). Isso previne que o agente execute ações destrutivas sem aprovação humana.
3 Níveis de Permissão
Allow (automático) — a ferramenta roda sem perguntar. Ideal para operações de leitura e buscas seguras
Deny (bloqueado) — a ferramenta nunca roda. Usa-se para bloquear comandos destrutivos como rm -rf
Ask (pergunta) — o sistema pausa e pede aprovação do usuário antes de executar. É o padrão para escritas
Configurável via settings.json — wildcards permitem regras como "Bash(npm test*)" → allow
📊 Exemplos de Configuração
Read, Grep, Glob: allow por padrão — são read-only, sem risco
Edit, Write: ask por padrão — modificam arquivos, precisam de aprovação
Bash(git push*): deny recomendado — previne push acidental para produção
Bash(npm test*): allow recomendado — testes são seguros e frequentes
🧰 Ferramentas Essenciais
Todo agente funcional precisa de pelo menos 4 ferramentas básicas: ler, escrever, executar e buscar. Com apenas essas 4, você já constrói um agente capaz de navegar codebases, modificar arquivos, rodar testes e encontrar informações.
As 4 Ferramentas Que Todo Agente Precisa
| Ferramenta | O Que Faz | Segurança | Exemplo |
|---|---|---|---|
| read_file | Lê conteúdo de arquivos | Read-only | Ler /src/main.py |
| write_file | Cria ou sobrescreve arquivos | Escrita | Criar /src/utils.py |
| run_shell | Executa comandos no terminal | Perigosa | npm test |
| search_in_files | Busca padrões em arquivos | Read-only | Buscar "TODO" no projeto |
💡 Com Essas 4 Você Já Constrói um Agente Funcional
Não precisa de 30 ferramentas para começar. Com read_file, write_file, run_shell e search_in_files, um agente pode: explorar uma codebase (read + search), modificar código (write), rodar testes (shell) e iterar até acertar. O Claude Code usa ~30, mas 80% do trabalho real passa por essas 4 fundamentais. Comece simples, adicione ferramentas conforme a necessidade.
📋 Resumo do Módulo
Próximo Módulo:
4.4 - 🧠 Memória e Contexto