Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Design: Casos de Utilização e Ferramentas

Aula 3 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Comece pelas expectativas, não pela API
  2. O inventário de casos de utilização
  3. Exclua e documente
  4. Dos casos de utilização às ferramentas
  5. O contrato de cada ferramenta
  6. Descrições escritas para serem escolhidas
  7. Anotações de segurança
  8. Um plano que serve como plano de testes
  9. Pontos-chave

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-sdk inexistente e um manifesto chatgpt-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:

CampoPergunta
ObjetivoO que é que a pessoa está a tentar realizar?
Pedidos de exemploComo é que os formularia, direta ou indiretamente?
Resultado esperadoO que tornaria a interação bem-sucedida?
Contexto necessárioQue informações, acesso à conta ou estado prévio são necessários?
CapacidadeUma competência é suficiente ou é necessária uma ferramenta MCP?
Limite de segurançaPoderia expor dados, modificar estados, gastar dinheiro ou afetar terceiros?
DecisãoPrimeira 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_projects para encontrar projetos;
  • get_project para examinar um;
  • create_project para criar um;
  • update_project para modificar detalhes;
  • archive_project para 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

CampoDefinir
NomeUm identificador estável e orientado para a ação
TítuloUma ação concisa e legível por humanos
DescriçãoO objetivo do utilizador e as condições que devem acionar a ferramenta
Esquema de entradaParâmetros obrigatórios e opcionais, tipos, valores permitidos, limites
Esquema de saídaCampos estruturados que o modelo pode inspecionar e reutilizar
AutorizaçãoA conta, função ou acesso que o servidor deve verificar
Efeitos secundáriosDados ou estado externo que a ferramenta pode modificar
FalhasErros 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 é true apenas se a ferramenta não puder modificar nenhum estado;
  • destructiveHint é true se a ferramenta puder produzir um resultado irreversível ou difícil de desfazer;
  • openWorldHint é true se 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