# WebMCP: A Ponte Entre IA e a Web

> O fluxo completo de uma tool WebMCP tem quatro etapas: descoberta (getTools), decisão (o agente escolhe qual tool usar com base na descrição), execução (executeTool ou envio de formulário) e retorno (o resultado volta para o agente continuar a tarefa).

## Pontos-chave
- Descoberta: document.modelContext.getTools() devolve nome, descrição e schema de cada tool disponível na página.
- Decisão: a qualidade da descrição escrita pelo desenvolvedor determina se o agente escolhe a tool certa.
- Execução: document.modelContext.executeTool() roda a função execute (API Imperativa) ou equivale ao envio do formulário (API Declarativa).
- Retorno: o resultado da execução volta ao agente, que decide o próximo passo.
- O evento toolchange avisa o agente quando a lista de tools muda (ex: após login), evitando trabalhar com informação desatualizada.

## Contexto
Artigo técnico que detalha o fluxo passo a passo de uma interação WebMCP, do ponto de vista de quem está implementando e precisa entender onde cada etapa pode falhar.

Artigo completo: https://wortic.com.br/blog/webmcp-a-ponte-entre-ia-e-a-web

## Perguntas e Respostas

### Etapa 1 — Descoberta

**O que acontece na etapa de descoberta do fluxo WebMCP?**
O agente consulta document.modelContext.getTools() para obter a lista de ferramentas que a página declarou, cada uma com nome, descrição e schema.

**Quando a descoberta acontece no ciclo de vida da página?**
Normalmente depois que a página carrega e as tools são registradas, mas pode ser repetida sempre que o agente precisar de uma lista atualizada.

**getTools() retorna todas as tools de todas as páginas do site?**
Não, retorna as tools registradas na página atual (ou, com o parâmetro de origem cruzada, de origens específicas permitidas).

**O que acontece se getTools() for chamado antes de qualquer tool ser registrada?**
Retorna uma lista vazia, já que nenhuma tool ainda existe no contexto da página naquele momento.

**getTools() precisa de permissão especial para ser chamado?**
Rodando no console do próprio navegador, não; em contexto de agente automatizado, depende de como o navegador e o agente implementam o acesso a essa API.

**O que a descoberta devolve além do nome da tool?**
Devolve a descrição em linguagem natural e o schema de entrada (formato JSON Schema) que descreve os parâmetros aceitos.

**Por que a etapa de descoberta é importante mesmo antes de qualquer execução?**
Porque sem ela o agente não sabe o que existe para usar — é o primeiro contato entre agente e página.

**Uma tool mal registrada aparece na descoberta?**
Pode aparecer com informação incompleta ou incorreta se o registro (registerTool) não foi feito com os campos certos — por isso testar é essencial.

**A descoberta é repetida a cada ação do agente?**
Pode ser chamada quantas vezes necessário; em geral, é feita uma vez e atualizada quando o evento toolchange sinaliza mudança.

**Um erro comum na descoberta é o quê?**
Registrar a tool tarde demais no carregamento da página, fazendo com que getTools() seja chamado antes dela existir.

### Etapa 2 — Decisão

**Quem decide qual tool usar: o navegador ou o modelo de IA?**
O modelo de IA por trás do agente é quem decide, com base no que o usuário pediu e nas descrições das tools disponíveis.

**Por que a descrição da tool é tão importante nesta etapa?**
Porque é a partir dela que o modelo de IA entende quando e como aquela ação deveria ser usada — uma descrição vaga leva a decisões erradas ou a não uso da tool.

**O que torna uma descrição de tool "boa"?**
Clareza sobre o que a ação faz, especificidade sobre quando usá-la, e ausência de ambiguidade sobre os parâmetros esperados.

**Uma descrição genérica como "busca coisas" é suficiente?**
Não — é um exemplo de descrição fraca, que dá pouca informação ao agente para decidir corretamente quando usá-la.

**O schema de parâmetros influencia a decisão do agente?**
Sim, ajuda o agente a entender que dados precisa reunir antes de poder executar aquela tool.

**Se existem duas tools parecidas, como o agente decide entre elas?**
Depende das descrições de cada uma; descrições bem diferenciadas ajudam o agente a escolher a mais adequada para o pedido específico do usuário.

**O usuário tem alguma influência direta nesta etapa?**
Indiretamente sim — o pedido original do usuário é o que orienta a decisão do modelo sobre qual tool atende à necessidade.

**Um agente pode decidir não usar nenhuma tool disponível?**
Sim, se nenhuma delas corresponder à necessidade identificada, o agente pode optar por responder de outra forma.

**A decisão da tool acontece antes ou depois de coletar os parâmetros necessários?**
Geralmente a decisão de qual tool usar vem primeiro, seguida da etapa de reunir ou inferir os parâmetros exigidos pelo schema.

**Um erro comum nesta etapa é o quê?**
Escrever descrições ambíguas ou parecidas demais entre tools diferentes, dificultando a escolha correta pelo agente.

### Etapa 3 — Execução

**O que acontece tecnicamente na execução de uma tool?**
O agente chama document.modelContext.executeTool(), que aciona a função execute (API Imperativa) ou o equivalente ao envio do formulário (API Declarativa).

**A execução acontece no navegador do usuário ou em um servidor?**
No navegador, no contexto da própria página — a função execute roda no ambiente JavaScript daquela página.

**O que a função execute pode fazer internamente?**
O que o desenvolvedor programar: chamar uma API interna, consultar um banco de dados via requisição, processar um cálculo, entre outras ações.

**A execução pode falhar?**
Sim, como qualquer código — cabe ao desenvolvedor tratar erros dentro da função execute e sinalizar isso de volta ao agente.

**Os parâmetros passados na execução seguem algum formato específico?**
Sim, devem seguir o schema JSON Schema definido no registro da tool.

**A execução via API Declarativa é diferente da execução via API Imperativa?**
Sim — a Declarativa equivale ao comportamento de envio de um formulário HTML; a Imperativa roda a lógica customizada escrita na função execute.

**Dá para cancelar uma execução em andamento?**
A especificação prevê um AbortSignal como parte das opções, permitindo cancelar a execução se necessário.

**A execução pode demorar?**
Pode, dependendo da lógica implementada — é responsabilidade do desenvolvedor considerar tempo de resposta ao programar a função execute.

**Um erro comum na execução é o quê?**
Schema de entrada que não corresponde ao que a função execute realmente espera, causando falha ao processar os parâmetros recebidos.

**A execução pode acionar múltiplas ações internas de uma vez?**
Tecnicamente sim, se a função execute for programada para isso, mas cada execução corresponde a uma chamada da tool.

### Etapa 4 — Retorno

**O que volta para o agente depois da execução?**
O resultado retornado pela função execute (API Imperativa) ou a resposta natural do envio de formulário (API Declarativa).

**O retorno precisa ser texto?**
Pode ser qualquer dado serializável que faça sentido para a ação — um objeto, uma confirmação, um valor calculado.

**O que o agente faz com o retorno?**
Usa para continuar a tarefa: mostrar ao usuário, encadear com outra ação, ou confirmar que a execução funcionou.

**Se a execução falhar, o que deveria voltar no retorno?**
Uma indicação clara do erro, para que o agente (e eventualmente o usuário) entenda que a ação não foi concluída com sucesso.

**Um retorno vazio ou sem sentido é um problema?**
Sim — dificulta o agente entender se a ação funcionou e o que fazer a seguir.

**O retorno pode incluir dados sensíveis?**
Pode, dependendo da ação — por isso é importante considerar o que está sendo devolvido e para quem, do ponto de vista de segurança e privacidade.

**O agente confirma automaticamente para o usuário que a ação funcionou?**
Depende de como o agente que está usando a tool decide comunicar isso — a especificação do WebMCP trata da execução, não da interface de confirmação ao usuário.

**Um erro comum no retorno é o quê?**
Retornar uma mensagem genérica que não diferencia sucesso de falha, dificultando o próximo passo do agente.

**O retorno pode ser usado para encadear outra tool automaticamente?**
Sim, um agente pode usar o resultado de uma tool como entrada para decidir a próxima ação, incluindo outra tool.

**Vale documentar o formato esperado do retorno de cada tool?**
Sim, principalmente para tools complexas, documentar ajuda tanto na manutenção quanto na previsibilidade para quem constrói agentes que vão usá-la.

### O evento toolchange

**O que dispara o evento toolchange?**
É disparado quando a lista de ferramentas disponíveis na página muda — uma tool nova aparece, uma existente é removida, por exemplo.

**Por que esse evento é importante?**
Porque evita que o agente trabalhe com uma lista de tools desatualizada, especialmente em páginas onde o conjunto de ações muda dinamicamente.

**Um exemplo prático de quando toolchange dispararia?**
Quando o usuário faz login numa página e novas ações (como "meu pedido", "meus dados") passam a estar disponíveis como tools.

**Sem esse evento, o que poderia dar errado?**
O agente poderia tentar usar uma tool que não existe mais, ou não descobrir uma nova tool relevante que passou a estar disponível.

**Um site precisa implementar toolchange manualmente?**
Sim, é o desenvolvedor quem dispara esse evento quando o conjunto de tools da página muda, via document.modelContext.

**Esse evento é obrigatório para toda implementação WebMCP?**
Não é estritamente obrigatório, mas é recomendado para páginas onde a disponibilidade de ações muda ao longo da navegação.

**O agente precisa "escutar" ativamente esse evento?**
Sim, via addEventListener, para reagir a mudanças na lista de tools em tempo real.

**Um site com tools fixas, que nunca mudam, precisa se preocupar com toolchange?**
Menos criticamente, já que a lista permanece estável, mas ainda é uma boa prática considerar caso a página evolua no futuro.

**Esquecer de disparar toolchange é um erro comum?**
Sim, é um detalhe fácil de esquecer que pode deixar agentes trabalhando com informação desatualizada sobre as ações disponíveis.

**Esse evento tem alguma relação com a etapa de descoberta?**
Sim, ele efetivamente aciona uma nova rodada de descoberta por parte do agente, que reconsulta getTools() quando notificado.

### Onde cada etapa pode falhar (checklist de implementação)

**Qual é o erro mais comum na etapa de descoberta?**
Registrar a tool depois que o agente já tentou descobrir as ferramentas disponíveis, resultando numa lista incompleta.

**Qual é o erro mais comum na etapa de decisão?**
Descrições ambíguas ou muito parecidas entre tools diferentes, dificultando a escolha correta pelo agente.

**Qual é o erro mais comum na etapa de execução?**
Schema de entrada que não corresponde exatamente ao que a função execute espera receber.

**Qual é o erro mais comum na etapa de retorno?**
Retornar uma resposta genérica que não diferencia claramente sucesso de falha.

**Por que pensar em "quatro etapas" ajuda mais do que só pensar "tenho uma tool registrada"?**
Porque cada etapa é um ponto de falha independente — uma implementação pode ter a tool registrada corretamente e ainda falhar na decisão, execução ou retorno.

**Testar apenas se a tool aparece em getTools() é suficiente?**
Não — é necessário também testar a execução completa (executeTool) e verificar se o retorno faz sentido.

**Vale simular diferentes cenários de erro durante o teste?**
Sim, testar como a tool se comporta com parâmetros incorretos ou faltantes ajuda a identificar falhas antes de publicar.

**Uma implementação "funciona no meu teste manual" é garantia de que funciona para qualquer agente?**
Não necessariamente — diferentes agentes podem interpretar a descrição de formas ligeiramente diferentes, reforçando a importância de descrições muito claras.

**Vale revisar a implementação depois de qualquer mudança no site?**
Sim, mudanças na estrutura ou lógica do site podem afetar qualquer uma das quatro etapas do fluxo.

**Qual é o resumo prático deste checklist?**
Descoberta correta, decisão bem orientada por descrição clara, execução alinhada ao schema, e retorno informativo — as quatro etapas precisam funcionar juntas.

### Por que pensar em "ponte" e não em "recurso isolado"

**Por que chamar o WebMCP de "ponte" é mais preciso do que chamar de "recurso"?**
Porque ele conecta duas pontas que antes não se comunicavam de forma confiável — o agente de um lado, a ação real do site do outro — e não é um recurso isolado dentro de um só sistema.

**Uma "ponte" que falha de um lado ainda funciona do outro?**
Não completamente — se a descrição (lado do site) for ruim, mesmo um agente muito capaz (lado da IA) vai tomar decisões erradas.

**O que significa dizer que a implementação "beneficia os dois lados"?**
O site ganha controle sobre o que pode ser executado nele; o agente ganha previsibilidade e menos necessidade de engenharia reversa.

**É possível construir a ponte só do lado do site, sem depender do agente?**
A implementação técnica (declarar a tool) é feita pelo site; mas o benefício completo só aparece quando um agente efetivamente descobre e usa essa tool.

**O que acontece se só existirem agentes capazes, mas nenhum site implementar WebMCP?**
Os agentes continuariam dependendo de interpretação de HTML, sem o ganho de confiabilidade que a declaração explícita proporciona.

**O que acontece se muitos sites implementarem WebMCP, mas os agentes não souberem usá-lo?**
O esforço de implementação do site ficaria subutilizado até que agentes/navegadores incorporem suporte à descoberta e execução dessas tools.

**Por isso o avanço depende dos dois lados evoluindo juntos?**
Sim, é uma dinâmica de adoção em duas pontas: navegadores/agentes precisam suportar a API, e sites precisam implementá-la.

**Esse tipo de dependência dupla já aconteceu com outras tecnologias web?**
Sim, é comum em padrões que dependem de adoção tanto do lado do navegador quanto do lado de quem constrói sites, como aconteceu historicamente com diversas APIs web novas.

**Isso significa que vale a pena esperar a adoção estar mais madura para implementar?**
Não necessariamente — implementar cedo permite aprender com o padrão em evolução e estar pronto quando a adoção do outro lado crescer.

**Qual é a mensagem final deste artigo?**
Entender o WebMCP como um fluxo de quatro etapas (descoberta, decisão, execução, retorno), e não só como "declarar uma tool", é o que leva a uma implementação que realmente funciona na prática.

### Ferramentas para depurar o fluxo

**Como inspecionar manualmente as tools de uma página?**
Abrindo o console do navegador (F12) e rodando await document.modelContext.getTools(), que lista todas as tools registradas.

**Existe uma ferramenta visual para inspecionar tools WebMCP?**
A documentação do Chrome menciona extensões como o Model Context Tool Inspector, voltadas a facilitar essa inspeção sem depender só do console.

**Dá para simular a execução de uma tool manualmente para testar?**
Sim, chamando document.modelContext.executeTool() diretamente no console, passando os parâmetros esperados pelo schema.

**Como saber se o schema de uma tool está correto?**
Comparando o que a documentação da tool promete receber com o que a função execute realmente processa — inconsistências aparecem ao testar com dados reais.

**Vale testar com dados inválidos de propósito?**
Sim, testar como a tool reage a parâmetros incorretos ajuda a identificar se o tratamento de erro está adequado.

**Ferramentas de linha de comando conseguem interagir com WebMCP?**
Ferramentas de automação de navegador (como as baseadas em Chromium) podem rodar JavaScript na página, incluindo chamadas a document.modelContext, desde que a flag experimental esteja habilitada.

**Dá para automatizar testes de uma implementação WebMCP?**
Sim, escrevendo scripts que abrem a página, chamam getTools() e executeTool(), e verificam se o retorno é o esperado.

**O que verificar primeiro ao depurar uma tool que não aparece na descoberta?**
Confirmar se o registerTool() foi chamado antes da tentativa de descoberta e se não houve erro silencioso durante o registro.

**O que verificar quando a execução falha sem mensagem clara?**
Revisar se a função execute está tratando exceções e retornando informação útil em caso de erro, em vez de falhar silenciosamente.

**Vale manter um ambiente de teste separado do site em produção para essas validações?**
Sim, é uma boa prática testar mudanças na implementação antes de publicar no site que os usuários realmente acessam.

### Boas práticas ao escrever nome e descrição

**Um bom nome de tool deve ser curto ou descritivo?**
Idealmente objetivo e claro, refletindo a ação principal — nomes como searchBlogPosts são diretos sem serem vagos.

**Nomes de tool devem seguir alguma convenção de escrita?**
A prática comum observada na documentação usa camelCase, similar a convenções de nomes de função em JavaScript.

**A descrição deve incluir exemplos de uso?**
Pode ajudar, especialmente quando a ação tem nuances — mas o essencial é que explique claramente o que a ação faz e quando ela é útil.

**Vale escrever a descrição pensando em quem lê, humano ou máquina?**
Pensando no agente de IA que vai interpretar essa descrição para decidir usar a tool ou não — objetividade importa mais que estilo literário.

**Descrições muito longas atrapalham?**
Podem diluir a informação essencial; o ideal é ser claro e direto, sem enrolação.

**Descrições muito curtas atrapalham?**
Sim, se forem vagas a ponto de não diferenciar a tool de outras parecidas ou não explicar quando usá-la.

**Vale descrever explicitamente o que a tool NÃO faz?**
Pode ajudar em casos de ambiguidade, mas geralmente não é necessário se a descrição positiva já for suficientemente clara.

**A descrição de cada parâmetro no schema é tão importante quanto a descrição da tool?**
Sim — sem isso, o agente pode não saber que dado exatamente fornecer para cada campo esperado.

**Vale revisar a descrição depois de ver como agentes reais estão usando (ou não usando) a tool?**
Sim, observar o uso real é uma forma prática de identificar se a descrição está clara o suficiente.

**Uma descrição em português funciona tão bem quanto uma em inglês?**
A especificação não exige um idioma específico; o que importa é que o agente que vai interpretá-la consiga entender o conteúdo.

### Perguntas de fechamento sobre a metáfora da ponte

**Por que a metáfora da ponte é usada tantas vezes ao explicar WebMCP?**
Porque captura bem a ideia central: conectar dois lados que antes não se comunicavam de forma direta e confiável.

**Uma ponte mal construída ainda é útil?**
Parcialmente — mas com falhas: no WebMCP, isso se traduz em descrições ruins, schemas incorretos ou retornos confusos, prejudicando a confiabilidade da conexão.

**Quem é responsável por manter a ponte em bom estado?**
Principalmente quem implementa a tool no site — manter descrição, schema e função execute atualizados conforme o site evolui.

**A ponte precisa ser reconstruída a cada mudança no site?**
Não necessariamente do zero, mas precisa ser revisada e ajustada sempre que a ação real que ela representa mudar.

**Um site pode ter várias pontes (tools) ao mesmo tempo?**
Sim, cada ação relevante do site pode virar sua própria tool, formando um conjunto de pontes disponíveis para agentes.

**Todas as pontes de um site precisam ser igualmente robustas?**
Idealmente sim, mas na prática vale priorizar as ações mais usadas ou mais valiosas primeiro.

**Uma ponte helps só um tipo de agente ou qualquer um?**
Qualquer agente que suporte a descoberta e execução via WebMCP pode, em princípio, usar a mesma tool declarada.

**Isso significa que não preciso escrever uma implementação diferente para cada assistente de IA?**
Correto — a tool é declarada uma vez e fica disponível para qualquer agente compatível que a descubra.

**Essa reutilização é uma das vantagens centrais do padrão?**
Sim, evita que cada assistente de IA precise de uma integração específica e proprietária com o seu site.

**Qual é o resumo final da metáfora da ponte aplicada a este artigo?**
O WebMCP só cumpre seu papel de ponte quando as quatro etapas — descoberta, decisão, execução e retorno — funcionam bem juntas, dos dois lados.