Pattern [22]

Boundary Translation

≈ Anti-Corruption Layer / Adapter / Facade

[22]

TL;DR

A third-party tool's contract is not your agent's contract. Put a translation layer at every boundary you do not own, any MCP server, any API behind a function call, so their broken types, overloaded return values and silent failures never reach your agent's reasoning.

Anti-Corruption Layer (Domain-Driven Design)

SWE: Anti-Corruption Layer
Architecture Flow
agentgate
AgentagentNormalizergateUpstream TooldataResult ClassifiergateVerdict Emittergate

> Architecture Flow

Agent  ──▶  Boundary Layer  ──▶  Third-party tool
                  │
                  ├─ normalize input
                  ├─ call upstream
                  ├─ classify result
                  └─ emit one enumerated verdict
Agent  ◀──────────┘

The agent never touches the upstream tool. The layer emits one of a fixed set of states, never a raw response.

> Agentic Definition

Boundary Translation puts a layer of your own between the agent and any tool you do not control. The layer owns the contract the agent sees: it normalizes what goes out, classifies what comes back, and guarantees that every outcome, including failure, maps to a state the agent knows how to act on. It applies to every modality: an MCP server behind a coding agent, a vendor API behind a background workflow, a retriever behind a chat agent. The boundary is the subject, not the agent on this side of it.

This is an old idea pointed at a new boundary. Domain-driven design has used the Anti-Corruption Layer since 2003 to stop a legacy system's model leaking into a new one, and Thoughtworks and AWS have both applied it to MCP servers for the translation of shape and vocabulary. This pattern takes the other half: what the layer says when the tool cannot answer. The foreign model is an external tool's return contract, the domain being protected is the agent's reasoning, and a leak does not throw. It speaks.

Frequently Asked Questions

Isn't this just an adapter?

An adapter changes shape. This changes meaning. An adapter would still hand your agent one boolean; the point here is that the boolean cannot express what the agent needs to know, so the layer replaces the contract rather than reformatting it.

Why not just fix the upstream tool?

Often you should, and often you cannot: it belongs to another team, another company, or another release cycle. Building the layer means your deployment stops depending on their timeline. When they do fix their tool, you point the layer at it and the agent never notices.

Is this only for MCP tools?

No. Reach for it at any boundary where something you do not control feeds something that reasons. A retriever that returns the same empty list for "nothing matched" and "the index is down." A vendor API where a declined payment and a timeout both surface as a failed call. A second agent whose output format drifts between releases. A legacy enterprise system wrapped as a tool, where the wrapper inherits forty years of someone else's conventions. A multi-vendor tool catalogue where each vendor signals errors differently and your agent has to treat them all alike. The question is always the same: can the thing on the other side express every outcome my agent needs to distinguish? When the answer is no, the layer is where you fix it.

How many states should the verdict have?

As few as map to genuinely different agent behaviour. Four is common: proceed, decline, ask, and transfer. If two states produce the same action, collapse them. If one state is being used for two actions, you have the problem this pattern solves.