Práticas recomendadas do WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Publicado em: 18 de maio de 2026

WebMCP precisa ser clara, sem que os desenvolvedores ou agentes precisem analisar as saídas e tentar novamente. Se você usa a API imperativa ou declarativa, siga estas práticas recomendadas:

  • Antes de criar, crie uma estratégia de ferramenta.
  • Use linguagem clara e HTML semântico.
  • Crie seus esquemas e processe a entrada.
  • Crie ferramentas confiáveis.
  • Teste e depure.

Criar uma estratégia de ferramenta

Assim como faria para qualquer aplicativo de software, sua primeira etapa é planejar a estratégia de ferramenta:

  • Cada ferramenta precisa consistir em uma única função. Por exemplo, uma ferramenta pode direcionar o usuário a um tipo de formulário específico, enquanto outra precisa corresponder aos campos de entrada com as informações do usuário. Tenha cuidado para não criar ferramentas sobrepostas, já que o agente pode ficar confuso sobre o que usar. Pergunte a si mesmo: posso cobrir várias tarefas com a mesma função?
  • Gerenciar o registro de ferramentas. Registre as ferramentas quando elas forem úteis em um determinado estado da página e cancele o registro quando a ferramenta não puder mais ser usada.
    • API imperativa: é possível gerenciar o registro dinamicamente com registerTool.
    • API declarativa: é possível gerenciar o registro dinamicamente adicionando ou removendo os atributos da ferramenta em um formulário, com toolname e tooldescription.
  • Reduzir a complexidade:para a maioria dos aplicativos, o registro estático precisa ser a abordagem padrão.
  • Confie no agente para concluir a tarefa. Em vez de escrever instruções rígidas ou negativas, suponha que o agente seja capaz de entender o que é necessário para concluir a tarefa, em vez de esperar que ele gerencie um fluxo exato de etapas.

Embora não haja um número máximo de ferramentas permitidas, cada uma ocupa parte da janela de contexto e aumenta o tempo de conclusão. Quanto mais ferramentas você fornecer e quanto mais elas se sobrepuserem, mais difícil será para o agente escolher corretamente. Faça testes para determinar o que é adequado para seu aplicativo.

Isso ajuda a criar ferramentas individuais, sem sobreposição de finalidade, e a gerenciar quando elas estão disponíveis.

Usar linguagem clara e código semântico

Use uma linguagem clara e direta para nomear ferramentas e descrever o uso delas. Isso ajuda os agentes a encontrar o que precisam, entender o que encontram e usar essas informações conforme o esperado pelo desenvolvedor.

Ao escrever nomes de ferramentas, distinga a execução da inicialização e use verbos que descrevam exatamente o que acontece. Por exemplo, create-event é uma ferramenta para criação imediata de eventos, mas start-event-creation-process é uma ferramenta que redireciona o usuário para um formulário para criar o evento.

Uma descrição clara precisa descrever o que a ferramenta faz e quando usá-la. Confie em linguagem e preferências positivas em vez de linguagem negativa, como limitações.

O que não fazer

"Não use essa ferramenta para o clima."

As limitações precisam estar implícitas em uma descrição bem escrita.
O que fazer

"Essa ferramenta pode criar um evento de agenda, programado para uma data e hora específicas."

Minimizar a computação cognitiva

Assim como você precisa minimizar a carga cognitiva para que os humanos concluam tarefas complexas, também é necessário minimizar a computação cognitiva para o modelo:

  • Aceitar a entrada do usuário bruta. Evite pedir ao agente para fazer cálculos matemáticos ou transformar as strings de entrada. Por exemplo, se um usuário disser "11:00 às 15:00", a ferramenta precisará aceitar isso como uma string. Evite pedir ao modelo para calcular os minutos entre esses horários.
  • Declare tipos específicos para parâmetros, como string, número ou enumeração.
  • Explique por que você fez determinadas escolhas. A escolha feita precisa ser autoexplicativa. O motivo ajuda os agentes a fazer escolhas melhores. Por exemplo, se você tiver uma loja de e-commerce, declare o tipo de frete com linguagem natural em vez de usar um ID ambíguo: shipping="Express" em vez de shipping_id=1.

Priorizar a confiabilidade

Agentes e humanos se beneficiam de ferramentas que se comportam conforme o esperado:

  • Defina uma falha normal para limites de taxa. As ferramentas precisam permitir repetições razoáveis, como para comparação de preços. Se uma ferramenta tiver um limite de taxa, retorne um erro significativo ou aconselhe o usuário a realizar a tarefa manualmente.
  • Atualize o estado da interface após a conclusão das funções. Os agentes podem confiar na interface para planejar as próximas etapas, enquanto as funções podem levar mais tempo para serem concluídas do que o carregamento da interface. O agente precisa confirmar que a função foi concluída depois que a interface for atualizada ou solicitar uma atualização novamente.
  • Valide estritamente no código e de forma flexível no esquema. As restrições e os testes precisam ser usados para funções e códigos que têm lógica binária. Embora as restrições de esquema possam ser úteis, elas não são garantidas. Adicione erros descritivos ao código da função para permitir que o modelo se autocorrige e tente novamente com parâmetros novos e válidos.

Testes de avaliação e depuração

Crie testes de avaliação e disponibilize suas ferramentas para depuração. Ao contrário dos testes de unidade determinísticos, as avaliações não podem ser codificadas, já que as saídas podem assumir formas inesperadas.

  • Defina o problema. É possível enquadrar o problema como um contrato de API, incluindo o tipo de entrada, o formato de saída e outras restrições.
  • Defina um valor de referência e um resultado ideal. Principalmente com a entrada de texto, é importante entender quais tipos de resultados podem gerar a saída esperada.
  • Determine como a saída será avaliada. É provável que você esteja identificando e medindo resultados subjetivos e qualitativos com base na qualidade da entrada, na utilidade e na capacidade de realizar a próxima tarefa. Há várias técnicas que podem ser usadas para avaliar a saída, incluindo verificações baseadas em código para saídas baseadas em regras (limites de caracteres) e LLM-as-a-judge.

Evite adicionar regras restritas para corrigir problemas com um modelo específico. Por exemplo, se você incluir um campo de seleção para títulos, o modelo poderá fazer a escolha errada. Em vez de adicionar regras restritas para corrigir esse problema, abstraia e ajuste a ferramenta. A melhor opção é definir esse campo como opcional. Em seguida, peça ao agente para perguntar ao usuário qual escolha faz sentido, para garantir que ele fique satisfeito com o resultado.

Interagir e compartilhar feedback

O WebMCP está em discussão ativa e sujeito a mudanças no futuro. Se você testar essas APIs e tiver feedback, gostaríamos de saber.