O que é MCP e como escrever tools que o Claude escolhe certo

Quanto mais tools um agente tem disponíveis, mais o resultado depende de como elas foram nomeadas e descritas — não só do schema. Esta página explica o MCP (Model Context Protocol) e as práticas que decidem se o Claude escolhe a tool certa ou erra por ambiguidade.

O que o MCP realmente padroniza

MCP é um protocolo que padroniza como um agente se conecta a fontes externas de dados e ação. No vocabulário do protocolo, o Claude Code atua como host; tools são controladas pelo modelo, que decide quando chamar cada uma; resources são controlados pela aplicação; e prompts são controlados pelo usuário. Cada primitiva tem um dono diferente da decisão de quando é usada — confundir os três é a fonte mais comum de mal-entendido sobre o que o MCP faz.

Isso importa na prática: um servidor MCP pode expor as três primitivas ao mesmo tempo, e nem toda integração exige o mesmo transporte — a escolha entre rodar localmente e expor via HTTP remoto depende de onde o servidor roda e de quem precisa autorizar o acesso.

Por que duas tools com o mesmo nome quebram a seleção

Quando a biblioteca de tools cresce por vários serviços, é comum dois módulos diferentes do mesmo agente exporem uma tool com nome igual — dois `get_user`, um vindo do serviço de autenticação e outro do de faturamento, por exemplo. O Claude precisa escolher entre as duas antes mesmo de preencher qualquer parâmetro, e um nome idêntico não dá informação nenhuma para essa escolha; a seleção vira sorte.

A correção documentada é dar nome com namespace por serviço: `auth_get_user`, `billing_get_user`. Um parâmetro extra para desambiguar depois não resolve, porque a ambiguidade acontece um passo antes — na seleção da tool, não no preenchimento dela — e um prefixo resolve sem tocar em nenhum schema.

A descrição é o principal canal de sinal, não o nome

Dado um nome sem ambiguidade, o que mais afeta o Claude escolher certo é a descrição: o que a tool faz, quando usá-la e o formato exato de cada parâmetro. Uma descrição vaga ("gerencia transações") deixa a decisão por conta de inferência; uma descrição específica sobre quando usar reduz isso a quase zero.

O mesmo cuidado vale para o retorno: em erro, a tool deve devolver `is_error: true` com uma mensagem acionável, não um texto genérico. E quando várias operações relacionadas fazem sentido junto, consolidar em menos tools que retornam só informação de alto sinal costuma funcionar melhor do que uma tool minúscula para cada operação.

tool_choice: quando a escolha não pode depender do modelo

Existem momentos em que a escolha não pode depender da interpretação do modelo — por exemplo, forçar que uma verificação de identidade aconteça antes de qualquer outra ação. Para isso, `tool_choice` permite forçar uma tool nomeada específica naquele turno, em vez de confiar que a descrição vai bastar.

É o mesmo padrão do domínio de permissões aplicado a tools: descrição boa aumenta a chance de acerto; um parâmetro estruturado da API garante o comportamento quando o acerto não pode ser opcional.

Duas tool calls no mesmo turno nem sempre devem rodar em paralelo

A Messages API permite que o Claude devolva mais de um bloco tool_use no mesmo turno, mas isso não significa que as duas chamadas devem ser executadas ao mesmo tempo pelo lado da aplicação. Quando uma operação depende do resultado da outra, ou quando as duas têm efeito colateral sobre o mesmo recurso, rodar em paralelo pode aplicar uma na ordem errada, ou aplicar as duas mesmo que a primeira devesse ter impedido a segunda.

Cabe à aplicação, não ao modelo, decidir a ordem de execução real das tool calls que ela recebe — o papel do Claude é decidir quais chamar; o papel do código que processa a resposta é decidir como e quando rodá-las com segurança.