Start with the user's request
What it is: Discovery starts with intent, constraints, and current state, not with blindly enumerating every tool.
Why learn: A normalized goal reduces noise even before capabilities are presented to the model.
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 without a clear human goal.
Predict before opening the code
What information changes the decision? What effect needs to appear in the interface? Answer before implementing.
const objetivo = { acao: "buscar", entidade: "curso", tema: "WebMCP", nivel: "iniciante" };Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
intent
constraints
context
success criterion
Read the catalog as a contract
What it is: Name, description, inputSchema, and annotations form the interface the agent can reason about.
Why learn: Treating the descriptor as data lets you validate, index, compare, and record decisions.
| Question | Strong contract | Weak contract |
|---|---|---|
| When should you use it? | The description names the intent and context. | “Does things” or “manages.” |
| What does it receive? | Only the data you need. | Generic and unlimited object. |
| What does it return? | Verifiable state and next action. | Text without a protocol. |
| How does it fail? | Code, rationale, and recovery. | Opaque exception. |
Do it
- ✓ Use specific verbs.
- ✓ Define the inputs.
- ✓ State the evidence.
Avoid
- ✗ Mix intentions.
- ✗ Accept any object.
- ✗ Hide effects.
const tools = await document.modelContext.getTools();
for (const tool of tools) validarDescritor(tool);Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
name
description
inputSchema
annotations
Filter before calling the model
What it is: Deterministic rules eliminate tools incompatible with the route, authentication, risk, or entity.
Why learn: The filter reduces tokens and prevents choices we already know are invalid.
Observe
Capture state, input, and context before taking action.
Decide
Validate preconditions and choose the allowed transition.
Execute
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.
const candidatas = tools.filter(tool =>
policy.isVisible(tool, pageState, userSession)
);Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
current route
session
risk
precondition
Create useful representations
What it is: The agent needs short descriptions, complete schemas, and consistent examples, without exposing internal implementation details.
Why learn: A stable representation improves selection and lets you compare models or prompts.
REFERENCE CODE
const promptTools = candidatas.map(({ name, description, inputSchema }) =>
({ name, description, inputSchema })
);It is small, described, and validatable.
Reuses the application's actual rule.
Allows you to verify the effect and continue.
Read the code as a contract
Underline where input is validated, where the effect occurs, 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 to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
serialization
context limit
example
drafting
Respond to the ephemeral catalog
What it is: Navigation, login, and selection can change the available tools during the same conversation.
Why learn: The agent must invalidate snapshots and rediscover capabilities when the document signals a change.
Induced failure
Run the scenario with missing state, invalid input, or unavailable capability.
Expected recovery
The response explains what failed, what remains safe, and what action can continue.
Minimum test matrix
✓ reproducible happy path
✓ actionable invalid input
✓ cancellation ends the work
✓ fallback preserves the user journey
✓ interface reflects the state
✓ backend maintains authorization
document.modelContext.addEventListener("toolchange", () => {
catalogCache.invalidate(location.href);
});Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
toolchange
snapshot
invalidation
rediscovery
Measure discovery quality
What it is: Coverage, precision, and the correct tool in the top k show whether the pipeline retrieves good candidates.
Why learn: Without discovery evals, a poor final answer may be attributed to the wrong component.
Synthesis exercise
- 1. Explain the problem without using the name of the technology.
- 2. Design the before and after states.
- 3. Implement the smallest functional proof.
- 4. Trigger a failure and record the recovery.
- 5. Deliver code, evidence, and a known limitation.
Module challenge
Build an inspector that captures the current catalog, explains each tool, and selects only the candidates relevant to a request.
Responsible Agent Developer criterion
The deliverable must work, explain its limitations, and preserve the human path when the experimental capability is unavailable.
caso: "curso iniciante"
esperadas: ["buscar_cursos"]
proibidas: ["confirmar_inscricao"]Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
recall
precision
top-k
dataset
📦 Module delivery
Build an inspector that captures the current catalog, explains each tool, and selects only the candidates relevant to a request.
Acceptance criteria
The deliverable works with WebMCP support and preserves the manual path when the API is unavailable.
Evidence
Include code, a tested scenario, the observed result, and a known limitation.
Technical sources
- WebMCP draft and official repository
- Rendered specification
- Official snapshot: 26/08/2026 · commit 41d12f0. The declarative API remains experimental; validate the draft before production.