Práticas recomendadas do WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Publicado em: 18 de maio de 2026

Explicação Web Extensões Status do Chrome Intenção
GitHub Teste de origem Teste de origem Ver Intenção de teste

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.

Escrevemos separadamente sobre a criação de ferramentas com foco na segurança.

Criar uma estratégia de ferramenta

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

  • Cada ferramenta precisa consistir em uma única função. Por exemplo, uma ferramenta pode direcionar o usuário para um tipo de formulário específico, enquanto outra ferramenta precisa corresponder aos campos de entrada com as informações do usuário. Tenha cuidado para não criar ferramentas sobrepostas, porque 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 ferramenta 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 é certo para seu aplicativo.

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

Usar linguagem clara e código semântico

Use uma linguagem clara e precisa 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 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 é 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 calendário, programado para uma data e hora específicas."

Em vez de dizer ao modelo o que fazer, essa linguagem descreve as ações que a ferramenta pode realizar.

Minimizar a computação cognitiva

Assim como você precisa minimizar a carga cognitiva para humanos que concluem 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 realizar cálculos matemáticos ou transformar as strings de entrada. Por exemplo, se um usuário disser "11:00 às 15:00", 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 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 limite de taxa, retorne um erro significativo ou aconselhe o usuário a realizar a tarefa manualmente.
  • Atualize o estado da interface depois que as funções forem concluídas. 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, 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, porque 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 sua ferramenta. É melhor definir esse campo como opcional. Em seguida, peça ao agente para perguntar ao usuário qual escolha faz sentido, para garantir que o usuário esteja 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.