Práticas recomendadas do WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Publicado em: 18 de maio de 2026

A declaração da ferramenta WebMCP precisa ser clara, sem que desenvolvedores ou agentes precisem analisar as saídas e tentar de novo. Se você usa a API imperativa ou declarativa, siga estas práticas recomendadas:

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

Criar uma estratégia de ferramentas

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

  • 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, e outra pode corresponder os campos de entrada às informações do usuário. Tenha cuidado para não criar ferramentas sobrepostas, porque o agente pode ficar confuso sobre o que usar. Pergunte-se: posso cobrir várias tarefas com a mesma função?
  • Gerenciar o registro da ferramenta. Registre ferramentas quando elas forem úteis em um determinado estado da página e cancele o registro quando não puderem mais ser usadas.
    • API imperativa: é possível gerenciar dinamicamente o registro com registerTool e unregisterTool.
    • API declarativa: é possível gerenciar o registro de forma dinâmica adicionando ou removendo os atributos da ferramenta em um formulário, com toolName e toolDescription.
  • Reduza a complexidade:para a maioria dos aplicativos, o registro estático deve 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 ao seu aplicativo.

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

Use uma linguagem clara e um código semântico

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

Ao escrever nomes de ferramentas, diferencie a execução da iniciaçã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 redireciona o usuário para um formulário para criar o evento.

Uma descrição clara deve explicar o que a ferramenta faz e quando usá-la. Use linguagem e preferências positivas em vez de negativas, como limitações.

O que não fazer

"Não use esta ferramenta para previsão do tempo."

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

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

Minimizar a computação cognitiva

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

  • Aceitar entrada bruta do usuário. Evite pedir ao agente para fazer cálculos ou transformar as strings de entrada. Por exemplo, se um usuário disser "das 11h às 15h", a ferramenta vai 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 deve ser autoexplicativa. O motivo ajuda os agentes a fazer escolhas melhores. Por exemplo, se você tem 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 funcionam como 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 a taxa limitada, retorne um erro significativo ou aconselhe o usuário a realizar a tarefa manualmente.
  • Atualizar o estado da interface depois que as funções forem concluídas. Os agentes podem depender da 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. Restrições e testes devem ser usados para funções e códigos com 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 corrija e tente novamente com parâmetros novos e válidos.

Teste e depuração de avaliaçã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. Você pode enquadrar seu 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. Você provavelmente está 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 você pode usar 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 tratamentos, o modelo poderá fazer a escolha errada. Em vez de adicionar regras restritas para corrigir esse problema, abstraia e ajuste sua ferramenta. É melhor definir esse campo como opcional. Em seguida, peça ao agente para perguntar ao usuário qual opção faz sentido para garantir que ele fique satisfeito com o resultado.

Engajamento e como compartilhar feedback

O WebMCP está em discussão e sujeito a mudanças no futuro. Se você testar essas APIs e tiver feedback, envie sua opinião.