Comece pelo pedido do usuário
O que é: Descoberta começa com intenção, restrições e estado atual, não com a enumeração cega de todas as tools.
Por que aprender: Um objetivo normalizado reduz ruído antes mesmo de apresentar capacidades ao modelo.
Antes de modelar
Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.
Erro de partida
Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.
Preveja antes de abrir o código
Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.
const objetivo = { acao: "buscar", entidade: "curso", tema: "WebMCP", nivel: "iniciante" };Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
intenção
restrições
contexto
critério de sucesso
Leia o catálogo como contrato
O que é: Nome, descrição, inputSchema e annotations formam a interface que o agente consegue raciocinar.
Por que aprender: Tratar o descritor como dado permite validar, indexar, comparar e registrar decisões.
| Pergunta | Contrato forte | Contrato fraco |
|---|---|---|
| Quando usar? | A descrição nomeia intenção e contexto. | “Faz coisas” ou “gerencia”. |
| O que recebe? | Somente dados necessários. | Objeto genérico e ilimitado. |
| O que devolve? | Estado e próxima ação verificáveis. | Texto sem protocolo. |
| Como falha? | Código, motivo e recuperação. | Exceção opaca. |
Faça
- ✓ Use verbos específicos.
- ✓ Delimite entradas.
- ✓ Declare a evidência.
Evite
- ✗ Misturar intenções.
- ✗ Aceitar qualquer objeto.
- ✗ Esconder efeitos.
const tools = await document.modelContext.getTools();
for (const tool of tools) validarDescritor(tool);Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
name
description
inputSchema
annotations
Filtre antes de chamar o modelo
O que é: Regras determinísticas eliminam tools incompatíveis com rota, autenticação, risco ou entidade.
Por que aprender: O filtro diminui tokens e impede escolhas que já sabemos serem inválidas.
Observe
Capture estado, entrada e contexto antes da ação.
Decida
Valide pré-condições e escolha a transição permitida.
Execute
Aplique a regra compartilhada e respeite cancelamento.
Prove
Atualize a interface e devolva resultado estruturado.
Ponto de controle
Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.
const candidatas = tools.filter(tool =>
policy.isVisible(tool, pageState, userSession)
);Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
rota atual
sessão
risco
pré-condição
Crie representações úteis
O que é: O agente precisa de descrições curtas, schemas íntegros e exemplos coerentes, sem despejar implementação interna.
Por que aprender: Uma representação estável melhora escolha e permite comparar modelos ou prompts.
CÓDIGO DE REFERÊNCIA
const promptTools = candidatas.map(({ name, description, inputSchema }) =>
({ name, description, inputSchema })
);É pequena, descrita e validável.
Reutiliza a regra real da aplicação.
Permite verificar efeito e continuar.
Leia o código como contrato
Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.
Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
serialização
limite de contexto
exemplo
redação
Reaja ao catálogo efêmero
O que é: Navegação, login e seleção podem alterar as tools disponíveis durante a mesma conversa.
Por que aprender: O agente deve invalidar snapshots e redescobrir capacidades quando o documento sinaliza mudança.
Falha provocada
Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.
Recuperação esperada
A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.
Matriz mínima de teste
✓ caminho feliz reproduzível
✓ entrada inválida acionável
✓ cancelamento encerra trabalho
✓ fallback preserva a jornada
✓ interface reflete o estado
✓ backend mantém autorização
document.modelContext.addEventListener("toolchange", () => {
catalogCache.invalidate(location.href);
});Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
toolchange
snapshot
invalidação
redescoberta
Meça a qualidade da descoberta
O que é: Cobertura, precisão e tool correta no top-k revelam se o pipeline recupera boas candidatas.
Por que aprender: Sem evals de descoberta, uma resposta final ruim pode ser atribuída ao componente errado.
Exercício de síntese
- 1. Explique o problema sem usar o nome da tecnologia.
- 2. Desenhe o estado anterior e posterior.
- 3. Implemente a menor prova funcional.
- 4. Provoque uma falha e registre a recuperação.
- 5. Entregue código, evidência e uma limitação conhecida.
Desafio do módulo
Construir um inspetor que captura o catálogo atual, explica cada tool e seleciona apenas as candidatas relevantes para um pedido.
Critério de Agent Developer responsável
A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.
caso: "curso iniciante"
esperadas: ["buscar_cursos"]
proibidas: ["confirmar_inscricao"]Indo mais fundo: evidência que vale guardar
Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.
Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.
Conceitos-chave
recall
precision
top-k
dataset
📦 Entrega do módulo
Construir um inspetor que captura o catálogo atual, explica cada tool e seleciona apenas as candidatas relevantes para um pedido.
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.