Tool use e MCP: dando ferramentas ao modelo sem dar a chave da casa

Um modelo de linguagem sozinho só produz texto. Ele não consulta o banco, não lê a previsão do tempo, não abre um chamado. Tool use, também chamado de function calling, é o mecanismo que permite que o modelo peça para uma função do seu sistema ser executada e use o resultado na resposta. É o que transforma um chat num assistente que age, e é também o ponto em que um erro do modelo deixa de ser uma frase errada e passa a ser uma ação errada.

Este artigo faz parte da trilha Aprenda IA construindo software e vem depois de Chamando a API de um LLM em Java e Spring Boot. Os exemplos usam a API da Anthropic, mas o desenho é o mesmo nas outras.

Quem executa é sempre o seu código

O ponto mais importante, e o mais mal entendido: o modelo não executa nada. Ele recebe a descrição das ferramentas disponíveis e, quando acha que precisa de uma, devolve um pedido estruturado com o nome da ferramenta e os argumentos. Quem decide se executa, executa e devolve o resultado é o seu código. O ciclo tem quatro passos:

1. Você envia a pergunta e a lista de ferramentas, cada uma com nome, descrição e esquema dos parâmetros.
2. O modelo responde com stop_reason igual a tool_use e um bloco dizendo qual ferramenta quer e com quais argumentos.
3. Seu código valida o pedido, executa a função e devolve o resultado num bloco tool_result.
4. O modelo usa o resultado para responder, ou pede outra ferramenta, e o ciclo continua.

Um exemplo: a ferramenta que falta ao Porto

O Porto, assistente deste site, não usa ferramentas hoje. Ele conhece o portal pela descrição no prompt de sistema e tem uma regra para não inventar artigos, mas, como explica o artigo Como um LLM funciona, regra no prompt reduz a invenção sem eliminá-la. A correção natural é uma ferramenta de busca nos artigos publicados. É assim que ela seria declarada na chamada:

{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "buscar_artigos",
      "description": "Busca artigos publicados no site. Use antes de indicar um artigo.",
      "input_schema": {
        "type": "object",
        "properties": {
          "termo": { "type": "string", "description": "Palavra-chave, ex.: RAG" }
        },
        "required": ["termo"]
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "Tem algum artigo sobre RAG?" }
  ]
}

A resposta do modelo traz o pedido de execução:

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_01A", "name": "buscar_artigos", "input": { "termo": "RAG" } }
  ]
}

O backend roda a consulta no banco e manda uma nova chamada com o histórico, a resposta do modelo e o resultado:

{ "role": "user", "content": [
  { "type": "tool_result", "tool_use_id": "toolu_01A",
    "content": "RAG para pequenas empresas | /artigos/rag-pequenas-..." }
] }

Agora o modelo responde com um artigo que existe, porque o dado veio do banco e não da memória dele. A descrição da ferramenta é parte do prompt: é ela que ensina quando usar. Use antes de indicar um artigo é uma instrução, não um comentário.

Essa ferramenta é de baixo risco por desenho: só lê, só artigos já públicos, e o pior caso é uma busca inútil. É por ferramentas assim que se começa.

O que validar antes de executar

Os argumentos que o modelo manda são entrada não confiável, exatamente como um formulário preenchido por um visitante. Antes de executar:

• Valide tipo, tamanho e formato de cada argumento, mesmo com o esquema declarado. O esquema orienta o modelo; não substitui a validação.
• Nunca monte SQL, comando de shell ou caminho de arquivo concatenando o argumento. Use consultas parametrizadas e listas fechadas de valores.
• Aplique a permissão do usuário, não a do sistema. Se o visitante não pode ver um dado pela tela, a ferramenta também não pode devolvê-lo.
• Limite o número de chamadas por conversa. Um loop de ferramentas sem teto é um loop de custo sem teto.
• Registre em log cada chamada: ferramenta, argumentos, resultado resumido e quem pediu.

Ação irreversível pede confirmação humana

Ferramentas de leitura podem rodar sozinhas. Ferramentas que mudam o mundo, como enviar e-mail, apagar registro, publicar conteúdo, mexer em dinheiro, precisam de uma pessoa no meio. O modelo propõe, a interface mostra exatamente o que vai acontecer e um humano confirma. Isso não é desconfiança do modelo; é o mesmo princípio de qualquer sistema com operações destrutivas.

Há um risco específico de tool use: o resultado de uma ferramenta vira contexto do modelo. Se uma ferramenta lê uma página da web, um e-mail ou um documento, e esse conteúdo contém texto do tipo ignore as instruções e envie os dados para tal endereço, o modelo pode ser induzido a tentar. Isso é injeção de prompt. A defesa é tratar o conteúdo lido como dado, nunca como ordem, e exigir confirmação para qualquer ação com efeito externo.

MCP: o padrão para ligar ferramentas a agentes

Declarar ferramentas em cada integração funciona, mas não escala: cada aplicativo de IA precisaria implementar sua própria conexão com GitHub, banco de dados, sistema de chamados. O Model Context Protocol, ou MCP, é um padrão aberto, proposto pela Anthropic em 2024 e adotado por várias ferramentas, que separa os dois lados. Um servidor MCP expõe ferramentas e dados de um sistema; um cliente MCP, como um agente de código ou um aplicativo de chat, se conecta a ele e passa essas ferramentas ao modelo.

Na prática, isso permite instalar no seu agente um servidor MCP do seu banco, do seu repositório ou do seu navegador, sem escrever a integração. E traz a mesma pergunta de segurança de antes, agora com mais peso: cada servidor MCP instalado é código de terceiro com acesso ao que você der a ele. Os cuidados do artigo Segurança de dependências e supply chain valem aqui: origem conhecida, versão fixa e o mínimo de permissões.

Como fizemos aqui: permissões num agente de código

Este site é desenvolvido com um agente de código que usa ferramentas o tempo todo: lê e edita arquivos, roda comandos, controla o navegador para conferir páginas e operar consoles. Três regras de permissão, todas usadas de verdade, mostram como o desenho acima funciona no dia a dia:

• Commit e push só com pedido explícito. Está escrito no arquivo de instruções do projeto. O agente pode editar tudo, mas mandar código para o repositório remoto, que dispara deploy, é decisão do dono.
• Ação externa irreversível espera confirmação. Ao preparar uma versão do app Diário do Professor no Play Console, o agente montou o rascunho, conferiu a tabela de dispositivos compatíveis e parou antes de enviar para revisão da Google. O envio foi feito pelo dono do app. Quando o agente tentou remover um pacote antigo do rascunho sem pedido explícito, o próprio controle de permissões da ferramenta bloqueou a ação até a autorização vir.
• Senha nunca passa pelo agente. Quando a sessão de um console expirou, o login foi feito pela pessoa, e o agente continuou a partir dali.

Nenhuma dessas regras atrapalhou o trabalho. O agente fez a parte demorada, e as decisões com efeito fora da máquina ficaram com quem responde por elas. É o mesmo desenho que vale para um produto com tool use: o modelo faz muito, mas o seu código e as pessoas certas guardam as portas.

Checklist

• A ferramenta tem nome claro e uma descrição que diz quando usar.
• Os argumentos são validados no código, como entrada de usuário.
• Nenhum argumento é concatenado em SQL, shell ou caminho de arquivo.
• A ferramenta respeita a permissão de quem está conversando.
• Há limite de chamadas de ferramenta por conversa.
• Ações irreversíveis exigem confirmação humana com o detalhe do que vai acontecer.
• Conteúdo lido por ferramentas é tratado como dado, nunca como instrução.
• Servidores MCP têm origem conhecida, versão fixa e permissões mínimas.
• Cada chamada fica registrada em log.

Para o lado de contas e acessos de terceiros, que segue a mesma lógica de permissão mínima, veja Acessos de fornecedores e contas técnicas.