As ferramentas dão ao ChatGPT e ao Codex acesso às ações e aos dados que o servidor MCP de um plugin oferece. Defina as ferramentas depois de levantar possíveis casos de uso e antes de implementar o servidor.
Cada ferramenta deve ajudar o usuário a alcançar um objetivo. Antes de reproduzir uma API interna, considere como as pessoas vão solicitar e usar a funcionalidade.
Associe os casos de uso às ferramentas
Para cada caso de uso compatível, siga estas etapas.
- Descreva o resultado que o usuário espera.
- Liste as informações necessárias para produzir esse resultado.
- Identifique as operações de leitura e escrita ou as ações externas que o servidor precisa executar.
- Agrupe as operações que, juntas, representam uma única ação.
- Separe as operações quando houver diferenças nas permissões, nos riscos de segurança ou nos requisitos de confirmação.
Um plugin de gerenciamento de projetos, por exemplo, pode oferecer as seguintes ferramentas.
list_projectspara localizar projetos.get_projectpara consultar os detalhes de um projeto.create_projectpara criar um projeto.update_projectpara alterar os detalhes de um projeto.archive_projectpara arquivar um projeto, uma alteração de estado com consequências importantes.
Separe as operações de leitura das de escrita para que o modelo e o usuário possam distinguir as consultas de informações das ações que alteram o estado.
Defina o contrato de cada ferramenta
Documente os campos a seguir para cada ferramenta proposta.
| Campo | O que definir |
|---|---|
| Nome | Um identificador estável que indique a ação. |
| Título | Uma descrição breve da ação em linguagem clara. |
| Descrição | O objetivo do usuário e as condições em que a ferramenta deve ser acionada. |
| Schema de entrada | Parâmetros obrigatórios e opcionais, tipos, valores permitidos e limites. |
| Schema de saída | Campos estruturados que o modelo pode consultar e reutilizar. |
| Autorização | A conta, a função ou a permissão de acesso ao recurso que o servidor deve verificar. |
| Efeitos colaterais | Dados ou estado de sistemas externos que a ferramenta pode alterar. |
| Comportamento em caso de falha | Erros que o modelo pode explicar ou dos quais pode se recuperar. |
Use entradas explícitas. Não dependa de suposições do modelo sobre identificadores, escopo da conta ou outros valores necessários para que a operação funcione corretamente.
Retorne identificadores estáveis e informações estruturadas suficientes para as chamadas seguintes. Não inclua segredos, tokens de acesso, diagnósticos internos nem dados pessoais desnecessários nos resultados.
Escreva descrições que orientem a escolha da ferramenta
O modelo usa as descrições para decidir quando uma ferramenta é adequada a uma solicitação. Concentre a descrição na intenção do usuário e evite detalhes de implementação.
Uma boa descrição atende aos seguintes critérios.
- Informa o que a ferramenta faz.
- Explica quando usá-la.
- Mostra como ela se diferencia de ferramentas semelhantes.
- Destaca limites ou pré-requisitos importantes.
Evite descrições que apenas repitam o nome da ferramenta ou usem termos internos do serviço que os usuários desconhecem.
Planeje as anotações de segurança
Atribua as anotações de acordo com o comportamento real de cada ferramenta. Consulte o schema ToolAnnotations do MCP para conhecer as definições oficiais, os valores padrão e a interação entre as anotações.
readOnlyHintsó étruequando a ferramenta não pode alterar o estado.destructiveHintétruequando a ferramenta pode causar efeitos irreversíveis ou difíceis de reverter.openWorldHintétruequando a ferramenta acessa a internet pública ou um conjunto não delimitado de entidades externas, inclusive por meio de ações somente leitura, como a pesquisa na Web. Se o acesso se limita a uma conta privada ou a um espaço de trabalho de escopo delimitado, a hospedagem externa, por si só, não caracteriza acesso a um ambiente aberto.
As anotações não substituem a autorização no servidor, a validação das entradas nem a confirmação de ações com consequências importantes.
Verifique a cobertura e os limites
Compare as ferramentas propostas com a lista completa de casos de uso.
- Confirme que é possível chegar a um resultado útil em cada caso de uso compatível.
- Identifique as ferramentas que não atendem a nenhum caso de uso documentado.
- Verifique se falta alguma operação de leitura de que os usuários precisam antes de executar uma operação de escrita.
- Verifique se, diante de uma solicitação sem suporte, a resposta explica a limitação de forma clara e evita oferecer uma solução aproximada que possa ser insegura.
- Teste se há sobreposição entre as descrições de duas ferramentas semelhantes a ponto de dificultar a escolha.
Guarde o plano das ferramentas para usá-lo como lista de verificação durante a implementação e a avaliação. Em seguida, implemente o servidor MCP e teste cada contrato com entradas representativas, inválidas e não autorizadas.