All chapters
  1. Start hereParseable is not valid. Valid is not correct
  2. Foundations · 1From free text to fields and records: why contracts matter
  3. Foundations · 2Syntax, schema, semantics, business validity: four different kinds of right
  4. Foundations · 3JSON and JSON Schema: types, enums, nullable fields, unions and nested objects
  5. Building · 4Typed models: Pydantic in Python, records and Bean Validation in Java
  6. Building · 5Provider output modes: prompting, JSON mode, constrained decoding and tool arguments
  7. Building · 6Tool input, tool result, agent handoff, final response: four contracts on one path
  8. Building · 7Schema design: names, required or optional, and where each value came from
  9. Operating · 8Validation stages: parse, schema, cross-field, domain rules
  10. Operating · 9Errors and repair: retry, clarify, correct within bounds, fall back
  11. Operating · 10Schema evolution: versions, compatibility and migrations
  12. Operating · 11Security: a valid string can still be an attack
  13. Operating · 12Observing contracts: validation failures, schema drift and replay artifacts
  14. Operating · 13Testing contracts: golden examples, property-based tests, fuzzing and contract suites
  15. Reference · 14Frameworks and standards: what each one checks for you
  16. Reference · 15Advanced: partial objects in a stream, polymorphism, multilingual data and typed events
  17. Reference · 16The insurance lab: one submission, four contracts, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Building · 6

Tool input, tool result, agent handoff, final response: four contracts on one path

One run crosses four boundaries. Who writes each payload, who must validate it, and what breaks when a boundary has no contract.

What you will understand
Four boundaries
Tool input, tool result, agent handoff, final response: one run crosses all four.
Who validates
The receiving side checks, every time, whoever produced the payload.
The envelope
What travels around a payload: which submission, which run, which type, which evidence.
Unchecked
What each boundary lets through when nobody owns its contract.

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.

#BoundaryProducerConsumerSchema
0Intakeintake agent (a model)the workflowsubmission.v1 (63 fields) plus provenance
1Tool inputunderwriting agent (a model)the tool runner, then get_roof_assessmenttool_inputs
2Tool resultroof-data provider (outside, a stand-in here)underwriting agentroof_assessment.v1
3Agent handoffassessment agentunderwriting agenthandoff.v1 envelope plus the payload's own schema
4Final responseunderwriting agent (a model)the workflow, then the underwriter cockpitrecommendation.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.

  1. 0 · Intake
    1. Submission: 63 fields from the broker's email, with provenance; checked by the workflow.
  2. 1 · Tool input
    1. Arguments: Checked before the call; a bad call never runs.
  3. 2 · Tool result
    1. Roof assessment: Checked before it enters the model's context.
  4. 3 · Handoff
    1. Envelope and payload: The receiver checks the envelope, then the payload type it names.
  5. 4 · Final response
    1. 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:

BoundaryWho validatesWhenIf it fails
Intakethe workflowafter the intake agent writes the submission, before any tool is calledre-ask the intake agent (UW-S17, UW-S18)
Tool inputthe tool runner (code between the model and the tool)before the call is madereturn the error to the model as the tool's answer; the call never runs
Tool resultthe workflow, for the receiving agentbefore the result enters the model's contextcount it, do not guess, degrade (UW-S20 becomes request_info)
Handoffthe receiving agent's codebefore the payload is handed to its modelreject the handoff; the sender's run gets the error
Final responsethe workflowbefore anything is stored or shownthe 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:

ContractOwned byWhy
submission.v1 and the field catalogthe underwriting workflowevery later step reads the submission; the catalog is the workflow's definition of a quote request
tool input schemasthe tool's ownerthe tool defines what it can accept
roof_assessment.v1the workflow, as consumerthe provider sends what it sends; the workflow decides what it accepts
handoff.v1the workflow, shared by all agentsone envelope for every handoff keeps the identifiers in one place
recommendation.v1 and v2the workflow and the underwriter cockpit togetherthe 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:

FieldAnswers
schema_versionwhich version of the envelope this is
from_agent, to_agentwho sent it and who it is for; a payload for the cockpit must not reach an agent
submission_id, run_idwhich quote request and which execution; never mixed up with another
payload_typewhich schema the payload must be validated with
evidence_idswhat 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.

  1. Arrives
    1. Handoff: An envelope with a payload inside.
  2. 1 · Envelope
    1. Check handoff.v1: submission_id, run_id, from and to, payload_type, evidence_ids, all required.
  3. 2 · Payload
    1. Check the named schema: The payload is validated with the schema the envelope names.
  4. 3 · Use
    1. 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.

BoundaryProducerConsumerValidatorIf nobody checks it
Intakeintake agent (model)the workflowsubmission.v1 plus provenancea guessed value (roof age 0 for unknown, square metres as square feet) becomes a fact for every later step
Tool inputunderwriting agent (model)get_roof_assessmenttool runner, before the calla malformed id reaches the provider; "no record" is read as a fact
Tool resultroof-data provider (outside)underwriting agentthe workflow, before the contextan unknown status (partial) or free-text notes reach the model as known answers
Agent handoffassessment agentunderwriting agentthe receiver: envelope, then payloadthe payload cannot be tied to its submission, run or evidence
Final responseunderwriting agent (model)the workflow, then the cockpitfour stages, then a record by codean 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 of run_tests(path) (tool input), the test runner's report (tool result), a plan handed from a planning agent to an implementing agent (handoff), and the change_report that CI reads (final response). The runtime that executes those tool calls is described on harness.sammuthu.com.

Checklist#

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.