What EDI X12 taught me about designing agent-readable APIs

EDI X12 is a data format from 1979 that still moves a large share of business transactions in the US. It looks hostile: segments, qualifiers, element separators, semantics scattered across implementation guides that cost money to read. I expected to hate it. Integrating it for real-time transactions changed my mind in one specific way.

X12 is brutally explicit. Every field has a qualifier that says what kind of thing it is. There is no 'it's usually a string but sometimes an object.' The format assumes the reader is a dumb machine with no context, and that assumption is exactly right for LLM agents too. The failures I see in agents consuming modern JSON APIs are almost always implicit context: fields that mean different things depending on other fields, enums documented only in a changelog, nulls with three different meanings.

The lesson isn't 'use X12.' The lesson is: design responses so a reader with zero out-of-band context can parse them unambiguously. Qualify everything. Make the schema carry the semantics. When I expose tools to agents now, every response self-describes, and the agents' error rate drops in a way prompt engineering never achieved.

A 47-year-old format designed for machines that couldn't think turns out to be a decent spec for machines that almost can.