Crédito: Foto de Ayush Sharma na Unsplash
Resumo
Quando um agente escolhe a tool errada, passa um parâmetro inválido ou repete o mesmo erro, o primeiro lugar a revisar é o que ele lê, e não o modelo. Segundo a documentação da Claude API, a descrição detalhada é, de longe, o fator que mais pesa no desempenho de uma tool. O schema com strict: true garante que a chamada chegue bem formada, e um erro escrito como instrução permite que o agente se corrija sozinho. No MCP, duas distinções evitam boa parte dos problemas: registrar um servidor não é o mesmo que autenticar nele, e annotations são dicas, não garantias. O tema corresponde ao domínio Tool Design & MCP Integration da certificação Claude Certified Architect – Foundations.
O problema em produção
O modelo escolhe e preenche cada chamada a partir do que lê sobre a tool: nome, descrição, schema, formato do resultado e mensagem de erro. Quando esse texto é vago, o agente erra a escolha, passa parâmetros inválidos ou enche o contexto de dados inúteis. Para ver como isso aparece na prática, imagine uma fintech de crédito fictícia que conecta três servidores MCP ao seu agente de atendimento: um de propostas, um de cobrança e um servidor de documentos de terceiro.
O agente chama a buscar do servidor de documentos quando deveria chamar a buscar do servidor de propostas, porque as duas descrições têm uma linha cada e começam pelo mesmo verbo.
Uma consulta por proposta inexistente devolve “não encontrado” como resultado normal, e o modelo repete a frase ao cliente como se fosse um dado.
A listagem de parcelas traz centenas de registros cheios de campos internos, e a conversa perde o fio.
Alguém versiona um .mcp.json com o token do servidor de cobrança colado no cabeçalho.
Depois que o time conecta mais dois servidores, o custo de cada conversa sobe antes mesmo de o cliente digitar a primeira mensagem.
Todas são falhas de interface, e cada seção a seguir resolve uma delas.
Por que a solução óbvia falha
A reação mais comum é reforçar o system prompt com regras como “use sempre a tool de propostas para perguntas sobre propostas”. Instruções no prompt podem influenciar quando o modelo recorre a uma tool, mas não desfazem a ambiguidade entre duas tools de mesmo nome, não transformam uma frase de erro em sinal de erro e não reduzem o custo das definições carregadas.
Forçar a chamada com tool_choice também não resolve e, em vários modelos atuais, nem é possível, como mostra a seção 2. Criar uma tool por endpoint piora o quadro: o artigo Writing effective tools for agents, da Anthropic, aponta essa prática como um erro comum.
1. A interface da tool decide a seleção
A descrição é o principal mecanismo
Uma boa descrição diz o que a tool faz, quando usá-la e quando não usá-la, o que significa cada parâmetro e o que a tool não devolve. A documentação da Claude API recomenda pelo menos três ou quatro frases. O artigo da Anthropic Engineering sugere um teste simples: descreva a tool como faria para alguém que acabou de entrar no time, e dê aos parâmetros nomes sem ambiguidade, como user_id em vez de user.
No MCP, o campo description é opcional na especificação, que o trata como uma dica para o modelo. Na prática, porém, ele é decisivo. Os hosts também impõem limites: o Claude Code corta descrições longas, e por isso a documentação pede texto conciso, com os detalhes críticos logo no início.
Nomes e consolidação
Quando o agente enxerga tools de vários serviços, prefixe cada nome com o serviço, como propostas_buscar e documentos_buscar. Use _ como separador: a especificação do MCP aceita ponto no nome, mas a Claude API o recusa. Prefixo e sufixo podem ter efeitos diferentes de um modelo para outro, por isso vale definir a convenção com avaliações próprias.
Consolide também as operações relacionadas. Em vez de três tools para criar, revisar e aprovar uma proposta, exponha uma única propostas_gerenciar com o parâmetro acao: poucas tools mais capazes reduzem a ambiguidade na hora da escolha.
Menor privilégio
As boas práticas de segurança do MCP recomendam começar com escopos mínimos e só elevar a permissão quando uma operação privilegiada for de fato tentada. O mesmo princípio vale para as tools que cada agente enxerga: exponha apenas as que ele usa. Na fintech, um agente de consulta fica com propostas_buscar e um token de leitura, sem a tool e sem o escopo que aprovam uma proposta.
Respostas de alto sinal e catálogo enxuto
Devolva só o que o modelo precisa para o próximo passo. Prefira nomes com significado, como consignado-aposentado, a identificadores opacos, e use response_format (concise ou detailed) para entregar o identificador técnico apenas quando a próxima chamada precisar dele. Quando a resposta puder ser grande, combine paginação, filtragem ou truncamento com valores padrão sensatos, e avise o agente sempre que cortar algo.
Cada definição carregada também ocupa contexto, e foi justamente esse custo que subiu na fintech. A tool search da Claude API (defer_loading: true) só carrega uma definição quando uma busca a encontra, e o Claude Code já usa esse recurso por padrão com servidores MCP.
Exemplo: a definição no servidor MCP
A definição abaixo, tal como aparece na resposta a tools/list, reúne descrição completa, nome com prefixo, schema fechado e annotations:
Definição completa de propostas_buscar
2. tool_choice e strict: quem decide se haverá chamada
O parâmetro tool_choice define se o modelo deve chamar uma tool:
auto: o modelo decide. É o padrão quando a requisição traz tools.
any: obriga o uso de alguma tool, sem fixar qual.
tool: obriga o uso de uma tool específica. É uma obrigação, não uma preferência.
none: impede o uso de tools. É o padrão quando a requisição não traz tools.
Em Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, any e tool retornam erro 400. Nos modelos que aceitam essas opções, como o Claude Haiku 5.5, a chamada forçada pula o raciocínio: a resposta começa direto no tool_use, sem bloco thinking. A alternativa documentada é usar auto com strict tool use, que garante um input válido pelo schema, ou structured outputs, quando a resposta precisa seguir um formato JSON fixo.
Com strict: true, a Claude API usa amostragem restrita por gramática para que o input siga exatamente o input_schema. Os schemas strict ficam em cache por até 24 horas, separados do conteúdo das mensagens e sem as mesmas proteções. Por isso, a documentação proíbe dado de saúde protegido (PHI) em nomes de propriedade e em valores de enum, const e pattern. Aqui, estendemos a regra ao dado pessoal protegido pela LGPD: nenhum CPF, nome ou e-mail em schema.
Para claude-opus-5-5 e claude-sonnet-5-5, a requisição com auto e strict: true fica assim:
Requisição com auto e strict: true
3. Erros que o modelo consegue ler
A especificação do MCP separa dois tipos de erro. Os erros de protocolo, como tool desconhecida ou requisição malformada, voltam como erro JSON-RPC e deixam ao modelo pouca chance de recuperação. Os erros de execução, como falha de API ou violação de regra de negócio, voltam dentro do resultado com isError: true (na Claude API, is_error: true no tool_result), e o client deve repassá-los ao modelo para que ele se corrija.
Escreva o erro como instrução: diga o que deu errado e o que tentar em seguida. Diante de uma chamada inválida, o Claude tenta de novo duas ou três vezes, com correções, antes de se desculpar com o usuário, então a primeira mensagem de erro precisa ser útil. O resultado abaixo resolve o “não encontrado” da fintech:
Resultado com isError: true
Para escolher o mecanismo, a documentação do Python SDK v2 do MCP propõe uma pergunta: um modelo mais inteligente teria evitado esse erro? Se a resposta for sim, levante ToolError, que chega ao modelo. Se for não, use MCPError, que faz a requisição falhar. Nunca devolva a mensagem de erro com return, porque o resultado sai marcado como sucesso. O exemplo abaixo levanta um ToolError com mensagem acionável:
Exemplo com ToolError
Trate também o conteúdo de um tool_result como não confiável, porque ele pode trazer instruções plantadas por terceiros. Mantenha esse conteúdo dentro do tool_result, nunca no system prompt.
4. Papéis e primitivas do MCP
O MCP tem três papéis. O host é a aplicação que o usuário enxerga e que coordena tudo. O client é o componente que o host cria para conversar com um único servidor. O servidor expõe tools, resources e prompts. Cada primitiva tem um controlador diferente: as tools são controladas pelo modelo, os resources pela aplicação e os prompts pelo usuário.
5. Registrar não é autenticar
Registrar um servidor diz ao host onde ele está e em que escopo vale; autenticar concede permissão para usá-lo. Foi a confusão entre as duas coisas que produziu o .mcp.json com token colado na fintech. No Claude Code, o .mcp.json de projeto vai para o controle de versão, então o segredo precisa sair do arquivo, seja com ${VAR}, com um headersHelper ou com OAuth. Os servidores de projeto pedem aprovação em sessões interativas, mas carregam sem confirmação em claude -p e no Agent SDK.
O .mcp.json abaixo autentica o servidor interno por SSO, com um script mantido fora do repositório, e o servidor do parceiro por OAuth, com escopo de leitura fixado:
.mcp.json sem segredos
Do lado do protocolo, o servidor MCP remoto atua como servidor de recurso OAuth 2.1. O token vai sempre no cabeçalho Authorization, nunca na URL, e o servidor só aceita tokens emitidos para ele. A especificação proíbe repassar o token recebido a outros serviços, prática conhecida como token passthrough. As boas práticas de segurança também apontam como erro comum publicar todos os escopos possíveis ou usar escopos curinga, como * ou full-access.
6. Confiança e risco
Uma tool MCP pode trazer annotations, dicas que o servidor declara sobre o comportamento dela: se é somente leitura, destrutiva, idempotente ou de mundo aberto. São declarações, não garantias. A especificação obriga o client a tratá-las como não confiáveis, a menos que venham de um servidor confiável, e o blog oficial do MCP lembra que um servidor pode declarar readOnlyHint: true e, mesmo assim, apagar seus arquivos.
Use essas dicas para dispensar a confirmação em tools de leitura de um servidor confiável e para avisar o usuário antes de uma tool destrutiva. A proteção real vem de sandbox, controle de rede e autorização no servidor.
O risco também não está numa tool isolada. O mesmo blog recorre à lethal trifecta (trindade letal), conceito de Simon Willison que reúne acesso a dados privados, exposição a conteúdo não confiável e capacidade de comunicação externa. Quando as três condições se juntam na mesma sessão, abrem caminho para o roubo de dados. O risco, portanto, é da sessão, e não de um servidor específico.
Por fim, o MCP Registry cataloga servidores públicos, mas não faz curadoria nem garante moderação. Já os servidores do repositório modelcontextprotocol/servers são exemplos educacionais, não implementações prontas para produção.
O que evitar
Uma tool por endpoint, com descrição de uma linha. Projete as tools para os fluxos do agente, com descrições de pelo menos três ou quatro frases.
Erro devolvido como sucesso. Sem isError/is_error, a frase de erro vira dado.
Forçar a tool com any ou tool nos modelos listados na seção 2. A API retorna erro 400; use auto com strict: true.
Dado pessoal em schema strict. O schema fica em cache por até 24 horas.
Credencial no .mcp.json, token na URL, token passthrough e escopo curinga. Use ${VAR}, headersHelper ou OAuth.
Agente com tools e escopos que ele não usa. Comece pelo mínimo e eleve sob demanda.
Tratar annotations ou o Registry como garantia. Nenhum dos dois protege por si só.
Este artigo faz parte de uma série assinada por arquitetos do corpo técnico da Duranium.
Glossário
Agente: aplicação em que o modelo decide, a cada passo, qual tool chamar e com quais parâmetros, até concluir a tarefa.
Annotations: dicas que um servidor MCP declara sobre o comportamento de uma tool, como somente leitura (readOnlyHint) ou destrutiva. Não são garantias.
Client: componente que o host cria para se comunicar com um único servidor MCP.
Contexto: tudo o que o modelo lê numa requisição, incluindo instruções, definições de tools, mensagens e resultados.
Enum: lista fechada de valores aceitos por um campo.
Escopo: recorte da permissão concedida a um token, como a leitura de documentos.
Host: aplicação que o usuário enxerga e que coordena a conversa com os servidores MCP, como o Claude Code.
MCP (Model Context Protocol): protocolo aberto que padroniza como aplicações expõem tools, resources e prompts a modelos de linguagem.
OAuth 2.1: padrão de autorização em que a aplicação obtém tokens de acesso com escopos definidos, sem lidar com a senha do usuário.
Prompts (MCP): modelos de mensagem que o servidor oferece e que o usuário aciona.
Resources (MCP): dados que o servidor disponibiliza e que a aplicação decide incluir no contexto.
Schema (JSON Schema): especificação que define os campos, os tipos e as restrições de um objeto JSON, como os parâmetros de entrada de uma tool.
Servidor MCP: programa que expõe tools, resources e prompts por meio do MCP.
Strict tool use: modo da Claude API, ativado com strict: true, que garante que o input da chamada siga o schema da tool.
Structured outputs: recurso da Claude API que faz a resposta do modelo seguir um JSON Schema, sem passar por uma tool.
System prompt: instruções gerais que orientam o modelo durante toda a conversa.
Token passthrough: repasse, a outros serviços, do token recebido por um servidor. A especificação do MCP proíbe essa prática.
Tool: função que o modelo pode chamar, descrita por nome, descrição e schema de entrada.
tool_choice: parâmetro da Claude API que define se o modelo deve chamar uma tool, e qual.
Tool search: recurso que carrega a definição de uma tool apenas quando uma busca a encontra, para economizar contexto.
Referências
Model Context Protocol (revisão 2026-07-28)
Claude API
Claude Code
Anthropic Engineering
Autor: Leonardo Coli de Aguiar
Claude Certified Architect – Foundations · Duranium
Coautoria: Maria Tereza Barros Araújo
Claude Certified Architect – Foundations · Duranium
Revisão técnica: Rafael Ladislau
Claude Certified Architect – Foundations · Duranium
Bernardo Ramos
Claude Certified Architect – Foundations · Duranium







