Separate proposal from execution
What it is: The call produced by the model is an untrusted proposal until it passes validation and policy checks.
Why learn: The boundary prevents probabilistic text from turning directly into an effect.
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 proposal = await model.chooseTool(context);
const approved = await gate.evaluate(proposal, session);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
tool call
untrusted input
policy gate
execution
Validate the schema again
What it is: Even when the provider applies schemas, the runtime validates types, limits, enums, and extra fields.
Why learn: Defense in depth contains provider discrepancies and calls generated by external code.
| 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 result = validator.validate(tool.inputSchema, proposal.arguments);
if (!result.ok) return fail("INVALID_ARGUMENTS", result.errors);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
JSON Schema
prohibited coercion
limits
stable error
Apply policy before the effect
What it is: Risk, authentication, scope, and the need for confirmation are decided outside the model.
Why learn: The LLM can recommend; the application remains responsible for authorization.
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.
if (tool.annotations?.destructiveHint) {
await requireHumanConfirmation(proposal);
}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
authorization
risk
confirmation
scope
Execute with a budget and cancellation
What it is: Every execution receives an AbortSignal, deadline, and limits suited to the experience.
Why learn: An abandoned conversation shouldn’t keep the network, UI, or backend working indefinitely.
REFERENCE CODE
const signal = AbortSignal.any([turn.signal, AbortSignal.timeout(10_000)]);
const tools = await document.modelContext.getTools();
const tool = tools.find((item) => item.name === proposal.name);
if (!tool) throw new Error("Tool não está mais disponível");
return document.modelContext.executeTool(tool, proposal.arguments, { signal });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
AbortSignal
deadline
resource budget
cleanup
Normalize results and failures
What it is: The runtime converts heterogeneous returns into envelopes with status, data, evidence, and next action.
Why learn: A common format simplifies the loop without hiding the original error.
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
return { ok: false, code: "AUTH_REQUIRED", recovery: { action: "request_login" } };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
envelope
recoverable error
evidence
next action
Record a reproducible trace
What it is: Each execution links the turn, catalog, proposal, policy decision, duration, and sanitized result.
Why learn: The trace makes it possible to debug selection, execution, and effects without recording secrets.
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
Implement an executor that receives a model call, validates the intent, and returns a success, error, or recovery envelope.
Responsible Agent Developer criterion
The deliverable must work, explain its limitations, and preserve the human path when the experimental capability is unavailable.
trace.record({ turnId, tool: proposal.name, policy: approved.reason, durationMs, outcome });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
traceId
catalog version
latency
redaction
📦 Module delivery
Implement an executor that receives a model call, validates the intent, and returns a success, error, or recovery envelope.
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.