Nomeação de ferramentas MCP: 6 padrões classificados pela sobrevivência a refatores

O que acontece com seu agente quando a equipe renomeia usuários para contas, e por que o nome da ferramenta que você escolheu há seis meses decide se algo quebra

Resumo: Eu enviei servidores MCP onde os nomes das ferramentas eram uma camada fina sobre a API REST subjacente, e eu enviei servidores onde os nomes vieram do modelo de domínio. Os que tinham nomes de domínio sobreviveram a refatores de backend com quase zero de churn. Os que eram pass-through quebraram toda vez que alguém renomeou uma tabela ou dividiu um serviço. Após classificar seis padrões de nomenclatura por dois eixos (quão bem um nome sobrevive a um refatoramento do sistema subjacente e quão claramente o modelo pode escolher a ferramenta certa), minha escolha é a nomenclatura de linguagem ubíqua dentro de um prefixo de contexto delimitado, com tipos de retorno de união discriminada do Pydantic fazendo o trabalho do esquema. A versão em uma linha da minha opinião: Design Orientado a Domínio mais esquemas de uso de ferramentas é a solução de produção para agentes. A camada MCP é onde a camada anti-corrupção pertence, não um pensamento posterior que você adiciona depois.

Uma nota rápida de escopo. Vou usar um reembolso como exemplo de nomenclatura ao longo do texto, porque todos têm um modelo mental do que é um reembolso. Não estou descrevendo um sistema que permite que um modelo emita reembolsos por conta própria. O reembolso aqui é um substituto para qualquer operação cujo nome você tenha que escolher. Trate-o como um rótulo, não como um design de produção que estou endossando.

Os dois eixos

A sobrevivência ao refatoramento é se o nome permanece correto quando o sistema subjacente muda. Um nome com alta sobrevivência ao refatoramento descreve algo estável (uma intenção no domínio de negócios) em vez de algo volátil (a forma atual do banco de dados ou a rota REST atual).

A clareza na seleção de LLM é se o modelo escolhe de forma confiável a ferramenta certa apenas pelo nome e descrição. Nomes que são muito inteligentes, muito abstratos ou propensos a colisões fazem o modelo hesitar ou escolher errado. Este eixo às vezes recompensa os nomes literais que o primeiro eixo pune, que é toda a tensão.

A classificação que defendo, do melhor ao pior nos eixos combinados: 5, depois 6, depois 4, depois 2, depois 3, depois 1. Os padrões 5 e 6 não são rivais. Você os usa juntos.

1. Nomenclatura pass-through

O backend tem POST /users, PATCH /users/{id}, DELETE /users/{id}, então as ferramentas se tornam create_user, update_user, delete_user. Rápido de escrever, o modelo lê bem. Modo de falha: o nome está soldado à superfície atual da API. No dia em que alguém decide que um usuário é realmente uma conta, a rota subjacente muda e o nome da sua ferramenta agora é uma mentira. Se você renomear a ferramenta, cada prompt e fixture de avaliação e agente que aprendeu create_user precisa ser atualizado. Se você não fizer isso, novos engenheiros leem create_user e vão procurar uma tabela de usuários que não existe mais. Alta clareza hoje, baixa sobrevivência amanhã.

2. Verbo-primeiro

process_refund, cancel_subscription, send_invoice. A ação lidera, o que é bom porque a seleção da ferramenta é fundamentalmente um problema de correspondência de verbos. Um bom verbo muitas vezes descreve a intenção em vez do transporte, então um refatoramento de backend pode deixar o nome intacto. Modo de falha: verbos colidem e se desviam à medida que a superfície cresce. Você adiciona process_payment, process_payout, process_chargeback, e agora process carrega quatro significados. process é um verbo fraco, então as pessoas o usam sempre que não conseguem pensar na palavra precisa. Sobrevivência média, alta clareza que decai à medida que a contagem de ferramentas aumenta.

3. Substantivo-primeiro, recurso-ponto-ação

refund.create, subscription.cancel. Agrupa bem para um humano navegando pela lista. Modo de falha: otimiza para a taxonomia de recursos à custa da coisa que o modelo faz melhor, correspondência de verbos. Com a ação em segundo lugar, o modelo lê refund primeiro e tem que segurá-lo antes do verbo que diz o que fazer. O agrupamento também tenta você a entrar em CRUD-sobre-recursos quando a operação de domínio que você deseja é mais rica do que criar/atualizar/excluir. O padrão que menos utilizo.

4. Prefixo de domínio com um contexto delimitado

billing.refund.process, identity.account.deactivate. O primeiro segmento nomeia o contexto delimitado (o termo vem do Design Orientado a Domínio): a parte do negócio onde essa ferramenta vive. Nomes que significam algo: um billing.transfer e um inventory.transfer permanecem separados tanto para o modelo quanto para o leitor. E um contexto delimitado é um conceito deliberadamente estável, então o prefixo sobrevive a refatores que destroem nomes pass-through. Modo de falha: o prefixo é tão bom quanto seus limites de contexto, e a maioria das equipes não os desenhou. Se billing, payments e invoicing são três prefixos sobrepostos que ninguém consegue distinguir, você adicionou cerimônia sem clareza. A outra falha é a verbosidade. Usado com limites reais é excelente. Usado como decoração é pior do que um nome de verbo plano.

5. Nomenclatura de linguagem ubíqua

A que defenderei com mais afinco. Nomeie a ferramenta após a palavra que os especialistas do domínio realmente usam, não o verbo do banco de dados. Não a chame de delete_account. Em quase todos os domínios reais de faturamento ou identidade, você não exclui uma conta, você a desativa ou fecha, e a linha permanece para conformidade e auditoria. Portanto, a ferramenta é deactivate_account, e esse nome codifica um fato verdadeiro sobre o domínio que delete oculta. Duas coisas boas acontecem: o modelo obtém um verbo preciso (deactivate é muito menos propenso a colisões do que delete ou process), e o nome permanece correto em refatores porque o significado comercial não muda quando você troca o banco de dados. Modo de falha: requer que uma linguagem ubíqua realmente exista, e em muitas equipes não existe, ou há três dialetos concorrentes. E há um custo de disciplina: alguém tem que resistir ao fácil delete e insistir no preciso deactivate na revisão de código, toda vez.

6. Schema-primeiro com uniões discriminadas do Pydantic

Os primeiros cinco padrões são sobre o nome. Este é sobre o tipo de retorno, e é onde está a alavancagem real. Um esquema de retorno vago (um dicionário simples, um blob stringificado) desfaz toda a disciplina que você colocou no nome. Uma união discriminada permite que uma ferramenta retorne vários resultados claramente distintos, cada um com sua própria forma tipada, marcada por um campo literal que o modelo pode ramificar.

from typing import Literal, Annotated, Union
from decimal import Decimal
from pydantic import BaseModel, Field

class RefundIssued(BaseModel):
status: Literal["issued"] = "issued"
refund_id: str
amount: Decimal
currency: str = Field(min_length=3, max_length=3)

class RefundPending(BaseModel):
status: Literal["pending_review"] = "pending_review"
request_id: str
reason: str

class RefundRejected(BaseModel):
status: Literal["rejected"] = "rejected"
code: Literal["already_refunded", "outside_window", "amount_exceeds_charge"]
message: str

RefundOutcome = Annotated[
Union[RefundIssued, Refund