Como revisar nomes de ferramentas duplicados em conexões MCP do Claude

Dois servidores MCP com a mesma ferramenta, ou com nomes parecidos, colocam o modelo diante de uma escolha ambígua. Ele não sabe que existe um CRM e um ERP por trás dos nomes: recebe uma lista plana e decide por nome, descrição e contexto. A revisão correta junta quatro movimentos: inventariar os nomes publicados, padronizar prefixos por sistema, reescrever descrições que expliquem o limite de cada ferramenta e testar com perguntas reais antes de liberar o conector para o time.

O problema é estrutural. O nome identifica a ferramenta dentro do servidor que a publica, mas o protocolo não define namespace global. Como o host reúne tudo na mesma requisição, buscar_cliente pode existir no CRM, no ERP e no data warehouse ao mesmo tempo. Quem administra o conector resolve isso na origem.

Resumo rápido

• O nome da ferramenta é único dentro do servidor MCP, não entre servidores conectados ao mesmo host.
• O modelo escolhe por nome e descrição. O campo server_name aparece na resposta, não na decisão.
• A precisão de seleção cai quando o catálogo cresce. A documentação do tool search cita degradação acima de 30 a 50 ferramentas.
• Prefixo por sistema (crm_, erp_, dw_) resolve colisão e facilita allowlist e auditoria.
• Descrição boa diz o que a ferramenta faz, o que ela não faz e qual é a alternativa.
• Teste com perguntas ambíguas e confira nos logs qual ferramenta e qual servidor foram chamados.

Como o modelo escolhe entre nomes parecidos

O cliente descobre o catálogo com tools/list e invoca com tools/call, enviando nome e argumentos. Cada definição traz name, description, inputSchema e, quando houver, outputSchema e anotações. O modelo lê esses metadados para decidir o que chamar e como preencher os argumentos. A lista que chega até ele soma ferramentas nativas e de todos os servidores habilitados, sem hierarquia visível e sem garantia de unicidade entre origens.

A escala agrava o quadro. A documentação do tool search tool afirma que a escolha da ferramenta certa degrada depois de 30 a 50 opções. Nome duplicado é o caso extremo: não há como acertar por dedução quando duas opções descrevem o mesmo verbo.

Quando o Claude usa uma ferramenta de MCP, o bloco de resposta traz name e server_name. Isso mostra depois qual servidor respondeu, mas a escolha já aconteceu, com base em nome e descrição. Anotações também não salvam a seleção: a especificação manda tratá-las como não confiáveis, a menos que venham de servidores confiáveis.

Os quatro tipos de colisão

Nem toda colisão é igual. Separar por tipo evita tratar como bug o que é apenas nomenclatura frouxa, e evita tratar como detalhe o que pode gerar escrita no sistema errado.

O nome idêntico é o mais fácil de detectar e o mais difícil de conviver. Em leitura, custa tempo e confiança. Em escrita, pode duplicar cadastro, disparar mensagem para o cliente errado ou alterar registro indevido. A triagem considera o efeito, não só a frequência. O nome parecido passa em revisão manual: plural, acento e abreviação criam pares que parecem distintos para quem escreveu. Já a colisão entre nativa e MCP tem custo próprio, porque a nativa tem limites conhecidos e o modelo pode preferi-la sem saber que o dado necessário está do outro lado.

Checklist de auditoria e convenção de prefixo

A auditoria começa antes da renomeação. Sem inventário, a discussão vira opinião sobre qual nome é mais bonito. O roteiro cabe em uma planilha e deve ser repetido a cada servidor novo.

1. Exporte o catálogo de cada servidor. Chame tools/list e guarde nome, descrição, campos obrigatórios e servidor. A listagem suporta paginação, então percorra todas as páginas.
2. Normalize antes de comparar. Minúsculas, hífen e espaço como sublinhado, sem acentos. Compare a forma normalizada.
3. Marque colisões exatas. Nome igual em servidores diferentes é bloqueante. Nome igual entre servidor e nativa também.
4. Marque quase colisões. Agrupe por raiz do verbo, substantivo e plural. O que sobrar é candidato a renomeação.
5. Confirme a allowlist contra a realidade. A documentação do conector avisa que nome inexistente em configs gera apenas aviso no backend, sem erro. Allowlist quebrada passa despercebida.
6. Atribua um dono por ferramenta. Sem dono, ninguém decide o nome nem responde quando o modelo erra.
7. Classifique o efeito. Leitura, escrita, exclusão e envio externo exigem testes diferentes.
8. Registre a decisão. Nome antigo, nome novo, motivo, data e quem aprovou.

A convenção de prefixo precisa ser curta, estável e óbvia. Prefixo longo rouba espaço do nome, e prefixo que muda quebra histórico e allowlist. A tabela é ponto de partida, não regra do protocolo.

Duas decisões acompanham o prefixo: um verbo por intenção, sem misturar idiomas, e nome que diga o objeto, não a implementação. erp_listar_pedido envelhece bem; erp_query_v2_endpoint descreve o código. Prefixos ainda agrupam allowlist, logs e dashboards por sistema. Um guia de permissões por equipe está em permissões de conectores do Claude para equipes.

Descrição ruim x descrição que desambigua

A descrição é o campo que o modelo lê para diferenciar duas ferramentas de nome parecido. Ela responde três perguntas: qual base responde, o que a ferramenta faz e o que ela não faz. Descrição curta empurra a decisão para o nome, justamente a parte ambígua.

Descrição ruim, em um servidor de CRM e outro de ERP, ambos com buscar_cliente:

Busca clientes.

Descrição que desambigua, no servidor de CRM:

Consulta o cadastro de clientes no CRM pelo nome, CPF/CNPJ ou e-mail.
Retorna razão social, nome fantasia, contatos e status do cadastro.
Somente leitura. Não traz pedidos, notas fiscais ou títulos financeiros.
Para pedidos e valores, use erp_listar_pedido.

Descrição que desambigua, no servidor de ERP:

Consulta clientes cadastrados no ERP para fins fiscais e financeiros.
Aceita CNPJ ou código interno. Retorna código, situação cadastral e
limite de crédito. Não traz contatos comerciais nem histórico de
atendimento. Para relacionamento, use crm_buscar_contato.

Quatro elementos fazem a diferença: origem do dado, identificador aceito, limite explícito com o nome da alternativa e efeito da chamada. CPF, CNPJ e código interno não são intercambiáveis, e o modelo só sabe disso se o texto disser. Data em fuso local ou valor em centavos pertencem à descrição do campo.

O campo title serve para leitura humana, mas não deve ser o desempate, porque a interface pode exibir só parte do texto. Descrições também são superfície de risco, já que vêm do servidor. Revise as de terceiros como você revisa código.

Como testar antes de liberar para o time

Teste de catálogo não é teste de seleção. O primeiro confirma nomes e esquemas; o segundo, que o modelo escolhe certo quando a pergunta é ambígua. O segundo é o que pega colisão de nome.

Monte quatro baterias: caso claro, com sistema ou objeto inequívoco; caso ambíguo, como “busca o cliente 12.345.678/0001-99” sem dizer se é cadastro comercial ou fiscal; quase erro, com palavras parecidas com o nome de outra ferramenta; e negativa, com pedidos que não devem acionar nada.

1. Rode em ambiente de teste, com dados representativos e credenciais próprias.
2. Registre, para cada pergunta, ferramenta chamada, argumentos e servidor. O bloco mcp_tool_use traz name e server_name.
3. Repita variando a redação. Paráfrase que muda a decisão revela descrição fraca.
4. Compare antes e depois da renomeação, com o mesmo modelo e a mesma configuração, por tipo de pergunta.
5. Revise os logs: servidor inesperado, identificador de outro sistema e tentativa e erro.
6. Só libere quando a bateria ambígua estiver estável. Caso claro acertando não compensa caso ambíguo errando.

A especificação recomenda registrar o uso de ferramentas, mostrar a entrada ao usuário antes de operações sensíveis e manter um humano com poder de negar a chamada. Em conector de time, isso vira confirmação para escrita, log centralizado e revisão periódica. Um roteiro de separação de ambientes está em ambientes de teste e produção em MCP com Claude.

Quando não é possível renomear, porque o servidor é de terceiro ou o nome é contrato de outro time, reduza a superfície. Desabilite o que não é necessário, habilite só o conjunto do fluxo e desligue o duplicado quando apenas um servidor é fonte de verdade. Mantenha um toolset por fluxo em vez de um catálogo único para toda a empresa.

Três recursos ajudam: allowlist com default_config desligado, carregamento adiado para tirar descrições do contexto inicial e lista de ferramentas fixada no toolset para que uma mudança no servidor não altere a conversa em andamento. Nenhum substitui o prefixo, mas os três compram tempo até a correção na origem.

Se o servidor for interno, trate a renomeação como mudança de contrato: mantenha o nome antigo ativo por um ciclo, marque a versão antiga como em desuso e avise quem tem allowlist apontando para ela. Autenticação e limite de requisições também entram no teste, como descrito em autenticação e rate limiting em servidores MCP.

Exemplo: dois servidores MCP em uma rede de clínicas

Cenário hipotético, sem vínculo com empresa real. Uma rede de clínicas odontológicas conecta dois servidores ao Claude: agenda, com buscar_paciente e criar_agendamento, e prontuário, com buscar_paciente e registrar_atendimento.

Na primeira semana, a recepção pede “confirma o telefone da Maria Souza” e o modelo chama o prontuário, que devolve dados clínicos em vez do contato. Em outro atendimento, “marca retorno da Maria” aciona a ferramenta de prontuário, que não cria evento. Nenhum erro técnico aparece: as chamadas são válidas, apenas no servidor errado.

A correção começa pelo inventário. Os nomes viram ag_buscar_paciente e pront_buscar_paciente. A descrição de agenda retorna contato, convênio e horários e informa que dados clínicos ficam no prontuário. A de prontuário retorna histórico e alergias e aponta a agenda para marcar consulta.

Depois vem o teste, com “qual o telefone da Maria”, “qual o último procedimento da Maria” e “marca a Maria para quinta às 14h”, em três redações cada. O time confere no log o par nome e servidor, e a escrita fica atrás de confirmação humana até o acerto estabilizar. Com prefixo por sistema, a recepção habilita apenas agenda e leitura de cadastro, e a coordenação clínica recebe outro toolset. A colisão virou fronteira de permissão.

Erros comuns

• Confiar no aviso do backend. Nome inexistente em configs gera aviso, não erro. Compare allowlist e catálogo explicitamente.
• Renomear só de um lado. Prefixar o CRM e deixar o ERP com o nome antigo mantém a ambiguidade.
• Usar prefixo que descreve o time. Prefixo por squad muda com o organograma e quebra histórico.
• Escrever descrição genérica. “Busca clientes” serve para qualquer base. Sem limite e sem alternativa, o modelo decide pelo nome.
• Testar só o caminho feliz. Pergunta clara acerta com qualquer nome. O teste que importa é o ambíguo e o quase erro.
• Liberar escrita sem confirmação. Colisão em leitura custa retrabalho; em escrita, custa dado errado. Exija confirmação e log.

Perguntas frequentes

O MCP não resolve nomes iguais automaticamente?

Não. O nome é único dentro do servidor que publica a ferramenta, e não existe namespace global entre servidores. Cabe ao host e a quem configura o conector evitar a ambiguidade.

Preciso renomear todas as ferramentas?

Não. Renomeie quando houver colisão real, quase colisão ou risco de confusão com nativa. Catálogo pequeno e sem sobreposição pode manter o nome, desde que a descrição seja específica.

Mudar o nome quebra a allowlist?

Sim. A configuração por ferramenta usa o nome como chave. Ao renomear, atualize allowlist e denylist na mesma publicação e mantenha o nome antigo ativo durante a transição.

Posso usar o campo title para diferenciar?

Pode, mas não conte com ele como desempate. O modelo trabalha com nome e descrição. Use title para leitura humana e coloque a informação decisiva no corpo da descrição.

O que fazer se o servidor de terceiro não aceita renomear?

Reduza a superfície com allowlist, desligue duplicados, separe toolset por fluxo e use descrição e prompt de sistema para orientar a escolha. Registre a limitação e acompanhe a taxa de erro.

Fontes e leitura recomendada

• Especificação MCP: Tools, com name, description, tools/list, paginação e segurança
• MCP: arquitetura, host, clientes e a relação de um cliente por servidor
• Anthropic: conector MCP, toolset, allowlist, denylist e aviso para nome inexistente
• Anthropic: tool search tool, limite prático de ferramentas e busca por nome e descrição
• Claude Help Center: conectores, permissões herdadas e múltiplos apps na mesma conversa
• Repositório oficial da especificação MCP, com histórico de mudanças