Design: Casos de Utilização e Ferramentas
Nesta página
Lição reescrita em 3 de novembro de 2026 com base nas páginas de documentação da OpenAI Brainstorm plugin use cases e Define tools. A lição anterior instalava um pacote
@openai/apps-sdkinexistente e um manifestochatgpt-app.json; a instalação das ferramentas reais (SDKs MCP oficiais) ocorre na Lição 4. Fontes: Brainstorm plugin use cases · Define tools.
Comece pelas expectativas, não pela API
A documentação da OpenAI recomenda começar a construir um plugin antes de escrever uma única linha de código: liste o que as pessoas esperam dele. O nome do plugin, a descrição, as competências, as ferramentas e o produto ao qual se liga criam todas expectativas; a sua implementação deve cumpri-las ou ter uma razão deliberada para não o fazer.
Imagine alguém que instalou o seu plugin sem ler a documentação. O que é que lhe vai pedir? Para descobrir, baseie-se nas tarefas que os seus utilizadores já realizam no seu produto, nos tickets de suporte, nas consultas de pesquisa, nos pedidos de funcionalidades, no vocabulário que usam e nas soluções de contorno que os obrigam a copiar dados de uma ferramenta para outra. Registe os pedidos diretos que nomeiam o plugin e os pedidos indiretos que indicam apenas o objetivo: um plugin de gestão de projetos deve tratar «Mostrar o quadro de lançamento da Acme» da mesma forma que «O que está a bloquear o lançamento?».
Não limite este inventário ao que a sua API já faz. Liste primeiro as expectativas e compare-as depois com o que pode fornecer de forma segura e fiável.
O inventário de casos de utilização
Para cada caso de utilização, a OpenAI recomenda responder a sete perguntas:
| Campo | Pergunta |
|---|---|
| Objetivo | O que é que a pessoa está a tentar realizar? |
| Pedidos de exemplo | Como é que os formularia, direta ou indiretamente? |
| Resultado esperado | O que tornaria a interação bem-sucedida? |
| Contexto necessário | Que informações, acesso à conta ou estado prévio são necessários? |
| Capacidade | Uma competência é suficiente ou é necessária uma ferramenta MCP? |
| Limite de segurança | Poderia expor dados, modificar estados, gastar dinheiro ou afetar terceiros? |
| Decisão | Primeira versão, mais tarde ou exclusão intencional? |
Agrupe os pedidos que partilham um objetivo: «Listar as minhas tarefas em aberto», «O que tenho de fazer hoje?» e «Mostrar trabalho em atraso» pertencem provavelmente ao mesmo caso de utilização de revisão de tarefas, com filtros diferentes.
Verifique depois a cobertura. Cada caso de utilização selecionado deve ter um caminho completo do pedido ao resultado; as escritas devem incluir autorização e confirmação; e o plugin deve saber indicar o que não faz, propondo ao mesmo tempo um próximo passo útil. Um plugin que permite criar projetos, mas não listá-los, vê-los ou editá-los, promete mais do que entrega: ou o completa ou restringe o seu posicionamento.
Exclua e documente
Não precisa de implementar tudo, mas cada exclusão importante merece uma justificação: risco de segurança ou privacidade inaceitável, uma API que não o suporta de forma fiável, permissões não verificáveis, resultados enganosos devido à falta de informações ou um âmbito de primeira versão claramente declarado na listagem do plugin. Registe estas decisões: elas informam os limites das competências, as descrições das ferramentas, as recusas, os testes e o texto público da listagem.
Dos casos de utilização às ferramentas
Uma ferramenta deve servir um objetivo do utilizador. Não copie simplesmente a sua API interna tal como está. Para cada caso de utilização selecionado, escreva o resultado esperado, liste as informações necessárias, identifique as leituras, as escritas e as ações externas, agrupe o que forma uma ação coerente — e separe o que difere em termos de permissões, risco ou necessidade de confirmação.
O exemplo da OpenAI para um plugin de projetos:
list_projectspara encontrar projetos;get_projectpara examinar um;create_projectpara criar um;update_projectpara modificar detalhes;archive_projectpara uma alteração de estado de alta consequência.
As leituras e as escritas são separadas para que o modelo e o utilizador possam distinguir consulta de modificação.
O contrato de cada ferramenta
| Campo | Definir |
|---|---|
| Nome | Um identificador estável e orientado para a ação |
| Título | Uma ação concisa e legível por humanos |
| Descrição | O objetivo do utilizador e as condições que devem acionar a ferramenta |
| Esquema de entrada | Parâmetros obrigatórios e opcionais, tipos, valores permitidos, limites |
| Esquema de saída | Campos estruturados que o modelo pode inspecionar e reutilizar |
| Autorização | A conta, função ou acesso que o servidor deve verificar |
| Efeitos secundários | Dados ou estado externo que a ferramenta pode modificar |
| Falhas | Erros que o modelo pode explicar ou dos quais se pode recuperar |
Três regras completam esta tabela. Entradas explícitas: não confie no modelo para adivinhar um ID ou um âmbito de conta. Saídas reutilizáveis: devolva IDs estáveis e informações suficientes para a próxima chamada. Saídas limpas: sem segredos, tokens de acesso, diagnósticos internos ou dados pessoais desnecessários.
Descrições escritas para serem escolhidas
O modelo seleciona ferramentas com base na sua descrição: descreva a intenção do utilizador, não a implementação. Uma boa descrição indica o que a ferramenta faz, quando utilizá-la, como difere das suas vizinhas e quais são os seus limites ou pré-requisitos. Evite aquelas que repetem o nome da ferramenta ou usam jargão interno que os seus utilizadores não conhecem.
Anotações de segurança
Cada ferramenta transporta anotações, definidas com base no seu comportamento real:
readOnlyHintétrueapenas se a ferramenta não puder modificar nenhum estado;destructiveHintétruese a ferramenta puder produzir um resultado irreversível ou difícil de desfazer;openWorldHintétruese a ferramenta aceder à Internet pública ou a entidades externas abertas, mesmo apenas em leitura, como uma pesquisa na Web. Uma conta ou espaço de trabalho privado e delimitado não é «aberto» só porque está alojado noutro local.
As anotações ajudam o ChatGPT e o Codex a escolher o nível de confirmação adequado, mas não substituem a autorização no servidor, a validação de entrada ou a confirmação para ações importantes.
Um plano que serve como plano de testes
Mantenha o inventário e o plano de ferramentas: eles tornam-se a sua lista de verificação. Adicione pedidos diretos, indiretos, de casos limite e fora do âmbito, e verifique se o plugin acabado se comporta como esperado para cada um. Procure também ferramentas que não sirvam nenhum caso de utilização documentado, leituras em falta antes de escritas e descrições demasiado próximas que possam confundir o modelo.
Pontos-chave
- Comece pelo que os utilizadores esperam e compare com o que pode fornecer de forma segura
- Um inventário de sete perguntas por caso de utilização, incluindo exclusões intencionais
- Uma ferramenta por ação coerente; leituras e escritas separadas
- Um contrato por ferramenta: nome, título, descrição, esquemas, autorização, efeitos secundários, falhas
- As anotações (
readOnlyHint,destructiveHint,openWorldHint) seguem o comportamento real e não substituem a autorização