Structured Tool Output

Use JSON, XML, or other tight schemas for inter-step communication instead of natural language. Avoid verbose wrappers that add tokens without adding information.

How It Works

Tool outputs are defined by a strict schema with required fields, fixed keys, and no free-form prose. The consuming agent parses the output deterministically without needing to interpret natural language descriptions.

Benefits

• eliminates ambiguous or verbose natural-language wrappers
• enables deterministic parsing and validation
• reduces prompt size by removing explanatory text the model does not need

Example

Instead of:

The search found 3 results. The first result is in file.py at line 10,
where the function foo is defined. The second result is in bar.py...

Return:

{
  "matches": [
    {"file": "file.py", "line": 10, "symbol": "foo"},
    {"file": "bar.py", "line": 25, "symbol": "bar"}
  ]
}

See Also

• Diff-Based Tool Output — diffs are a specific kind of structured output.
• Grep-Result Tool Output — search results are often structured as JSON.
• Fail Fast Validation — structured output enables deterministic validation.
• Generator Invocation — generator wrappers should return a tight result object rather than their stdout.
• Subagents as Context Firewalls — a firewalled child cannot infer the return shape, so the parent must specify it.

Tools

• OpenAI Structured Outputs — API feature enforcing JSON schema compliance, eliminating verbose parsing instructions.
• Anthropic Tool Use — designed for concise tool input/output schemas.
• Instructor — structured output validation and generation for LLM tool calls.