← All questions
AgentsMedium· Agents & Orchestration

Your agent's tools return JSON. Where does that break?

Two places, in practice:

Schema drift. A tool’s response shape changes upstream — a field gets renamed, a type changes from a number to a string — and the agent silently mis-parses it rather than failing loudly. This argues for validated, typed interfaces on every tool boundary, not just a loosely shaped “returns JSON” contract.

Serialization of payloads. JSON is a fine envelope for structured arguments and a bad container for freeform content. If the payload contains code, or a document, or anything with its own quotes and newlines, stuffing it into a JSON string field means every quote gets escaped and every newline gets encoded — the content moves off the distribution the model was trained on, and that invites subtle, silent corruption that parses without error and breaks later.

My rule: keep structured JSON schema for metadata and routing, and use delimited freeform text blocks (not JSON-escaped strings) for anything that’s actually a document or a piece of code.

Code playground (Python)