Prose is a lossy interface between agents
A research agent may retrieve the correct match, then summarize it for a writing agent. If the handoff is only prose, stable IDs disappear, timestamps are reformatted, missing fields become assumptions, and the distinction between a source fact and interpretation is lost. The final answer can no longer be reproduced even though the first tool call was sound.
Define a JSON schema for the handoff. Require the task, selected resource IDs, query parameters, source facts, inferences, uncertainty, request ID, source timestamp, and retrieval timestamp. Validate it before the next agent sees it. Unknown values should be null with a reason, not omitted in a way that invites completion from model memory.
Keep the envelope small enough to audit
Do not pass an entire API response through every stage by default. Retain the original response in controlled storage and pass the fields required for the next decision with a reference to that evidence. This reduces prompt size and limits accidental exposure while keeping the chain reproducible.
Version the handoff schema and reject unknown versions. If a new workflow requires lineups or player data that the current contract does not provide, the schema change should not create those fields out of thin air. Add the capability only after the data source, API contract, tests, and reviewer have all moved together.
{
"schema_version": "1",
"resource_ids": {"match_id": "match_example"},
"source_facts": [],
"inferences": [],
"uncertainty": {"value": null, "reason": "not in source"},
"retrieved_at": "2026-07-28T05:10:00Z"
}A handoff your agent can actually follow
Treat an AI agent as a planner and transformer, not as the database. Give it a narrow task, the exact resources it may call, the response fields it may quote, and a stop condition for missing data. Keep bearer credentials in the server-side tool implementation rather than in the prompt, transcript, browser, or generated source file.
The handoff below is deliberately operational. It asks for evidence before prose, makes uncertainty visible, and keeps the model inside the current football API contract. Adapt the output format to your product, but preserve the rules about stable IDs, UTC timestamps, freshness, and error handling.
Return JSON that validates against the supplied schema.
Keep source_facts and inferences in separate arrays.
Use null plus an uncertainty reason for unknown values.
Preserve stable IDs, UTC timestamps, request ID, and retrieved_at without rewriting them.What the human reviewer still owns
Automation can verify schemas and repeatable checks, but publication and product decisions still need a person. Review the selected competition, season, team, and match IDs; confirm that the time window matches the user’s question; and read the final answer against the retrieved JSON. A fluent explanation is not evidence that the underlying call was correct.
For time-sensitive football AI, record when the source was ingested and when the agent retrieved it. If the workflow cannot establish those timestamps, qualify the result instead of presenting it as current. The same rule applies to unavailable capabilities: do not quietly substitute fixtures or results for lineups, player statistics, odds, expected goals, injuries, or live events.
- Confirm every quoted fact appears in the retained API response.
- Exercise the empty, 401, 404, 429, and 503 paths before launch.
- Keep model interpretation separate from source facts in logs and user-facing output.
- Reject coercion that turns missing values into zero, empty strings, guessed labels, or an inferred match status.
Continue with the contract, not a guess
Start with the public contract and coverage ledger, then move into implementation only when the capability you need is marked available. The related guide gives your next agent-first pattern without requiring an undocumented endpoint.