Chamar o WebMCP de “ponte” não é só uma imagem bonita — é uma descrição precisa do que a especificação faz: conecta duas pontas (o agente de IA e a ação real do site) que antes não tinham um jeito confiável de se falar. Para entender essa ponte de verdade, vale seguir o fluxo completo, do início ao fim.
Etapa 1: Descoberta
Antes de fazer qualquer coisa, o agente precisa saber o que existe. Isso acontece via document.modelContext.getTools(), um método que devolve a lista de ferramentas que a página declarou — cada uma com nome, descrição e o schema de parâmetros que ela aceita. Sem essa etapa, o agente estaria de volta a adivinhar lendo HTML.
Etapa 2: Decisão
Com a lista de tools em mãos, cabe ao agente (o modelo de IA por trás dele) decidir qual ferramenta usar, com base no que o usuário pediu e na descrição de cada tool disponível. É aqui que a qualidade da descrição que você escreveu importa de verdade: uma descrição vaga como “busca coisas” ajuda muito menos que “busca artigos do blog por palavra-chave e categoria, retornando título, resumo e URL”.
Etapa 3: Execução
Decidida a tool, o agente aciona document.modelContext.executeTool() passando os parâmetros no formato que o schema definiu. Se a tool foi registrada via API Imperativa, a função execute que você escreveu roda nesse momento — pode ser uma chamada a uma API interna, uma consulta a um banco, o que fizer sentido para aquela ação. Se foi declarada via API Declarativa, o comportamento equivale a enviar o formulário correspondente.
Etapa 4: Retorno
A ação executa e devolve um resultado para o agente — o texto ou dado que a função execute retornou, ou a resposta natural do envio do formulário. O agente usa esse retorno para continuar a tarefa: mostrar o resultado ao usuário, encadear com outra ação, ou simplesmente confirmar que funcionou.
Um detalhe que muita gente pula: o evento toolchange
Sites mudam. Uma tool pode deixar de existir, uma nova pode aparecer depois que a página termina de carregar (por exemplo, depois que o usuário faz login). O WebMCP prevê isso com o evento toolchange, que avisa o agente quando a lista de ferramentas disponíveis muda, para ele não trabalhar com informação desatualizada.
Por que pensar em etapas ajuda a implementar melhor
Cada uma dessas quatro etapas é um ponto onde uma implementação pode falhar silenciosamente: uma tool mal descoberta porque foi registrada tarde demais, uma decisão errada porque a descrição é ambígua, uma execução que quebra porque o schema não bate com o que a função espera, um retorno que não diz nada útil sobre o que aconteceu. Pensar no fluxo completo, e não só no “tenho uma tool registrada”, é o que separa uma implementação que funciona de uma que só existe no papel.
A ponte funciona nos dois sentidos
Vale reforçar: essa ponte beneficia quem constrói o site (controle sobre o que exatamente pode ser executado, em vez de depender de scraping alheio) e quem constrói o agente (menos engenharia reversa, mais previsibilidade). Ninguém precisa confiar cegamente no outro lado — o contrato está escrito no nome, na descrição e no schema da tool.