An output contract is the part of a prompt that says exactly what you want back. Without one, you get the model's default: a friendly paragraph, a recap of your question, a list of caveats, and the answer somewhere in the middle.
Contracts matter more for agents than for chat, because agent output often feeds a next step: a script parses it, another agent reads it, or you paste it into a PR.
Four parts of a contract
- Format: diff, JSON, Markdown table, bullet list, a single line.
- Skeleton: the exact fields or headings.
- Limits: maximum items, lines or words.
- Gap handling: what to output when information is missing.
Example: a JSON contract
Review the diff below for security issues.
Return only JSON, no prose, matching:
{
"issues": [
{"file": string, "line": number, "severity": "high"|"medium"|"low",
"problem": string (max 20 words), "fix": string (max 20 words)}
],
"summary": string (max 25 words)
}
If there are no issues, return {"issues": [], "summary": "No issues found."}.The "if there are no issues" line is gap handling. Without it, some models invent a low-severity issue to fill the list.
Example: a review summary for humans
Output:
- Line 1: verdict, one of APPROVE / REQUEST CHANGES.
- Then at most 5 bullets, most important first, each "path:line - problem - fix".
- No introduction, no closing summary.Use the host's structured output when you can
Many APIs can enforce a JSON Schema on the response (often called structured outputs or JSON mode). When you call a model from code, prefer that over asking nicely: the API guarantees the shape. In an interactive agent, a clear contract in the prompt is the next best thing. Check the result once with a parser and tell the agent when it drifts.
Contracts for subagents
When a main agent delegates (see the Agent Building Blocks course), the subagent's output lands in the main context. A tight contract there protects your budget:
Return at most 15 lines: <path>:<line> | <symbol> | <why it matters>.
End with: START HERE: <one path>.
Step by step: add a contract to a prompt you reuse
- Pick a prompt you run often (code review, test plan, commit message).
- Look at the last three results. Note what you deleted or rewrote each time.
- Write a contract that would have produced the edited version: format, skeleton, limits, gaps.
- Run the prompt on two new inputs. If you still edit the output, tighten the skeleton.
Common mistakes
- Length in vague words. "Brief" means different things to different models. Use numbers.
- Skeleton without types. Say
"severity": "high"|"medium"|"low", not justseverity. - Contradictions. "Be thorough" plus "max 3 bullets" makes the model choose; it may choose wrong.
- Forgetting the empty case. Always say what to return when there is nothing to report.
Practice: tighten a vague request
Before: "Review this PR and tell me what you think."
After, with a contract:
Review the diff in this PR for correctness and security only.
Output exactly:
- Verdict: approve | request changes
- Blocking issues: numbered list, each with file:line and a one-line fix (or "none")
- Non-blocking: at most 3 bullets
No praise, no restating the diff.Run both on the same PR and compare: the second is shorter, easier to skim, and you can tell at a glance whether it followed the contract.
Quick check
-
What are the four parts of an output contract?Format, skeleton, limits and gap handling.
-
Your review prompt sometimes invents trivial issues. What part is missing?Gap handling: say what to return when there are no issues.
-
When should you prefer an API-level schema over a prompt?When you call the model from code and need the shape guaranteed.






