Promova um formulário a ferramenta
O que é: Os atributos toolname e tooldescription declaram a intenção do formulário sem remover sua semântica HTML.
Por que aprender: É o caminho de menor esforço para jornadas que já possuem campos, validação e botão de envio.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
<form
toolname="solicitar_contato"
tooldescription="Envia uma solicitação de contato para a equipe comercial.">
<!-- campos e submit continuam normais -->
</form>Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
form continua HTML
toolname identifica
descrição orienta
progressive enhancement
Descreva parâmetros sem ambiguidade
O que é: O name do controle vira a propriedade; toolparamdescription explica ao agente o significado e o formato esperado.
Por que aprender: Labels ajudam pessoas, enquanto descrições precisas reduzem preenchimentos plausíveis porém errados.
✓ Faça
- ✓ Declare name é chave de forma observável.
- ✓ Preserve label serve pessoas no fluxo manual.
- ✓ Teste o resultado e o cancelamento.
✗ Evite
- ✗ Esconder efeitos atrás de descrições vagas.
- ✗ Confiar na tool como autorização.
- ✗ Remover o fallback da interface.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
<label for="email">E-mail profissional</label>
<input id="email" name="email" type="email" required
toolparamdescription="E-mail corporativo para retorno da equipe." />Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
name é chave
label serve pessoas
descrição serve escolha
exemplos esclarecem
Sintetize schema com controles HTML
O que é: Tipos de input, required, min, max e opções contribuem para o schema sintetizado pelo navegador.
Por que aprender: Reutilizar restrições semânticas mantém o formulário manual e a tool alinhados.
Defina o contrato
Nome, descrição, entrada, resultado e limites ficam explícitos antes da implementação.
Observe a execução
Registre entrada, estado visível, cancelamento e saída sem expor dados sensíveis.
Verifique a evidência
A tool só está pronta quando o efeito e o retorno podem ser reproduzidos.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
<select name="nivel" required
toolparamdescription="Nível atual em WebMCP.">
<option value="iniciante">Iniciante</option>
<option value="intermediario">Intermediário</option>
</select>Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
required vira requisito
select limita valores
min/max restringem
algoritmo ainda evolui
Controle a confirmação com toolautosubmit
O que é: Sem toolautosubmit, o agente preenche e a página devolve o foco ao usuário para revisão; com o atributo, o envio pode ocorrer automaticamente.
Por que aprender: A escolha deve seguir o risco e o efeito da ação, não apenas a conveniência do fluxo.
💡 Teste de realidade
Implemente este tópico com um caminho feliz, uma entrada inválida e um cancelamento. Registre o que a pessoa viu e o que o agente recebeu.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
<form toolname="buscar_cursos" toolautosubmit>…</form>
<!-- Consulta reversível: autosubmit pode fazer sentido. -->
<form toolname="confirmar_inscricao">…</form>
<!-- Efeito relevante: preserve confirmação humana. -->Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
ausente pede revisão
booleano habilita envio
risco orienta decisão
UI mostra preenchimento
Responda com SubmitEvent.respondWith
O que é: Em envio acionado por agente, agentInvoked permite identificar a origem e respondWith entrega uma Promise com o resultado estruturado.
Por que aprender: O agente recebe um protocolo verificável sem depender de raspar a página após o envio.
✓ Faça
- ✓ Declare preventDefault primeiro de forma observável.
- ✓ Preserve teste agentInvoked no fluxo manual.
- ✓ Teste o resultado e o cancelamento.
✗ Evite
- ✗ Esconder efeitos atrás de descrições vagas.
- ✗ Confiar na tool como autorização.
- ✗ Remover o fallback da interface.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
form.addEventListener('submit', (event) => {
event.preventDefault();
const task = enviarContato(new FormData(form));
if (event.agentInvoked && event.respondWith) {
event.respondWith(task);
}
});Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
preventDefault primeiro
teste agentInvoked
Promise como resposta
erro é estruturado
Separe o draft do código de produção
O que é: A API declarativa e os eventos toolactivated/toolcanceled continuam como propostas abertas no draft oficial; toolchange é o evento atualmente especificado.
Por que aprender: Um Builder precisa distinguir modelo conceitual, proposta experimental e API normativa antes de prometer compatibilidade em produção.
💡 Teste de realidade
Implemente este tópico com um caminho feliz, uma entrada inválida e um cancelamento. Registre o que a pessoa viu e o que o agente recebeu.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
// API especificada no snapshot de 26/08/2026
document.modelContext?.addEventListener('toolchange', atualizarCatalogo);
// toolactivated/toolcanceled: propostas em discussão; não dependa delas
// em produção até entrarem na interface normativa.Estado do padrão
A seção declarativa da especificação está marcada como TODO. Use esta aula para compreender a direção do padrão e valide o explainer oficial antes de experimentar atributos.
Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
estado visual explícito
cancelamento limpa UI
draft pode mudar
fallback não depende disso
📦 Entrega do módulo
Instrumentar um formulário de contato com validação, confirmação humana e resposta estruturada com protocolo.
Critério de aceite
A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.
Evidência
Inclua código, cenário testado, resultado observado e uma limitação conhecida.
Fontes técnicas
- Draft e repositório oficial WebMCP
- Especificação renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. A API declarativa permanece experimental; valide o draft antes de produção.