Boundary Translation
≈ Anti-Corruption Layer / Adapter / Facade
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)
> 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.
Before: The agent trusts the tool's contract
1# The upstream tool returns a bare boolean.2result = await tools.coverage_check(treatment=user_term)34# One False is doing four jobs here: the real no, the unmatched word,5# the failed lookup, and the thrown error. The agent cannot tell them6# apart, so an outage becomes a confident no to a customer.7if result:8 await agent.say("Yes, that's covered. Let's get you booked.")9else:10 await agent.say("Sorry, that isn't covered under your plan.")After: The boundary owns the contract
1VERDICTS = ("covered", "not_covered", "unresolved", "lookup_failed")23async def check(term: str) -> Verdict:4 key = normalize(term) # lowercase, trim, strip punctuation56 try:7 catalogue = await cache.get_or_fetch(tools.list_covered_treatments)8 except (UpstreamError, TimeoutError):9 return Verdict("lookup_failed") # never invent a verdict from a failure1011 match = resolve(key, catalogue) # see the matching ladder below12 if match is None:13 return Verdict("unresolved") # ask, do not refuse14 if match.split: # a category covering both covered and not15 return Verdict("unresolved", candidates=match.covered)1617 return Verdict("covered" if match.covered else "not_covered",18 canonical=match.name)> The resolve ladder
- Normalize: lowercase, trim, strip punctuation, collapse whitespace.
- Category match: callers speak in categories, and categories are usually a field you already have.
- Exact and singular or plural name match.
- Alias and synonym map: small, versioned, hand-maintained.
- Hypernym expansion: a parent term resolved through its members.
- Fuzzy fallback with a confidence threshold. Below the threshold, return unresolved, never a false no.
The agent's reasoning trace
1Caller: "is physio covered?"2 → normalize "physio"3 → category match miss4 → name match miss5 → alias map physio → physiotherapy6 → hypernym expansion physiotherapy → {assessment, treatment}7 → both covered → covered, canonical "physiotherapy"8Agent: proceeds with the bookingTraditional SWE
Anti-Corruption Layer
Agentic Pattern
Boundary Translation
Read the original pattern
- Anti-Corruption Layer pattern (Microsoft Azure Architecture Center)
- Anticorruption Layer, in the Domain-Driven Design reference (Eric Evans, Domain Language)
- Your agent skill is not an anti-corruption layer (the ACL applied to MCP, for schema and vocabulary) (Thoughtworks)
- Rediscovering Domain-Driven Design, one MCP server at a time (AWS, on dev.to)
Traditional
A system integrating with a legacy or third-party model puts an Anti-Corruption Layer between them, so the foreign model's assumptions never leak into the domain you control.
Agentic
The agent's reasoning is the domain being protected. A leaked bad value does not throw an exception. It becomes a confident sentence spoken to a user.
≈How They're Similar
Both translate at the edge. Both refuse to let an upstream model's shape dictate an internal one. Both let you ship without waiting on the other team.
≠Key Divergence
A classical ACL protects a data model, and corruption shows up as a bug you can catch in a test. Here, corruption shows up as a plausible answer. There is no stack trace for an agent that was told false and said "that isn't covered."
How far the damage travels depends on where the agent sits. A coding agent writes bad code and review catches it. A background agent writes bad data and someone finds it next week. A real-time agent says it out loud to a person who acts on it. Same defect, different blast radius, and the layer is the same in all three.
> Production Considerations
Classify every failure kind, and look at the distribution. Instrument the boundary by failure kind, not just success and error. The shape of the failures is the diagnosis. The most dangerous class is the upstream that returns an error dressed as a valid response: a gateway 5xx delivered with a 200 body, an empty result that looks like a real negative, a tool that errors by returning nothing at all. Those are invisible without a layer that is looking for them, whatever protocol they arrive over.
Uncertainty needs its own state. Most broken integrations are broken because the contract has nowhere to put "I don't know." Collapsing unknown into no is what turns a matching gap into a lost customer. Give uncertainty a state, and make the agent's behaviour for that state a question rather than a refusal.
Key Takeaway
Old mindset: Call the tool, branch on what it gives you.
New mindset: Decide what your agent is allowed to believe, then build the layer that guarantees it.
BuildBuild the Boundary Layer for a Coverage Tool. A third-party tool answers "is this treatment covered?" with a bare boolean. Build the layer between the agent and the tool so that an unmatched term comes back as unresolved, a failed lookup as lookup_failed, and never as a false no.
DebugDebug: Boundary Translation. An agent is telling 8% of callers a treatment is not covered. The upstream tool reports a 0% error rate. The verdict emitter is there. Find where the failures are going.
OptimizeTake the Boundary Off the Hot Path. Your boundary layer resolves every caller's term against a third-party coverage catalogue: a fetch, a resolver model for the fuzzy and hypernym steps, and a verdict writer that explains the state to the agent. It adds a network call and two model calls to every turn: $9.60 per 1,000 runs and 2.1 seconds. Introduce a cached index with a TTL so the warm path makes zero upstream calls, keep quality at 85 or better, and decide what the layer does on a cold cache with the upstream down.
PromptWrite the Agent's Instructions for Four Verdicts. Your boundary layer hands the agent one of four verdicts: covered, not_covered, unresolved, lookup_failed. Write the agent's system prompt so that each verdict produces exactly the right behaviour: unresolved produces exactly one clarifying question, and lookup_failed never asserts anything about coverage.
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.
Further Reading
Tool Use
The pattern this one protects. How an agent reaches outside itself, and why the call is the easy part.
State Management (MCP)
The protocol most boundaries now arrive over. A standard transport does not make a standard contract.
Exception Handling & Recovery
What the agent does once the boundary has named the failure. Retries, fallbacks, and telling the truth.
Guardrails & Safety
The other layer at the edge: what the agent may say and do, after it knows what is true.
Evaluation & Monitoring
Where the failure distribution lives. Instrument by kind, then read the shape.