Comece pela jornada crítica
O que é: Uma tool nasce de um objetivo real do usuário, não de cada botão ou função existente no código.
Por que aprender: Mapear início, decisão, efeito e evidência impede que a integração copie a interface sem compreender a intenção.
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.
jornada: "encontrar e reservar uma vaga"
estado_inicial: "catálogo aberto"
resultado: "reserva preparada, ainda não confirmada"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
objetivo observável
estado inicial
efeito esperado
evidência final
Dê uma responsabilidade a cada tool
O que é: Ferramentas pequenas realizam uma intenção completa e não competem pela mesma chamada.
Por que aprender: Quando duas descrições parecem responder ao mesmo pedido, a LLM precisa adivinhar e a taxa de escolha correta cai.
| 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.
buscar_cursos({ tema, nivel })
consultar_curso({ cursoId })
verificar_vagas({ cursoId, turmaId })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
sem sobreposição
verbo preciso
fronteira clara
saída própria
Projete entradas para o agente
O que é: A entrada deve pedir apenas dados necessários e representar alternativas fechadas com enums quando possível.
Por que aprender: Schemas focados reduzem argumentos inventados, mas a validação real continua obrigatória no execute e no backend.
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.
nivel: {
type: "string",
enum: ["iniciante", "intermediario", "avancado"]
}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
campos mínimos
enum útil
descrição concreta
validação real
Escolha IDs e nomes compreensíveis
O que é: O agente pode conhecer o nome dito pelo usuário antes de conhecer o identificador interno do sistema.
Por que aprender: Separar busca, resolução e ação evita exigir IDs opacos cedo demais ou aceitar nomes ambíguos tarde demais.
CÓDIGO DE REFERÊNCIA
const curso = await buscar_cursos({ tema: "WebMCP" });
await consultar_curso({ cursoId: curso.id });É 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
nome descobre
ID identifica
resolução explícita
ambiguidade tratada
Registre somente o que faz sentido agora
O que é: O catálogo deve acompanhar rota, seleção, autenticação e etapa atual da jornada.
Por que aprender: Menos ferramentas disponíveis significam menos contexto e menos chamadas impossíveis.
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
await modelContext.registerTool(confirmarInscricao, {
signal: etapaConfirmacao.signal
});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
catálogo contextual
registro dinâmico
sessão visível
cleanup
Refatore um catálogo ruim
O que é: Nomes genéricos e sobrepostos precisam virar uma sequência que revele intenção e efeito.
Por que aprender: A entrega prova que o catálogo orienta o agente e também explica o fluxo para produto, segurança e QA.
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
Refatorar um catálogo ambíguo em uma sequência de tools com responsabilidade única e critérios de escolha.
Critério de Integrator responsável
A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.
// antes
curso(); gerenciar_curso(); resolver_inscricao();
// depois
buscar_cursos(); iniciar_inscricao(); 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
inventário
refatoração
teste de escolha
documentação
📦 Entrega do módulo
Refatorar um catálogo ambíguo em uma sequência de tools com responsabilidade única e critérios de escolha.
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.