Most of this site so far has looked at one payload: the recommendation the underwriting agent writes at the end. But by the time it writes that, the run for submission SUB-1004 has already passed data across four other lines. The intake agent turned the broker's email into a submission. The underwriting agent called get_roof_assessment with arguments it wrote itself. The roof-data provider answered with a result. The assessment agent handed its findings over to the underwriting agent. Each of those payloads was produced by one party and read by another, and each could be wrong in its own way.
Here is what one of them looked like on a bad day, in this site's own case UW-S20. The roof-data provider, an outside service, answered:
{"status": "partial", "submission_id": "SUB-1004", "roof_age_years": 22, "source": "roof-data provider (stand-in)", "method": "aerial image, synthetic", "evidence_id": "EV-ROOF-0412", "notes": "Only part of the roof was visible in the image."}
partial is not a status the workflow knows. If nobody checks the tool result, the underwriting agent reads roof_age_years: 22 next to an unknown status and does what models do with unknown words: it guesses. Maybe it treats partial as ok. Then a roof age that the provider itself flagged as uncertain becomes a fact that decides an escalation. Nothing failed loudly. The output at the end was schema-valid.
Plain English. A boundary is any place where data passes from one party to another, and the receiver depends on its shape. For example: the line between the roof-data provider and the underwriting agent. A contract belongs at every boundary, not only at the last one.
One run, five crossings#
The path of SUB-1004, in order. Intake comes first; the series counts four boundaries after it.
| # | Boundary | Producer | Consumer | Schema |
|---|---|---|---|---|
| 0 | Intake | intake agent (a model) | the workflow | submission.v1 (63 fields) plus provenance |
| 1 | Tool input | underwriting agent (a model) | the tool runner, then get_roof_assessment | tool_inputs |
| 2 | Tool result | roof-data provider (outside, a stand-in here) | underwriting agent | roof_assessment.v1 |
| 3 | Agent handoff | assessment agent | underwriting agent | handoff.v1 envelope plus the payload's own schema |
| 4 | Final response | underwriting agent (a model) | the workflow, then the underwriter cockpit | recommendation.v1 (or v2), wrapped in recommendation_record.v1 |
Plain English. A tool input is the set of arguments a model writes when it asks for a tool to be called. For example: {"submission_id": "SUB-1004"} for get_roof_assessment.
Plain English. A tool result is what comes back from the tool. For example: the roof assessment above. Code produced it, but code you do not control, from data you did not see.
Plain English. A handoff is a payload one agent passes to another agent in the same workflow. For example: the assessment agent passes the roof assessment it validated, with the evidence ids, to the underwriting agent.
Plain English. The final response is what the run produces for the outside world. For example: the recommendation the underwriter sees. The model recommends; a person decides.
The example walks the whole path with run_path() in examples/uw-contracts/run_contracts.py. It validates each payload at its boundary and also tries one bad tool call. The real output:
intake intake agent (model) ok
tool input underwriting agent (model) ok
tool input (a bad call) underwriting agent (model) REJECTED
/submission_id: "1004" does not match ^SUB-[0-9]{4}$
tool result roof-data provider (stand-in) ok
agent handoff assessment agent ok
final response underwriting agent (model) ok
stored record the workflow (code) ok
The model here is a scripted stand-in, so these results show how the mechanism works, not how good any model is.
Diagram: The path of SUB-1004 · five crossings, each checked by the side that depends on it
Read left to right. Each box is a payload crossing from one party to another; the line under it names who validates it. Models and an outside provider produce; code checks at every receiving side.
- 0 · Intake
- Submission: 63 fields from the broker's email, with provenance; checked by the workflow.
- 1 · Tool input
- Arguments: Checked before the call; a bad call never runs.
- 2 · Tool result
- Roof assessment: Checked before it enters the model's context.
- 3 · Handoff
- Envelope and payload: The receiver checks the envelope, then the payload type it names.
- 4 · Final response
- Recommendation: Four stages, repair, then a record written by code.
The receiver validates, every time#
The obvious rule is "the producer makes sure its output is right". It is a good habit and a bad contract. At three of the five boundaries the producer is a model, which cannot be made to promise anything; at one it is an outside service whose code you cannot read. The only party that can enforce a contract is the one that depends on it. So the rule on this site is: the receiving side validates, with the schema it expects, before it uses the payload.
That makes the question "who validates?" easy to answer for each boundary:
| Boundary | Who validates | When | If it fails |
|---|---|---|---|
| Intake | the workflow | after the intake agent writes the submission, before any tool is called | re-ask the intake agent (UW-S17, UW-S18) |
| Tool input | the tool runner (code between the model and the tool) | before the call is made | return the error to the model as the tool's answer; the call never runs |
| Tool result | the workflow, for the receiving agent | before the result enters the model's context | count it, do not guess, degrade (UW-S20 becomes request_info) |
| Handoff | the receiving agent's code | before the payload is handed to its model | reject the handoff; the sender's run gets the error |
| Final response | the workflow | before anything is stored or shown | the four stages and the repair loop |
Two rows deserve a closer look.
The tool input is checked before the call, not by the tool. The bad call in the output above ("1004" without the prefix) never reaches the provider. If it did, the provider might answer "no record", and the agent would read that as a fact about the roof: there is no assessment for this building. A malformed argument becomes a false statement about the world. That is a worse failure than an error.
The tool result is checked before the model sees it. Once a value is in the model's context, no later check can take it out of the model's reasoning. For UW-S20 the workflow rejects the unknown status, records it as drift (see observability), and runs the rule check as if the assessment were unavailable. The real run:
UW-S20: degraded | /status "partial" is not one of "ok", "not_found", "timeout" | rule check after: {'outcome': 'request_info', 'rules': [], 'missing': ['roof_assessment']}
The run degrades to request_info with roof_assessment missing: the underwriter is asked to get an inspection, instead of being shown a confident escalation built on a guess.
Before AI. In a service architecture, a team that consumes another team's API validates the response at its client, even when both teams use the same schema library, because the other team deploys on its own schedule. The same is true here, with a twist: two of the producers are models, and their "deploy" is any change of instructions or settings. Validate at the receiver as if every producer were another team.
Where the schema lives, and who owns it#
A contract has an owner, usually the consumer, because the consumer is the one that breaks. In this example:
| Contract | Owned by | Why |
|---|---|---|
submission.v1 and the field catalog | the underwriting workflow | every later step reads the submission; the catalog is the workflow's definition of a quote request |
| tool input schemas | the tool's owner | the tool defines what it can accept |
roof_assessment.v1 | the workflow, as consumer | the provider sends what it sends; the workflow decides what it accepts |
handoff.v1 | the workflow, shared by all agents | one envelope for every handoff keeps the identifiers in one place |
recommendation.v1 and v2 | the workflow and the underwriter cockpit together | the cockpit renders it; the workflow validates it |
The tool rows touch the seam with another site. Where tool schemas live, how a tool call is executed, and how tools are exposed over a protocol is the subject of tools.sammuthu.com. This page only asks what has to be true of the data on each side of the call.
One protocol shows how the two sides of a tool boundary are written down. The Model Context Protocol (revision 2026-07-28, the current one when read on 2026-11-18; revision 2025-06-18 has the same rules) gives each tool an inputSchema, a "JSON Schema defining expected parameters", and an optional outputSchema. If an output schema is provided, "Servers MUST provide structured results that conform to this schema" and "Clients SHOULD validate structured results against this schema". Its security section says clients should "Validate tool results before passing to LLM". The same rule as this page, written as a protocol requirement. The specification also notes that its structuredContent "is server-produced result data and is unrelated to LLM "structured outputs" (schema-constrained model generation)": two different things that share a word.
What this is not. Messages between agents as a protocol (discovery, tasks, transport, the A2A protocol) belong to a2a.sammuthu.com. Deciding which agent runs next and under which condition belongs to orchestrate.sammuthu.com. This page owns the shape of what crosses each line and who checks it.
The envelope#
A payload alone does not say where it belongs. A roof assessment with roof_age_years: 22 handed from one agent to another could be for any submission, from any run, gathered under any evidence. When several submissions are processed at once, that missing context is how a value from one quote request ends up in another.
Plain English. An envelope is a small fixed wrapper around a payload that says what the payload is and where it belongs. For example: "this is a roof_assessment.v1, for SUB-1004, run run-7f3a, from the assessment agent to the underwriting agent, resting on EV-EMAIL-1004 and EV-ROOF-0412".
The handoff of the example, validated against handoff.v1:
{
"schema_version": 1,
"from_agent": "assessment_agent",
"to_agent": "underwriting_agent",
"submission_id": "SUB-1004",
"run_id": "run-7f3a",
"payload_type": "roof_assessment.v1",
"payload": {"status": "ok", "submission_id": "SUB-1004", "roof_age_years": 22, "source": "roof-data provider (stand-in)", "evidence_id": "EV-ROOF-0412", "method": "aerial image, synthetic"},
"evidence_ids": ["EV-EMAIL-1004", "EV-ROOF-0412"]
}
Each field of the envelope answers one question the receiver would otherwise guess:
| Field | Answers |
|---|---|
schema_version | which version of the envelope this is |
from_agent, to_agent | who sent it and who it is for; a payload for the cockpit must not reach an agent |
submission_id, run_id | which quote request and which execution; never mixed up with another |
payload_type | which schema the payload must be validated with |
evidence_ids | what the payload rests on, so the next agent can cite it and the domain stage can check citations |
Validation is two steps: the envelope against handoff.v1, then the payload against the schema payload_type names. Code fills the envelope; the model never writes run_id or submission_id (the schema design page explains why). Leave one field out and the receiver says so before anything else happens:
handoff without run_id: (root) required - missing required property "run_id"
Diagram: Validating a handoff · the envelope first, then the payload it names
Read left to right. The receiving agent's code checks the envelope against handoff.v1, picks the payload's schema from payload_type, checks the payload, and only then gives it to its model.
- Arrives
- Handoff: An envelope with a payload inside.
- 1 · Envelope
- Check handoff.v1: submission_id, run_id, from and to, payload_type, evidence_ids, all required.
- 2 · Payload
- Check the named schema: The payload is validated with the schema the envelope names.
- 3 · Use
- Into the model's context: Only a payload that passed both checks reaches the receiving model.
Try it: click a boundary#
The lab shows the five points on the path of SUB-1004. Click one to see its producer, its consumer, who validates it with which schema, the payload that passed, and what breaks when nobody checks it.
| Boundary | Producer | Consumer | Validator | If nobody checks it |
|---|---|---|---|---|
| Intake | intake agent (model) | the workflow | submission.v1 plus provenance | a guessed value (roof age 0 for unknown, square metres as square feet) becomes a fact for every later step |
| Tool input | underwriting agent (model) | get_roof_assessment | tool runner, before the call | a malformed id reaches the provider; "no record" is read as a fact |
| Tool result | roof-data provider (outside) | underwriting agent | the workflow, before the context | an unknown status (partial) or free-text notes reach the model as known answers |
| Agent handoff | assessment agent | underwriting agent | the receiver: envelope, then payload | the payload cannot be tied to its submission, run or evidence |
| Final response | underwriting agent (model) | the workflow, then the cockpit | four stages, then a record by code | an unknown word, an invented rule or requires_human: false reaches the underwriter |
In our insurance agent. The underwriter cockpit only ever reads recommendation records written by code. It never reads a model's raw output, a tool result or a handoff. Every boundary before it has been checked by the side that depended on it, so the cockpit can trust the shape of what it shows and spend its attention on the evidence.
For a coding agent. A coding agent crosses the same four boundaries: the arguments ofrun_tests(path)(tool input), the test runner's report (tool result), a plan handed from a planning agent to an implementing agent (handoff), and thechange_reportthat CI reads (final response). The runtime that executes those tool calls is described on harness.sammuthu.com.
Checklist#
- List every boundary of the run, including intake and every tool, with producer, consumer and schema.
- Validate at the receiver, before the payload is used; never rely on the producer's own check.
- Check tool arguments before the call and tool results before they enter a model's context.
- Treat an unknown enum value from outside as drift: reject, count, degrade; never map it to a known value.
- Wrap every handoff in an envelope with submission, run, payload type and evidence ids, filled by code.
- Validate the envelope first, then the payload with the schema the envelope names.
- Give every contract an owner, usually its consumer.
A rejected tool call is still an answerWhat the model sees when its arguments fail
When the tool runner rejects arguments, the model needs to know, or it will assume the call succeeded or retry blindly. The usual design returns the validation errors to the model as the tool's result, marked as an error, so the next step can correct the arguments. That is a re-ask at the tool boundary, and it counts against the same bounds as any other (see repair). The rejected call never reaches the tool, so it costs nothing outside the run.
Trust is not transitiveA validated payload handed on is validated again
The assessment agent validated the roof assessment. Should the underwriting agent validate it again inside the handoff? Yes, against the schema it expects. The two agents may be deployed separately, run different versions of roof_assessment, or be reached by a payload that never went through the assessment agent at all (a bug, a replay, a test). Validation is cheap; a check that exists only on the sending side protects only the sender.
Free text at a boundaryThe provider's notes field
roof_assessment.v1 has a notes field: free text from an outside provider, up to 1,000 characters. The schema can check that it is a string; it cannot check what the string says. Before the notes enter a model's context they are untrusted text, the same kind of risk as the broker's email (see security). A contract that needs only the age and the status can leave notes out of what is passed to the model, and keep them for the underwriter to read in the cockpit, encoded.
In one breath#
One run crosses five lines: intake, tool input, tool result, handoff, final response, and each needs a contract that the receiving side checks before it uses the payload, because the producers are models and outside services that cannot be made to promise anything. Check tool arguments before the call and tool results before the model sees them, treat unknown values from outside as drift instead of guessing, and wrap every handoff in an envelope that code fills with the submission, run, payload type and evidence. Then the cockpit only ever reads records that every boundary before it has vouched for.
You now know where contracts are needed and who checks them. The next page asks how to write a good one: names, required or optional, units, and where each value came from, in schema design.