# WebMCP Conecta Sua Web à Inteligência Artificial

> Roteiro prático de 6 passos para conectar especificamente o seu site ao WebMCP: listar ações reais, escolher uma para começar, escrever a descrição antes do código, implementar com a API certa, testar de verdade, e ajustar sem desistir no primeiro erro.

## Pontos-chave
- Passo 1: listar todas as ações reais do site (formulário, busca, carrinho), sem julgar ainda quais valem a pena.
- Passo 2: escolher UMA ação pra começar, priorizando a mais usada, simples de descrever e de menor risco.
- Passo 3: escrever a descrição em português claro ANTES de escrever qualquer código — se não consegue descrever claramente, a ação precisa ser mais bem entendida primeiro.
- Passo 4: API Declarativa para formulário HTML simples (toolname/tooldescription/toolparamdescription); API Imperativa (registerTool) para lógica mais complexa.
- Passo 5: testar de verdade com a flag chrome://flags/#enable-webmcp-testing, usando getTools() e executeTool() com parâmetros válidos e inválidos.
- Passo 6: ajustar após erros, não abandonar — repetir o ciclo é o que constrói domínio prático real.

## Contexto
Guia prático e direto (não teórico) com passo a passo concreto de 6 etapas para o leitor implementar WebMCP na própria ação real do site, complementando os artigos mais conceituais da série.

Artigo completo: https://wortic.com.br/blog/webmcp-conecta-sua-web-a-inteligencia-artificial

## Perguntas e Respostas

### Passo 1: listar as ações reais do site

**O que conta como "ação real" de um site para efeito deste roteiro?**
Qualquer interação que o site permite executar: formulário de contato, busca, adicionar ao carrinho, agendar horário, entre outras.

**Uma página institucional sem formulário tem alguma ação real para listar?**
Pode ter menos, mas ainda vale verificar se existe alguma busca, newsletter ou outra interação disponível.

**Vale listar até ações pequenas e aparentemente pouco importantes?**
Sim, o objetivo do Passo 1 é ter a lista completa antes de julgar o que vale priorizar depois.

**Quanto tempo leva para fazer esse levantamento inicial?**
Para a maioria dos sites, pode ser feito em poucas horas, revisando as páginas principais em busca de formulários e funcionalidades interativas.

**Uma pessoa sem conhecimento técnico consegue fazer esse levantamento?**
Sim, é mais um exercício de observação do site do que de conhecimento técnico profundo.

**Vale envolver a equipe de atendimento ao cliente nesse levantamento?**
Pode ajudar, já que eles frequentemente sabem quais ações os clientes mais usam ou perguntam sobre no site.

**Esse levantamento deveria incluir ações que só aparecem depois de login?**
Sim, se relevantes, vale incluir também ações disponíveis para usuários autenticados.

**Um site com múltiplas páginas semelhantes precisa listar a ação em cada uma separadamente?**
Não necessariamente — se a ação (como busca) é a mesma em várias páginas, pode ser tratada como uma única entrada na lista.

**Vale revisar esse levantamento periodicamente conforme o site evolui?**
Sim, novas funcionalidades podem surgir e vale atualizar a lista de ações reais ao longo do tempo.

**Qual é o objetivo final deste primeiro passo?**
Ter uma visão completa e honesta de quais ações reais o site já oferece, antes de decidir o que declarar via WebMCP.

### Passo 2: escolher uma ação para começar

**Por que o artigo recomenda escolher só uma ação para começar?**
Para reduzir risco e permitir aprendizado focado antes de expandir para múltiplas ações ao mesmo tempo.

**Quais critérios definem uma boa primeira escolha?**
Ação mais usada, mais simples de descrever, e de menor risco caso algo dê errado na implementação.

**Por que busca e formulário de contato são exemplos comuns de boa primeira escolha?**
Porque já existem na maioria dos sites, são relativamente simples de entender, e erros nelas raramente causam dano grave.

**Um site de e-commerce deveria começar pela ação de finalizar compra?**
Não é recomendado como primeira escolha, dado o risco financeiro envolvido — melhor começar por busca de produto, por exemplo.

**Como saber qual ação é "mais usada" no meu site?**
Pode ser avaliado através de dados de analytics existentes ou pelo conhecimento da equipe sobre o comportamento típico dos visitantes.

**Vale escolher a ação mais fácil tecnicamente, mesmo que não seja a mais usada?**
Pode ser uma estratégia válida para o primeiro teste de aprendizado, mesmo que o valor de negócio imediato seja menor.

**Um site pode ter mais de uma boa candidata para começar?**
Sim, é comum ter algumas opções válidas — a escolha final pode considerar também facilidade de implementação técnica disponível.

**Vale pedir opinião da equipe técnica antes de escolher a primeira ação?**
Sim, a equipe técnica pode avaliar melhor a complexidade real de implementar cada ação candidata.

**Isso significa que a primeira escolha é definitiva e não pode mudar?**
Não, é apenas o ponto de partida — a lista completa do Passo 1 continua disponível para expandir depois.

**Qual é a mensagem central deste segundo passo?**
Escolher com critério (uso, simplicidade, baixo risco) evita começar por uma ação complexa demais para uma primeira experiência de aprendizado.

### Passo 3: escrever a descrição antes do código

**Por que escrever a descrição antes do código é recomendado?**
Porque força clareza sobre o que a ação realmente faz antes de qualquer decisão técnica de implementação.

**O que fazer se eu não conseguir escrever essa descrição com clareza?**
Isso é um sinal de que a própria ação precisa ser mais bem entendida antes de tentar declará-la tecnicamente.

**Essa descrição precisa ser técnica ou pode ser em linguagem simples?**
Deve ser em português claro e direto — é justamente o que depois vira a tooldescription usada pelo agente.

**Quantas frases essa descrição inicial deveria ter?**
Geralmente uma frase é suficiente para capturar o essencial do que a ação faz e quando deveria ser usada.

**Vale mostrar essa descrição para outra pessoa antes de prosseguir?**
Sim, pedir que alguém de fora do processo técnico leia e confirme se entendeu a ação é um bom teste de clareza.

**Essa descrição inicial já é exatamente o texto que vai no atributo tooldescription?**
Pode servir como base direta, ajustada conforme necessário para caber no formato técnico esperado.

**O que fazer se a descrição ficar muito longa ou complicada?**
Simplificar até capturar o essencial — descrições excessivamente longas tendem a confundir mais do que esclarecer.

**Vale escrever descrições alternativas e comparar qual fica mais clara?**
Pode ser um exercício útil, especialmente para ações com nuances que exigem cuidado na formulação.

**Esse passo é frequentemente pulado por quem implementa diretamente no código?**
Sim, é comum pular direto para o código, mas o artigo recomenda evitar essa tentação para garantir clareza antes da implementação técnica.

**Qual é a lição central deste terceiro passo?**
Clareza de linguagem sobre a ação vem antes de qualquer decisão técnica — pular essa etapa aumenta o risco de má implementação.

### Passo 4: implementar com a API certa

**Como decidir entre API Declarativa e API Imperativa para minha ação?**
Se a ação já é um formulário HTML simples, use a Declarativa; se envolve lógica mais complexa, use a Imperativa.

**Posso usar as duas APIs para ações diferentes no mesmo site?**
Sim, a escolha pode ser feita individualmente para cada ação, conforme sua natureza específica.

**O que exatamente adicionar num formulário para usar a API Declarativa?**
Os atributos toolname, tooldescription no elemento form, e toolparamdescription nos campos relevantes.

**O que exatamente escrever para usar a API Imperativa?**
Uma chamada a document.modelContext.registerTool() com nome, descrição, schema de entrada em JSON Schema, e a função execute.

**Preciso de conhecimento avançado de JavaScript para a API Imperativa?**
Conhecimento básico a intermediário de JavaScript geralmente é suficiente para implementar corretamente.

**A API Declarativa exige mudar a estrutura visual do formulário?**
Não, os atributos são adicionados sem alterar a aparência ou comportamento visual para usuários humanos.

**Quanto tempo leva, tipicamente, para implementar uma tool com a API Declarativa?**
Para um formulário já existente, pode ser relativamente rápido, muitas vezes questão de minutos a poucas horas.

**Quanto tempo leva, tipicamente, para implementar com a API Imperativa?**
Pode levar mais tempo, dependendo da complexidade da função execute e da lógica necessária para completar a ação.

**Vale consultar exemplos oficiais (como Pizza Maker ou Le Petit Bistro) ao implementar?**
Sim, exemplos documentados pela Chrome for Developers podem servir de referência para boas práticas de implementação.

**Qual é a mensagem central deste quarto passo?**
Escolher a API certa para o tipo de ação (Declarativa para formulário simples, Imperativa para lógica mais complexa) simplifica a implementação.

### Passo 5: testar de verdade

**Por que testar visualmente não é suficiente, segundo o artigo?**
Porque a implementação técnica da tool precisa ser verificada via console, não apenas observando a aparência da página.

**Qual é o primeiro comando recomendado para testar?**
await document.modelContext.getTools(), para confirmar que a tool aparece com nome, descrição e schema corretos.

**Como ativar a flag necessária para esse teste?**
Acessando chrome://flags/#enable-webmcp-testing, ativando a flag "WebMCP for testing" e reiniciando o navegador.

**Depois de confirmar a descoberta, qual é o próximo teste recomendado?**
Testar a execução com executeTool(), passando parâmetros válidos e inválidos para observar o comportamento em ambos os casos.

**Por que testar com parâmetros inválidos também é importante?**
Para verificar se a implementação trata erros adequadamente, em vez de falhar silenciosamente ou de forma confusa.

**O que fazer se a tool não aparecer no resultado de getTools()?**
Revisar se o registro (via atributos HTML ou registerTool) foi feito corretamente e se ocorreu antes da tentativa de descoberta.

**O que fazer se a execução falhar de forma inesperada?**
Revisar a função execute (API Imperativa) ou o comportamento do formulário (API Declarativa) em busca de erros de implementação.

**Vale testar em diferentes navegadores ou só no Chrome?**
No estágio atual, o Chrome é o navegador com implementação mais avançada e documentada para esse tipo de teste.

**Um teste bem-sucedido garante que a implementação está perfeita?**
Não garante perfeição, mas confirma que a base funcional está correta — testes adicionais em diferentes cenários ainda são recomendados.

**Qual é a mensagem central deste quinto passo?**
Testar tecnicamente via console, não apenas visualmente, é o que confirma que a implementação realmente funciona como esperado.

### Passo 6: ajustar sem desistir

**É normal a primeira tentativa de implementação não funcionar perfeitamente?**
Sim, é esperado — descrição confusa, schema incompleto ou execução com falha em algum caso são erros comuns na primeira tentativa.

**O que fazer quando a descrição da tool parece confusa nos testes?**
Reescrever de forma mais clara e específica, testando novamente até que fique inequívoca.

**O que fazer quando o schema não corresponde ao que a função execute espera?**
Revisar e ajustar o schema para bater exatamente com os parâmetros que a lógica de execução realmente processa.

**Quantas rodadas de ajuste são normais antes de considerar a implementação satisfatória?**
Não há um número fixo, mas várias rodadas de ajuste são comuns e fazem parte natural do processo de aprendizado.

**Isso conecta com o artigo sobre "dominar WebMCP" da série?**
Sim, esse ciclo de testar, errar e ajustar é exatamente o tipo de experiência prática discutida como vantagem competitiva em outro artigo.

**Vale documentar cada ajuste feito durante esse processo?**
Sim, documentar ajuda a entender o histórico de decisões e facilita ajustes futuros ou onboarding de outras pessoas da equipe.

**Um erro nessa fase de ajuste pode prejudicar o site em produção?**
Se os testes forem feitos com a flag experimental antes de expor a tool amplamente, o risco para produção é minimizado.

**Vale envolver outra pessoa para revisar os ajustes feitos?**
Pode ajudar a identificar problemas que passaram despercebidos durante o processo de ajuste individual.

**Quando considerar que a implementação está "pronta o suficiente"?**
Quando a descoberta, execução e retorno funcionam de forma consistente nos testes realizados, mesmo que ajustes futuros ainda sejam possíveis.

**Qual é a mensagem central deste sexto passo?**
Ajustar repetidamente após erros é parte esperada e valiosa do processo — desistir no primeiro problema perde o aprendizado que realmente importa.

### O que fazer depois da primeira ação funcionando

**O que o artigo recomenda fazer depois de uma implementação bem-sucedida?**
Voltar à lista do Passo 1 e escolher a próxima ação a declarar, repetindo o mesmo processo de seis passos.

**Existe pressa para implementar todas as ações da lista rapidamente?**
Não, o artigo recomenda expansão constante e testada, sem pressa artificial de terminar tudo de uma vez.

**Cada nova ação exige o mesmo nível de cuidado da primeira?**
Sim, cada ação nova merece o mesmo processo cuidadoso de descrição, implementação, teste e ajuste.

**A experiência da primeira implementação facilita as próximas?**
Sim, o aprendizado acumulado tende a acelerar e melhorar a qualidade das implementações subsequentes.

**Vale criar um processo documentado interno depois de algumas implementações?**
Sim, documentar um processo padrão ajuda a manter consistência e facilita replicar a implementação em novas ações ou até em novos projetos.

**Isso significa que a implementação de WebMCP é um processo contínuo, não um projeto único?**
Sim, tratar como processo contínuo de expansão gradual tende a gerar resultados mais sólidos ao longo do tempo.

**A Wortic pode ajudar a continuar essa expansão depois da primeira implementação?**
Sim, a Wortic pode apoiar tanto a primeira implementação quanto a expansão gradual para outras ações do site.

**Como entrar em contato para essa continuidade de apoio?**
Pelo formulário de e-mail ao final deste artigo.

**Esse roteiro de seis passos se aplica igualmente a sites pequenos e grandes?**
Sim, o processo é o mesmo, embora a escala e a quantidade de ações a considerar variem conforme o tamanho do site.

**Qual é a última frase deste artigo?**
Seis passos simples, repetidos com cuidado, valem mais do que qualquer teoria — comece pela ação mais simples do seu site, hoje.

### Erros comuns ao seguir este roteiro

**Qual é o erro mais comum ao pular o Passo 1 (listar ações)?**
Começar a implementar sem uma visão completa das ações disponíveis, escolhendo talvez uma ação menos ideal por falta de comparação.

**Qual é o erro mais comum ao pular o Passo 3 (escrever descrição antes)?**
Implementar tecnicamente uma tool com descrição vaga ou ambígua, que confunde agentes na hora de decidir usá-la.

**Qual é o erro mais comum no Passo 4 (escolha de API)?**
Usar a API Imperativa para uma ação simples que poderia ser resolvida com a Declarativa, aumentando desnecessariamente a complexidade.

**Qual é o erro mais comum no Passo 5 (testes)?**
Testar apenas visualmente, sem verificar via console se a tool realmente aparece e executa corretamente.

**Qual é o erro mais comum no Passo 6 (ajuste)?**
Desistir após o primeiro teste malsucedido, sem investigar e corrigir a causa do problema.

**Esses erros são exclusivos de iniciantes em WebMCP?**
Não necessariamente — mesmo desenvolvedores experientes em outras áreas podem cometer esses erros na primeira implementação específica de WebMCP.

**Vale revisar este checklist de erros comuns antes de cada nova implementação?**
Sim, pode ajudar a evitar repetir os mesmos problemas em implementações futuras de novas ações.

**Um erro em um desses passos invalida todo o processo?**
Não necessariamente — corrigir o passo específico onde o erro ocorreu geralmente resolve o problema sem precisar recomeçar tudo.

**Vale compartilhar esses erros comuns com a equipe antes de começar a implementar?**
Sim, antecipar esses erros pode acelerar o processo e evitar retrabalho desnecessário.

**Qual é a lição geral desta seção sobre erros comuns?**
Seguir os seis passos na ordem recomendada, sem pular etapas, reduz significativamente a chance de cometer esses erros comuns.

### Perguntas sobre ferramentas e recursos de apoio

**Existe alguma ferramenta que ajuda a validar minha implementação de WebMCP?**
A documentação do Chrome menciona ferramentas como o Model Context Tool Inspector, que podem auxiliar na inspeção da implementação.

**Vale usar apenas o console do navegador ou existem alternativas mais visuais?**
O console é o método mais direto e acessível hoje; ferramentas visuais complementares podem facilitar a inspeção, mas o console já é suficiente para testes básicos.

**Onde encontrar exemplos de código para me inspirar ao implementar?**
A documentação oficial do Chrome for Developers cita exemplos como Pizza Maker e Le Petit Bistro que podem servir de referência.

**Vale participar de comunidades online sobre WebMCP para tirar dúvidas?**
Pode ser útil, especialmente fóruns ou grupos de discussão relacionados ao desenvolvimento web e IA, onde a experiência de outros pode ajudar.

**Existe algum curso ou treinamento formal sobre implementação de WebMCP?**
Ainda é uma tecnologia recente sem cursos formais amplamente estabelecidos; a documentação oficial e a prática direta são os recursos mais confiáveis hoje.

**A Wortic oferece algum tipo de suporte técnico durante essa implementação?**
Sim, a Wortic pode apoiar diretamente na implementação, desde o mapeamento de ações até o teste final.

**Vale revisar a documentação oficial do W3C além da documentação do Chrome?**
Pode ser útil para entender o contexto mais amplo da especificação, embora a documentação do Chrome seja mais prática para implementação imediata.

**Um desenvolvedor júnior consegue seguir este roteiro sozinho?**
Para ações simples com a API Declarativa, sim; ações mais complexas com a API Imperativa podem se beneficiar de apoio de alguém mais experiente.

**Vale manter uma documentação interna de referência conforme implemento múltiplas tools?**
Sim, documentar decisões e aprendizados ao longo do processo facilita manutenção e replicação futura.

**Qual é o resumo desta seção sobre ferramentas e recursos?**
Console do navegador, documentação oficial e exemplos práticos são os recursos mais diretos disponíveis hoje para apoiar essa implementação.

### Fechamento sobre o roteiro prático

**Esse artigo é o mais prático da série sobre WebMCP?**
Sim, é especificamente estruturado como um guia de ação direta, complementando os artigos mais conceituais da série.

**Vale ler os artigos mais conceituais antes de seguir este roteiro prático?**
Pode ajudar a entender o contexto mais amplo, mas este artigo é autossuficiente para quem já quer agir diretamente.

**Esse roteiro de seis passos é aplicável a qualquer tipo de site?**
Sim, o processo geral se aplica independente do setor ou tamanho do site, ajustando apenas a ação específica escolhida.

**A Wortic segue esse mesmo roteiro em suas próprias implementações?**
Sim, a implementação no próprio blog da Wortic seguiu um processo similar de escolha, descrição, implementação e teste cuidadoso.

**Como a Wortic pode acelerar esse processo para quem não tem tempo de seguir sozinho?**
Assumindo a implementação completa em nome do cliente, desde o mapeamento até o teste final da tool declarada.

**Onde deixar contato para essa implementação assistida?**
No formulário de e-mail ao final deste artigo.

**Esse artigo garante sucesso total na primeira tentativa de implementação?**
Não garante perfeição na primeira tentativa, mas oferece um caminho estruturado que reduz significativamente a chance de erro grave.

**Vale voltar a este artigo como referência durante o processo de implementação?**
Sim, pode servir como checklist de referência a cada nova ação que for declarada via WebMCP.

**Esse é um bom artigo para compartilhar com uma equipe técnica que vai implementar WebMCP?**
Sim, oferece um roteiro claro e direto que pode orientar a equipe durante todo o processo de implementação.

**Qual é a última frase deste artigo?**
Não espere entender tudo sobre WebMCP antes de começar — siga os seis passos, comece pela ação mais simples, e aprenda fazendo.