Descrições de ferramentas MCP que evitam erros em produção

Uma descrição de ferramenta MCP pode impedir uma chamada insegura em produção antes que ela comece ou esconder o perigo atrás de um verbo amigável. A maioria das ações acidentais em produção não começa quando um agente decide causar dano. Elas começam quando uma descrição vaga faz uma ferramenta destrutiva parecer intercambiável com uma ferramenta de inspeção.

Escreva a descrição de toda ferramenta que altera estado como um pequeno contrato operacional: indique o sistema-alvo, o efeito colateral e a exigência de confirmação. Se uma dessas informações faltar, a descrição pede que o modelo deduza um limite de segurança que o seu código deveria ter deixado explícito.

Já analisei interfaces de ação suficientes para desconfiar de rótulos como «gerenciar», «sincronizar», «implantar» e «limpar». Eles são convenientes para quem escreve e caros para quem precisa explicar por que uma solicitação de teste chegou a uma conta ativa. Uma boa descrição torna os detalhes incômodos impossíveis de ignorar.

Uma descrição de ferramenta é um aviso de execução, não texto de produto

As descrições de ferramentas MCP devem informar ao agente e ao operador humano o que acontecerá se a chamada for bem-sucedida. Elas não devem vender a capacidade, resumir um subsistema interno nem repetir o nome da ferramenta em uma frase mais longa.

O esquema de ferramentas do Model Context Protocol inclui uma description legível por humanos ao lado do nome da ferramenta e de inputSchema. A especificação MCP também permite anotações como readOnlyHint e destructiveHint. Essas anotações ajudam um cliente a apresentar as ferramentas, mas a especificação diz que os clientes devem tratá-las como dicas. Elas não são verificações de permissão. Por isso, a descrição continua sendo o lugar onde o operador pode ler a consequência real antes que a chamada chegue ao seu serviço.

Considere estas duas definições:

{
  "name": "delete_backup",
  "description": "Deletes a backup.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": { "type": "string" }
    },
    "required": ["backup_id"]
  }
}

{
  "name": "delete_production_backup",
  "description": "Permanently deletes one backup from the Production PostgreSQL backup store. This removes a recovery point and cannot be undone. Ask the user to confirm the backup ID and its timestamp before calling this tool.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "backup_id": {
        "type": "string",
        "description": "Immutable backup ID returned by list_production_backups."
      }
    },
    "required": ["backup_id"],
    "additionalProperties": false
  },
  "annotations": {
    "destructiveHint": true,
    "readOnlyHint": false
  }
}

A segunda definição faz mais do que parecer cautelosa. Ela informa o alvo, o resultado irreversível, uma forma segura de identificar o objeto e uma pausa obrigatória na conversa. Também dá ao revisor informações suficientes para rejeitar uma chamada antes de investigar os detalhes da implementação.

Não presuma que um verbo forte resolva o problema. «Destruir» alerta mais do que «excluir», mas ainda não diz qual conta será afetada, que tipo de dado está envolvido nem como a ferramenta trata a confirmação. A descrição precisa fornecer esse contexto.

Coloque o sistema-alvo na primeira frase

A primeira frase deve identificar o sistema exato afetado, incluindo o ambiente ou o limite da conta. Uma ação contra «o banco de dados» pode significar um contêiner local descartável, um serviço de teste compartilhado, um tenant de staging ou o livro-caixa de clientes em produção. São ações diferentes, mesmo quando o endpoint da API é o mesmo.

Use nomes que o operador reconheça no próprio trabalho. Diga «conta de pagamentos de produção», «cluster Kubernetes de staging», «tenant do cliente northwind» ou «branch de release do repositório mobile-api». Evite apelidos internos, a menos que todos os operadores pretendidos os conheçam e o nome apareça nos argumentos.

Esta ordem funciona porque coloca o risco antes da mecânica:

[Target system]. [Action and result]. [Confirmation rule].

Por exemplo:

Production identity directory. Disables the selected user account and ends active sessions. Ask the user to confirm the username before calling.

O alvo precisa corresponder ao handler, não à intenção de quem escreveu a ferramenta. Se a ferramenta aceita um argumento environment, uma descrição que afirma «Atualiza staging» se torna falsa no momento em que alguém passa production. Divida a operação em ferramentas específicas por ambiente ou diga claramente o que o argumento permite.

Uma divisão costuma ser mais fácil de operar:

list_staging_feature_flags
set_staging_feature_flag
list_production_feature_flags
request_production_feature_flag_change

O design pode parecer repetitivo. Repetição custa menos do que um seletor de ferramentas decidir que set_feature_flag parece adequado e descobrir só depois que um argumento opcional apontava para produção.

Os nomes merecem a mesma disciplina, mas não conseguem carregar todo o aviso. Listas de ferramentas truncam nomes. Às vezes os agentes se concentram na descrição ao escolher entre nomes parecidos. Sob pressão, as pessoas examinam os dois. Coloque o alvo nos dois lugares quando couber e faça a descrição continuar completa se o nome desaparecer da tela.

Há uma exceção: uma ferramenta que recebe uma URI de recurso imutável cujo host já fixa o ambiente. Mesmo assim, informe o host ou a classe da conta na descrição. Um UUID não diz a um ser humano se identifica um registro de desenvolvimento ou um cliente real.

Declare o efeito colateral como um resultado concluído

Uma descrição segura informa como o mundo ficará depois do sucesso. Isso obriga quem escreve a distinguir uma observação de uma mudança, uma alteração reversível de uma permanente e uma solicitação de sua execução.

Compare o verbo vago «gerenciar»:

Manages service deployments.

Ele esconde resultados muito diferentes. Uma ferramenta de implantação pode criar uma release, promover uma release existente, reiniciar instâncias, alterar a distribuição de tráfego, reverter código ou apenas consultar o status. Cada operação merece sua própria ferramenta quando tem um modo de falha ou uma regra de aprovação diferente.

Use um resultado explícito:

Creates a deployment request for the Production catalog service. It does not change running instances. A release manager must approve the request in the deployment system.

Ou:

Changes Production catalog traffic so the specified release receives 100 percent of requests. Existing requests may finish on the prior release. Ask the user to confirm the release version before calling.

A diferença entre criar uma solicitação e executá-la importa mais do que a diferença entre HTTP POST e PATCH. Um objeto de solicitação ainda pode criar trabalho, consumir uma cota ou avisar pessoas, portanto descreva também esse efeito. Mas não o chame de implantação ativa se ele apenas abre um item para aprovação.

Evite eufemismos. «Aposentar» pode significar arquivar, desativar, excluir ou encerrar uma cobrança. «Limpar» pode significar remover arquivos temporários ou excluir a única cópia mantida de uma exportação de cliente. Escreva o verbo e o objeto reais: exclui, desativa, alterna, promove, transfere, envia, cobra ou publica.

Para operações com efeitos atrasados, indique o atraso. Uma alteração de DNS pode se propagar depois que a API retorna. A remoção de um usuário pode interromper o acesso futuro enquanto preserva os registros de auditoria. A rotação de uma credencial pode invalidar clientes que ainda usam o segredo antigo. O agente precisa desse contexto para decidir se deve primeiro inspecionar sistemas dependentes.

As descrições também devem mencionar o escopo relevante quando uma única chamada afeta muitos objetos. «Exclui o registro selecionado» é diferente de «Exclui todos os registros correspondentes à consulta fornecida». Um endpoint em lote escondido atrás de um verbo no singular causa problemas previsíveis.

A linguagem de confirmação deve descrever um controle real

Uma frase de confirmação só é útil quando a implementação e o processo operacional a respeitam. Escrever «requer confirmação» em uma ferramenta cujo handler executa imediatamente é encenação, e os agentes acabarão expondo isso.

Há três padrões distintos, e as descrições devem indicar qual deles você realmente usa.

1. O agente pergunta ao usuário na própria conversa e depois chama a ação. Isso depende de o agente seguir a descrição e não impede um cliente modificado ou descuidado.
2. A ferramenta cria uma solicitação para outra pessoa ou sistema aprovar. A chamada tem um efeito colateral, mas a alteração de produção descrita aguarda.
3. Um gateway de execução pausa a ação e exige aprovação humana antes de enviar credenciais ou contatar o sistema-alvo.

Não reduza esses padrões a «confirmação obrigatória». Eles oferecem proteções e evidências de auditoria diferentes.

Use verbos que indiquem o ator e o momento:

Before calling, ask the user to confirm the repository name and release tag.

Calling this tool submits a change request. The deployment system requires a release manager to approve it before any production release begins.

This action gateway asks a human to approve every call before it sends the request to the Production payments API.

A última formulação descreve um limite aplicado pelo sistema. A primeira descreve uma instrução para o agente. As duas podem ser adequadas, mas não são equivalentes.

Nunca diga ao agente para pedir uma confirmação vaga. Informe quais fatos a pessoa precisa aprovar. Para uma exclusão, podem ser o nome do recurso, a conta e o status de retenção. Para uma transferência, origem, destino, valor e moeda. Para uma release, serviço, versão e escopo do tráfego. A descrição não deve exigir um ritual; deve pedir os fatos que detectam um alvo errado.

Uma regra de confirmação também precisa de escopo. «Obtenha aprovação antes de alterações em produção» é fraco quando uma única sessão pode executar dez chamadas depois de uma aprovação. Se o controle real aprova um processo durante toda a sua vida útil, explique isso na documentação do produto e não afirme que cada chamada recebe uma pausa individual.

Alegações de somente leitura falham quando os handlers fazem trabalho oculto

Chame uma ferramenta de somente leitura apenas quando o handler não alterar intencionalmente o sistema-alvo. A palavra descreve o comportamento, não o método HTTP, o nome da permissão no banco de dados nem as esperanças de quem escreveu a ferramenta.

Uma requisição GET pode atualizar uma sessão, alterar um campo de último acesso, gerar uma exportação, iniciar um trabalho de relatório ou acionar o preenchimento de um cache com custo relevante. Uma requisição POST pode ser inofensiva se avaliar uma simulação e não persistir nada. Inspecione o handler e as chamadas posteriores antes de escolher o rótulo.

A anotação MCP readOnlyHint é útil para um cliente que queira reduzir o atrito em ferramentas de inspeção. Ainda é apenas uma dica, portanto o servidor precisa impor seu próprio limite. Mais importante, a descrição deve informar qualquer exceção que surpreenda um operador.

Esta descrição é enganosa:

Read-only tool for checking invoice status.

Ela falha se o endpoint criar um evento de visualização, atualizar um token de terceiros ou iniciar um cálculo remoto. Uma forma mais honesta seria:

Retrieves the current status of one Production invoice. It does not edit the invoice or charge the customer. The billing provider records this request in its access log.

Um registro de acesso normalmente é aceitável para uma ação de inspeção. Ele se torna relevante quando o alvo tem regras de conformidade, custo por consulta ou um fluxo de trabalho que reage às leituras. Declare esses efeitos sem transformar toda descrição em um aviso jurídico.

Mantenha simulações separadas da execução sempre que possível. Uma ferramenta deploy com um booleano dry_run cria dois perfis de segurança dentro da mesma definição. Os agentes podem omitir um padrão, interpretar errado se o servidor o respeita ou reutilizar um payload sem alterá-lo. plan_production_deployment e execute_production_deployment tornam a diferença visível na seleção de ferramentas, nos logs e nas revisões.

A mesma regra vale para ferramentas de validação. «Validar configuração» parece seguro, mas alguns provedores alocam um recurso ou contatam uma dependência ativa durante a validação. Se isso ocorrer, descreva a operação como uma ação e aplique a regra de confirmação relevante.

Uma ferramenta ampla cria erros de aprovação

As ferramentas devem agrupar operações por consequência e limite de aprovação compartilhados, não pela conveniência de um único cliente de API. Uma ferramenta administrativa genérica transforma as descrições em um catálogo de exceções que nem um modelo nem uma pessoa lerão de forma confiável.

Este é o padrão a evitar:

{
  "name": "admin",
  "description": "Administer users, deployments, secrets, and configuration across environments.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": { "type": "string" },
      "environment": { "type": "string" },
      "payload": { "type": "object" }
    },
    "required": ["operation", "environment", "payload"]
  }
}

Essa definição destrói a unidade útil de revisão. Um revisor não consegue saber pelo cartão da ferramenta se a chamada consultará o status, alternará credenciais ou excluirá um usuário. A string operation leva a semântica importante para um argumento posterior, fácil de ignorar.

Divida por intenção e risco:

get_production_deployment_status
plan_production_deployment
submit_production_deployment_request
rotate_production_service_credential
create_production_user_access_request

Você não precisa de uma ferramenta para cada endpoint. Precisa de ferramentas separadas quando o alvo, o efeito colateral ou a confirmação mudam. Uma ferramenta em lote pode continuar sendo uma ferramenta em lote se sempre atingir o mesmo tipo limitado de recurso e exigir sempre a mesma aprovação. A descrição deve dizer que ela pode afetar vários objetos e mostrar como o chamador limita a seleção.

Os argumentos também precisam de descrições. A descrição da ferramenta explica o que a operação faz; as descrições dos argumentos restringem as escolhas perigosas. Use enums para ambientes e tipos de ação quando puder. Rejeite valores desconhecidos no servidor. Não coloque «production» em uma string livre e confie que a descrição salvará você.

Uma ferramenta restrita também produz registros de auditoria melhores. Quando o diário diz rotate_production_service_credential, o investigador entende a classe da ação antes de abrir os argumentos. Quando diz admin, é preciso reconstruir a intenção a partir do payload.

Escreva a descrição antes do handler

Criar o contrato operacional antes da implementação expõe requisitos vagos enquanto ainda é barato mudar a interface. Se você não consegue escrever uma frase simples sobre o resultado concluído, ainda não tem um limite de ferramenta estável.

Use esta sequência de revisão para toda ferramenta de ação:

1. Escreva o alvo como um operador o identificaria, incluindo ambiente, conta ou tenant.
2. Escreva o resultado concluído com um verbo literal e diga se a alteração pode ser revertida.
3. Indique quem confirma, em que ponto ocorre a aprovação e se ela vale por chamada ou por sessão.
4. Compare a frase com o comportamento do handler, os padrões, as tentativas e as APIs posteriores.
5. Adicione descrições aos argumentos de identificadores, controles de escopo e qualquer valor que altere o alvo.

O quarto item detecta falhas que uma documentação bem acabada pode esconder. Tentativas repetidas podem fazer uma cobrança ou mensagem ocorrer duas vezes se a solicitação posterior não usar um mecanismo de idempotência. Padrões podem transformar um environment omitido em produção. Um handler pode resolver um nome amigável para vários recursos. A descrição não corrige esses erros de implementação, mas escrevê-la os traz à tona.

Um teste interno útil é remover o nome da ferramenta e mostrar apenas a descrição e o esquema de entrada a outro engenheiro. Peça que ele preveja o que acontecerá depois de uma chamada bem-sucedida e que aprovação espera. Se a resposta diferir do handler, corrija o contrato ou o código.

Teste também prompts de linguagem comum. «Limpe os dados antigos», «coloque a nova versão no ar» e «corrija a conta do Jordan» são exatamente o tipo de solicitação que torna uma ferramenta ampla tentadora. Um agente seguro deve usar primeiro uma ferramenta de inspeção, pedir um identificador ausente ou apresentar a ação concreta para aprovação. Se ele conseguir saltar desse prompt para uma exclusão em produção, a falha começa no design da interface, muito antes de o comportamento do modelo entrar em cena.

Mensagens de erro e resultados devem preservar o limite de segurança

Uma descrição cuidadosa perde grande parte do valor quando o resultado da ferramenta esconde o alvo executado ou quando um erro convida o agente a tentar uma ação mais ampla. Retorne evidências suficientes para que o agente e o operador verifiquem o que aconteceu.

Para uma alteração de estado bem-sucedida, retorne o identificador canônico do alvo, a ação realizada e o estado resultante. Não responda apenas com ok.

{
  "status": "completed",
  "target": {
    "environment": "production",
    "service": "catalog",
    "release": "2025.06.14-3"
  },
  "action": "traffic_promoted",
  "traffic_percent": 100,
  "request_id": "relreq_8a2f"
}

Em uma pausa para aprovação, diga que nada chegou ao alvo. Essa distinção impede que um agente tente compensar uma chamada que apenas aguarda uma pessoa.

{
  "status": "approval_required",
  "action": "rotate_production_service_credential",
  "target": "production/catalog-api",
  "executed": false,
  "approval_scope": "this call"
}

Os erros exigem o mesmo cuidado. «Proibido» é tecnicamente correto e operacionalmente inútil. Informe se o alvo foi rejeitado, se o ambiente era inválido, se faltava aprovação ou se a solicitação falhou depois de chegar ao sistema remoto. Nunca exponha um segredo nessa explicação e nunca aconselhe o agente a repetir cegamente uma solicitação que altera estado.

A idempotência merece um resultado visível para ações relevantes externamente. Se ocorrer um timeout depois que um serviço remoto aceitou uma transferência ou criou uma release, o agente precisa consultar o status da solicitação usando um ID estável. O caminho de repetição não deve adivinhar. As descrições não expressam todas as regras de repetição, mas uma ferramenta que faz chamadas irreversíveis deve ter uma ferramenta de status complementar e um formato de resultado que permita a recuperação.

As descrições precisam de aplicação por trás delas

A linguagem simples reduz seleções inadequadas, mas não consegue impedir um processo que já possui um token de produção irrestrito. Coloque as credenciais e a ação de rede final atrás de um limite capaz de negar, aprovar e registrar a chamada.

O Sallyport usa essa estrutura para agentes conectados ao MCP: o agente usa o shim sp mcp incluído, enquanto o app mantém as credenciais de API e SSH em seu cofre criptografado e executa sozinho as ações aprovadas. A autorização por sessão e as aprovações opcionais de chaves por chamada transformam a confirmação em um comportamento aplicado pelo sistema, em vez de um pedido de boa educação.

Isso não justifica um design fraco de ferramentas. O gateway vê a chamada que chega. O esquema da sua ferramenta ainda decide se a chamada diz «excluir este backup de produção» ou esconde a exclusão atrás de uma operação admin genérica. Faça a validação dos argumentos no handler, restrinja as credenciais ao alvo pretendido quando o sistema remoto permitir e mantenha um registro de auditoria que identifique o processo e a ação.

As orientações de autorização do Model Context Protocol reforçam o mesmo ponto em outra camada: a autorização pertence a um fluxo de protocolo com verificações explícitas, não a uma instrução para o modelo. Trate as descrições como um contrato legível por humanos. Trate a autorização do servidor, a custódia das credenciais e a aprovação como os controles que tornam esse contrato verdadeiro.

Escolha a ferramenta mais perigosa que você expõe hoje e reescreva a descrição sem olhar para o nome. Se não conseguir indicar o alvo de produção, o efeito colateral concluído e o escopo da aprovação em duas ou três frases diretas, ainda não ofereça essa ferramenta a um agente autônomo.