JIMDRURY.
Jim Drury
Flat blue editorial illustration: an agent sphere sends two tool calls at a z.object contract wall; the invented { customerId: 123 } is stopped with a cross while { customer_id: "c_8f2" } passes through to a packages/contracts module shared by web, agent-tools and mcp-jira.
agents

TypeScript is the contract your agents keep breaking

4 MIN READ

I caught an agent inventing a customerId: number field on a tool that has always taken customer_id: string. It compiled in the model's head. It exploded in production's face.

That is when I stopped treating TypeScript as "the language the UI happens to use" and started treating it as the contract layer for anything an agent is allowed to touch.

Agents generate API surface all day

Humans write a handful of endpoints a week and argue about names in PR review.

Agents propose tool calls constantly: search, create, update, deploy, comment, refund. Every call is a tiny API. If the inputs are vibes, you get vibes-shaped outages.

Zod (or an equivalent runtime schema) is how you make the model fail closed:

The schema is not bureaucracy. It is the fence at the cliff edge.

Why TypeScript specifically

Because the same types can serve three audiences without a translation layer:

  1. Humans reading the tool file in a PR

  2. Compilers catching obvious nonsense before merge

  3. Agents discovering tool shapes through MCP / framework introspection

That triple duty is rare. OpenAPI can do some of it. JSON Schema can do some of it. In a TS shop shipping Eve tools, MCP servers, and Next.js route handlers, Zod-in-TypeScript is the boring centre of the Venn diagram.

I favour boring centres. They survive reorgs.

Shared schemas beat duplicated truth

Pattern I keep pushing:

One CreateIssueInput. Three consumers. When the agent invents a field, it invents it against a wall that already exists in git.

If your UI form accepts summary as required and your agent tool secretly makes it optional "for flexibility", you do not have flexibility. You have drift.

Generated surface still needs handwritten edges

Agents will happily generate tool wrappers. Let them draft. Do not let them own the schema without review.

Rules of thumb that have saved us pain:

  • Schemas are reviewed like public API.

  • Enums beat free-text whenever the domain is closed.

  • Defaults belong in the schema, not in prompt folklore.

  • Output schemas matter too: structured results the next tool can consume beat markdown soup.

  • Breaking changes bump versions; agents pin versions like any other client.

The mischievous bit

Once you do this well, you will notice something awkward: a lot of "prompt engineering" was compensating for missing types.

Tighten the contract and the prompts get shorter. The model spends fewer tokens apologising for malformed JSON and more tokens doing the job.

Thoughts

If agents are going to generate your API surface all day, TypeScript is not a preference. It is the seatbelt.

Similar Articles