Otimize os metadados

Por que os metadados são importantes

O ChatGPT e o Codex usam os metadados que você fornece para decidir quando chamar sua ferramenta. Nomes, descrições e documentação de parâmetros bem redigidos aumentam a chance de o modelo chamar a ferramenta nos prompts relevantes e reduzem as chamadas acidentais. Cuide dos metadados como cuida dos textos do produto: revise, teste e analise os resultados.

Monte um conjunto de prompts de referência

Antes de ajustar os metadados, reúna um conjunto de prompts e classifique cada um:

• Prompts diretos: o usuário menciona explicitamente o nome do seu produto ou da sua fonte de dados.
• Prompts indiretos: o usuário descreve o resultado desejado sem mencionar sua ferramenta pelo nome.
• Prompts negativos: uma ferramenta integrada ou outra ferramenta deve atender à solicitação.

Documente o comportamento esperado para cada prompt (chamar sua ferramenta, não fazer nada ou usar uma alternativa). Você voltará a usar esse conjunto nos testes de regressão.

Escreva metadados que orientem o modelo

Para cada ferramenta:

• Nome: combine o domínio com a ação (calendar.create_event).
• Descrição: comece com “Use esta ferramenta quando…” e indique em quais casos o uso é proibido (“Não use para lembretes”).
• Documentação dos parâmetros: descreva cada argumento, inclua exemplos e use valores permitidos para entradas com restrições.
• Indicação de somente leitura: use a anotação readOnlyHint: true em ferramentas que apenas consultam informações ou fazem cálculos e nunca criam, atualizam ou excluem dados nem os enviam para fora da conversa.
• Indicação de ação destrutiva: use a anotação destructiveHint: false em ferramentas que não excluem nem sobrescrevem dados do usuário.
• Indicação de acesso a recursos externos de escopo aberto: use a anotação openWorldHint: true quando a ferramenta acessar a internet pública ou interagir com um conjunto aberto de entidades externas. Isso inclui ferramentas de somente leitura, como a pesquisa na Web. Use false se o acesso da ferramenta se limitar a uma conta privada ou a um espaço de trabalho privado de escopo delimitado, mesmo que o serviço tenha hospedagem externa.

Avalie seu servidor MCP personalizado

1. Conecte seu servidor MCP personalizado no ChatGPT e instale o plugin resultante.
2. Execute cada prompt do conjunto de referência e registre qual ferramenta o modelo selecionou, quais argumentos passou e se o componente foi renderizado.
3. Para cada prompt, acompanhe a precisão (o modelo chamou a ferramenta certa?) e a revocação (o modelo chamou a ferramenta quando deveria?).

Se o modelo escolher a ferramenta errada, revise as descrições para destacar o cenário de uso previsto ou restrinja o escopo da ferramenta.

Faça ajustes sistemáticos

• Altere um campo de metadados por vez para identificar qual mudança trouxe a melhoria.
• Mantenha um histórico das revisões com a data, a hora e os resultados dos testes.
• Compartilhe as diferenças entre as versões com os revisores para identificar trechos ambíguos antes de publicar as alterações.

Repita a avaliação após cada revisão. Priorize uma alta precisão nos prompts negativos antes de buscar pequenos ganhos de revocação.

Monitoramento em produção

Quando seu servidor MCP estiver em produção:

• Analise semanalmente as métricas de chamadas de ferramentas. Um aumento repentino nas confirmações de “ferramenta errada” costuma indicar que os metadados já não refletem bem quando a ferramenta deve ser usada.
• Colete o feedback dos usuários e atualize as descrições para esclarecer mal-entendidos frequentes.
• Programe a reexecução periódica dos prompts, especialmente depois de adicionar ferramentas ou alterar campos estruturados.

Mantenha os metadados atualizados. Quanto mais cuidado você dedicar à redação e à avaliação, mais fácil será para o modelo encontrar e chamar sua ferramenta.