03Capítulo 3: Ferramentas: quando o modelo pede para agir

Até aqui o modelo só escreve texto. Então como um assistente lê os seus arquivos, roda os testes e abre um pull request? Ele pede. Quem faz é o aplicativo.

O pedido estruturado

Junto com o contexto, o app envia a lista de ferramentas disponíveis. Cada uma tem nome, descrição e o formato dos argumentos, descrito em JSON Schema:

{
  "name": "ler_arquivo",
  "description": "Lê um arquivo de texto do projeto e devolve o conteúdo. Use antes de alterar código.",
  "input_schema": {
    "type": "object",
    "properties": {
      "caminho": { "type": "string", "description": "Caminho relativo à raiz do projeto" }
    },
    "required": ["caminho"]
  }
}

Esse é o formato da API da Anthropic. Outras APIs usam nomes de campo um pouco diferentes, mas a ideia é a mesma.

Quando o modelo conclui que precisa ver um arquivo, em vez de responder com texto ele responde com um pedido:

{
  "type": "tool_use",
  "id": "toolu_01",
  "name": "ler_arquivo",
  "input": { "caminho": "src/rotas/pedidos.ts" }
}

O app lê esse pedido, executa a função de verdade e devolve o resultado como mais uma mensagem no contexto:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01",
  "content": "import { Router } from 'express'\n..."
}

O modelo continua de onde parou, agora sabendo o que tem no arquivo. Pode pedir outra ferramenta ou responder.

Três consequências

1. Quem executa é o app. O modelo não tem acesso a nada. As permissões são do programa que roda as ferramentas, ou seja, as suas. É o app que decide se pergunta antes: o “posso rodar este comando?” que aparece no Claude Code, no Copilot e no Cursor.
2. A descrição é instrução. O modelo escolhe a ferramenta lendo nome e descrição. Ferramenta mal descrita é ferramenta mal usada, ou nunca usada.
3. Resultado ocupa contexto. Um comando que devolve 5 mil linhas de log joga 5 mil linhas na janela do capítulo 2.

O problema que sobrou

Até pouco tempo atrás, cada aplicativo definia as próprias ferramentas do seu jeito. Para dar ao Claude, ao Copilot e ao Cursor acesso ao mesmo banco de dados, você escrevia três integrações diferentes. Cada empresa que quisesse ser usada por IA também.

O MCP, assunto do próximo capítulo, padroniza essa ligação. A ideia é parecida com a de uma tomada: você escreve a integração uma vez e ela funciona em qualquer app que tenha a tomada certa.