Start with the critical journey
What it is: A tool starts with a real user goal, not with every existing button or function in the code.
Why learn: Mapping the start, decision, effect, and evidence prevents the integration from copying the interface without understanding its intent.
Before modeling
Write the person’s request, the current state, and the evidence that will prove completion.
Starting error
Starting with a function name or a button produces a tool with no clear human purpose.
Predict before opening the code
What information changes the decision? What effect needs to appear in the interface? Answer before implementing.
jornada: "encontrar e reservar uma vaga"
estado_inicial: "catálogo aberto"
resultado: "reserva preparada, ainda não confirmada"Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change on the page.
Also include a simulated failure and the observed behavior without WebMCP support.
Key concepts
observable objective
initial state
expected effect
final evidence
Give each tool one responsibility
What it is: Small tools fulfill a complete intent and do not compete for the same call.
Why learn: When two descriptions seem to answer the same request, the LLM has to guess, and the correct selection rate drops.
| Question | Strong contract | Weak contract |
|---|---|---|
| When to use it? | The description names intent and context. | “Does things” or “manages.” |
| What do you receive? | Only the data you need. | Generic, unlimited object. |
| What does it return? | Verifiable state and next action. | Text without a protocol. |
| How does it fail? | Code, reason, and recovery. | Opaque exception. |
Do
- ✓ Use specific verbs.
- ✓ Delimit inputs.
- ✓ State the evidence.
Avoid
- ✗ Mix intentions.
- ✗ Accept any object.
- ✗ Hide effects.
buscar_cursos({ tema, nivel })
consultar_curso({ cursoId })
verificar_vagas({ cursoId, turmaId })Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change on the page.
Also include a simulated failure and the observed behavior without WebMCP support.
Key concepts
no overlap
precise verb
clear boundary
own output
Design inputs for the agent
What it is: The input should request only the necessary data and represent closed alternatives with enums when possible.
Why learn: Focused schemas reduce invented arguments, but actual validation is still required in execute and on the backend.
Observe
Capture state, input, and context before the action.
Decide
Validate preconditions and choose the allowed transition.
Run
Apply the shared rule and respect cancellation.
Prove
Update the interface and return a structured result.
Checkpoint
If step 2 fails, the tool doesn't try to “make it work”: it returns an explicit recovery.
nivel: {
type: "string",
enum: ["iniciante", "intermediario", "avancado"]
}Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change on the page.
Also include a simulated failure and the observed behavior without WebMCP support.
Key concepts
minimum fields
useful enum
concrete description
real validation
Choose clear IDs and names
What it is: The agent may know the name spoken by the user before it knows the system's internal identifier.
Why learn: Separating search, resolution, and action avoids requiring opaque IDs too early or accepting ambiguous names too late.
REFERENCE CODE
const curso = await buscar_cursos({ tema: "WebMCP" });
await consultar_curso({ cursoId: curso.id });It is small, documented, and verifiable.
Reuses the application's actual rule.
Lets you verify the effect and continue.
Read the code as a contract
Highlight where input is validated, where the effect happens, where cancellation arrives, and where the UI is updated.
Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change on the page.
Also include a simulated failure and the observed behavior without WebMCP support.
Key concepts
name discovers
ID identifies
explicit resolution
ambiguity addressed
Record only what makes sense now
What it is: The catalog should track the route, selection, authentication, and current stage of the journey.
Why learn: Fewer available tools mean less context and fewer impossible calls.
Simulated failure
Run the scenario with missing state, invalid input, or unavailable capability.
Expected recovery
The response explains what failed, what remains safe, and which action can continue.
Minimum test matrix
✓ reproducible happy path
✓ actionable invalid input
✓ cancellation ends work
✓ fallback preserves the journey
✓ interface reflects the state
✓ backend maintains authorization
await modelContext.registerTool(confirmarInscricao, {
signal: etapaConfirmacao.signal
});Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change on the page.
Also include a simulated failure and the observed behavior without WebMCP support.
Key concepts
contextual catalog
dynamic registration
visible session
cleanup
Refactor a poor catalog
What it is: Generic and overlapping names need to become a sequence that reveals intent and effect.
Why learn: The implementation proves that the catalog guides the agent and also explains the flow to product, security, and QA.
Synthesis exercise
- 1. Explain the problem without using the technology name.
- 2. Map the state before and after.
- 3. Implement the smallest functional proof.
- 4. Trigger a failure and record the recovery.
- 5. Deliver code, evidence, and one known limitation.
Module challenge
Refactor an ambiguous catalog into a sequence of tools with a single responsibility and selection criteria.
Responsible Integrator criterion
The implementation must work, explain its limits, and preserve the human path when the experimental capability is unavailable.
// antes
curso(); gerenciar_curso(); resolver_inscricao();
// depois
buscar_cursos(); iniciar_inscricao(); confirmar_inscricao();Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change on the page.
Also include a simulated failure and the observed behavior without WebMCP support.
Key concepts
inventory
refactoring
choice test
documentation
📦 Module delivery
Refactor an ambiguous catalog into a sequence of tools with a single responsibility and selection criteria.
Acceptance criterion
The implementation works with WebMCP support and preserves the manual path when the API is unavailable.
Evidence
Include code, the tested scenario, the observed result, and a known limitation.
Technical sources
- Draft and official WebMCP repository
- Rendered specification
- Official snapshot: 26/08/2026 · commit 41d12f0. The declarative API remains experimental; validate the draft before production.