Defina ferramentas

Ferramentas são as ações e os dados que o servidor MCP de um plug-in disponibiliza ao ChatGPT e ao Codex. Defina-as depois de explorar ideias de casos de uso e antes de implementar o servidor.

Toda ferramenta deve ajudar a alcançar um objetivo do usuário. Não reproduza uma API interna sem considerar como as pessoas vão solicitar e usar o recurso.

Associe casos de uso a ferramentas

Para cada caso de uso compatível:

1. Descreva o resultado que o usuário espera.
2. Liste as informações necessárias para produzir esse resultado.
3. Identifique as leituras, escritas ou ações externas que o servidor deve executar.
4. Agrupe operações que representem uma única ação coerente.
5. Separe as operações quando elas tiverem permissões, riscos de segurança ou requisitos de confirmação diferentes.

Por exemplo, um plug-in de projetos pode disponibilizar:

• list_projects para encontrar projetos.
• get_project para inspecionar um projeto.
• create_project para criar um projeto.
• update_project para alterar os detalhes de um projeto.
• archive_project para realizar uma mudança de estado com consequências significativas.

Separe as operações de leitura das de escrita para que o modelo e o usuário possam distinguir a recuperação de informações das ações que alteram o estado.

Defina cada contrato

Registre as seguintes informações para cada ferramenta proposta:

Use entradas explícitas. Não dependa de o modelo adivinhar identificadores, o escopo da conta ou outros valores necessários para o funcionamento correto.

Retorne identificadores estáveis e informações estruturadas suficientes para chamadas subsequentes. Não inclua segredos, tokens de acesso, diagnósticos internos nem dados pessoais desnecessários nos resultados.

Escreva descrições que orientem a seleção

O modelo usa as descrições das ferramentas para decidir quando uma ferramenta é adequada a uma solicitação. Descreva a intenção do usuário, não a implementação.

Boas descrições:

• Informam o que a ferramenta faz.
• Explicam quando usá-la.
• Diferenciam a ferramenta de outras semelhantes.
• Destacam limites ou pré-requisitos importantes.

Evite descrições que apenas repitam o nome da ferramenta ou usem terminologia interna do serviço que os usuários não conheçam.

Planeje as anotações de segurança

Atribua anotações com base no comportamento real. Consulte o esquema ToolAnnotations do MCP para ver as definições canônicas, os valores padrão e as interações entre essas indicações:

• readOnlyHint é true somente quando a ferramenta não pode alterar o estado.
• destructiveHint é true quando a ferramenta pode causar resultados irreversíveis ou difíceis de reverter.
• openWorldHint é true quando a ferramenta acessa a internet pública ou entidades externas sem escopo delimitado, inclusive por meio de ações somente leitura, como pesquisa na Web. Uma conta ou um workspace privado com escopo delimitado não é de mundo aberto apenas por estar hospedado externamente.

As anotações não substituem a autorização no servidor, a validação de entradas nem a confirmação de ações com consequências significativas.

Verifique a cobertura e os limites

Compare as ferramentas propostas com o inventário completo de casos de uso:

1. Confirme que todo caso de uso compatível tem um caminho para chegar a um resultado útil.
2. Identifique ferramentas que não atendem a um caso de uso documentado.
3. Verifique se faltam operações de leitura necessárias aos usuários antes de executar uma ação de escrita.
4. Verifique se as solicitações não compatíveis resultam em uma explicação compreensível da limitação, em vez de uma aproximação insegura.
5. Teste se duas ferramentas semelhantes têm descrições sobrepostas que possam confundir a seleção.

Mantenha o plano de ferramentas resultante como uma lista de verificação para implementação e avaliação. Em seguida, crie o servidor MCP e teste cada contrato com entradas representativas, inválidas e não autorizadas.