Works On My Machine logo ~/works-on-my-machine

❯ Notes from inside developer platforms. IDP, CI/CD, DX, and the gaps between them.

❯ ~/blog/three-ways-to-go-broke-on-context

Three Ways to Go Broke on Context

Part 2 of 3 in the Context Is a Budget series. Previous: The Expensive Part Is Remembering. Part 3, on rules over documents, is coming soon.

The PR Claude Code wrote for me identified each deployment artifact twice: once by commit SHA, once by semver tag.

On a data platform I work on, the deployment pipeline exists in more than one version, and the versions disagree. Some expect a commit SHA to identify an artifact. Others expect a semver tag, a version label like v1.4.2. The agent saw both requirements and nothing saying which one won, so it did the diplomatic thing and used both. The change compiled, passed review, and made one basic question unanswerable: which artifact is live?

The agent wasn’t wrong, exactly. It was keeping the peace.

The first post in this series was the dollar side of context: in a long session you pay for what the model re-reads, not for what it writes. This post is the failure side — what happens when the context the agent needs was never knowable, sits somewhere it can’t reach, or was never decided by anyone.

Ambiguity rarely makes an agent stop. More often, it makes it guess or hedge. Classify the missing context first, then apply the matching defense, and make that defense cheap enough to carry.

Missing context comes in three kinds

Once I started looking, I saw the same pattern all over platform and data work. The code did exactly what it was told. The person telling it just didn’t know something. But “missing context” isn’t one failure. It comes in three kinds, and each needs a different defense.

1. Unknowable. A human did something nobody could have predicted — an ad-hoc workaround, a manual override, a one-off hack. No document could have warned you, because nobody knew in advance. Defense: domain invariants that fail closed, meaning they reject anything ambiguous instead of guessing. That’s the subject of Part 3.

2. Unshared. Someone knew it, but it wasn’t written anywhere the implementor would reach. Secrets once landed somewhere our deployments didn’t look. The layout the deployments expect wasn’t written down anywhere the person creating the secrets would see it. I knew about a networking boundary between two of our environments, but it wasn’t written down, so a stack in one ended up pointing at the other and the boundary blocked it. Defense: ship the context with the code.

3. Undecided. No standard exists. Sometimes not even you know the answer. That was the SHA-versus-tag case, and I wasn’t sure either. The answer — tags only, to keep the pipeline simple — came out of a troubleshooting session with a teammate, not from anyone’s prior knowledge. Monorepo layout is the same kind of problem: where nothing official exists, every team and every senior engineer invents something that works for them. Defense: someone decides on purpose, and the written decision is the artifact.

Hedging passes review. Hallucination doesn’t.

Three kinds of missing context and their matching defenses.
Unknowable gaps call for fail-closed invariants; unshared context should travel with the code and load just in time; undecided standards need an explicit decision.

Hallucination gets all the attention, and it’s the least dangerous failure here, because it’s loud. A made-up API usually fails the build.

The other two ways an agent fills a gap are quiet:

  • Convention-defaulting. With no local context, the agent falls back on whatever is most common in its training data. Think microservice patterns applied to a monorepo. It looks normal because it is normal — just not for your environment.
  • Hedging under conflict. With two valid-looking requirements and no rule to choose, the agent satisfies both. SHA and tag. The result looks thorough.

Both pass review for the same reason: they look like reasonable code. And each maps back to a kind: convention-defaulting is usually Unshared context showing up in a diff, and hedging is usually Undecided context.

The research backs the “doesn’t stop” part. A Microsoft Research and Salesforce study found that models given an underspecified task over several turns tend to make assumptions early and jump to a final answer. They lose an average of 39% in performance compared with getting the fully specified task in one shot. Drew Breunig, in his taxonomy of how long contexts fail, discusses the same study under context clash, where parts of the context disagree with each other.

Coding agents show the same habit. Ambig-SWE stripped details out of SWE-bench issues (real GitHub issues used as a coding benchmark) and found that “without explicit prompting, models almost never interact, even for severely underspecified inputs.” When the agents did ask, their results improved by up to 74%.

The “hedge” part has thinner support. AmbigDocs gave models documents about different entities that share a name, and found they often “incorrectly merge information belonging to different entities.” OpenAI’s GPT-5 prompting guide warns that contradictory instructions make GPT-5 spend reasoning “searching for a way to reconcile the contradictions rather than picking one instruction at random.” Not every study sees models split the difference: in ClashEval, GPT-4o adopted wrong retrieved evidence over its own correct answer about 60% of the time. What I watched mine do was hedge: it used both.

The obvious defense overspends

The naive fix for Unshared context is “give the agent everything.” Load every runbook, every convention doc, every tool, every decision log into every session.

That goes broke in the opposite direction. Breunig’s taxonomy — poisoning, distraction, confusion, clash — is mostly about context you overspend. Chroma’s context rot research tested 18 models and found performance gets less reliable as input grows, and distractors (passages that look relevant but don’t answer the question) make it worse. Then there’s Part 1: every token you keep in the window gets re-read on every turn.

So the defense for Unshared context has a constraint: it has to be cheap to carry. Keep a small pointer resident, meaning always in the context window, and load the real context just in time, when the task actually reaches for it. Every just-in-time setup I use works that way: one small piece stays permanently resident and tells the model where everything else lives.

Tool definitions are the overspend you don’t see

The cleanest example of just-in-time context, the Unshared defense done right, is one most people never look at: tool definitions.

Every MCP server you connect brings tool definitions: a name, a description, and a full JSON schema for each tool’s inputs. Without tool search, which loads definitions on demand (more below), all of them go into the context before you’ve typed a word. That’s what you get from raw API calls that don’t set defer_loading, or from Claude Code with ENABLE_TOOL_SEARCH=false. Anthropic’s advanced tool use post puts its example setup, 58 tools across five servers, at roughly 55K tokens of definitions up front, and says they’ve seen setups internally reach 134K. That’s budget spent before any work starts.

It costs attention too. The tool search docs say Claude’s ability to pick the right tool degrades past 30–50 available tools. Breunig cites a quantized Llama 3.1 8b that failed a query with 46 tools and passed with 19.

The fix is deferred loading. You still send every tool definition with the request, but you mark most of them to stay out of the context window until they’re needed:

{
  "tools": [
    { "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" },
    {
      "name": "get_weather",
      "description": "Get the weather at a specific location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      },
      "defer_loading": true
    }
  ]
}

At first, only the search tool and the non-deferred tools are in context. When Claude needs something else, it searches, and the API expands the matching tools into full definitions on the spot. In a larger setup from the same post, total context went from about 77K tokens up front to about 8.7K, including the handful of tools found on demand. Anthropic calls that an 85% reduction.

It also raised accuracy on Anthropic’s MCP evaluations: Opus 4 went from 49% to 74%, and Opus 4.5 from 79.5% to 88.1%. Less context, better answers.

Here’s what that looks like in my own setup. These numbers are from my harness, not a benchmark: your count will move with every MCP server, plugin, and connector you add, and with the Claude Code version.

In an interactive terminal session I have three MCP servers connected, with 45 tools between them. With tool search on, the default, /context reports about 35K tokens before my first prompt. With ENABLE_TOOL_SEARCH=false, the same session starts at about 85K, well over double. The MCP tools account for 20.7K of the difference. Most of the rest is Claude Code’s own built-in tools. In my sessions, it defers those too. With tool search off, more than half of what a fresh session loads is tool schemas that tool search would hold back until they’re needed.

You can see a deferred tool from the user side, too: it shows up as a bare name, with no parameters, and can’t be called until the model searches for it. Deferred tools are a token-budget optimization, not a permissions gate. The harness decides what stays resident and what gets fetched on demand.

Two details tie this back to the budget:

  • Deferral doesn’t break the cache. The API leaves deferred tools out of the system-prompt prefix and adds discovered ones inline in the conversation, so the cached prefix from Part 1 stays intact.
  • Keep your most-used tools resident. The docs recommend leaving your 3–5 most frequent tools non-deferred, so the common path doesn’t pay for a search.

The one tool that can never be deferred

This is the detail that made it click for me.

The tool search tool must never be deferred itself. Something that’s always loaded has to resolve the deferred schemas, and in the standard setup that’s the search tool. If it were deferred too, nothing could load its schema, nothing could ever leave the deferred state, and the system would deadlock.

The docs say never to defer it. The API enforces a looser rule, that at least one tool must stay non-deferred, and rejects a request that defers every tool with an HTTP 400 error:

At least one tool must have defer_loading=false. All tools cannot be deferred.

So every tool sits in one of three states: resident (full schema in context), deferred by name (in Claude Code, the model sees the name but can’t call it yet), and resolved (searched for, expanded, callable). The search tool is the one tool that has to stay in the first state.

Keep the resident layer small and pointing outward

Tool schemas are a small, clean case of the Unshared problem: the knowledge exists, the model needs it to act, and loading all of it up front costs too much. The same shape works beyond tools. Skill descriptions stay in context while skill bodies load on invocation. A short CLAUDE.md points to runbooks instead of inlining them.

That’s how I now think about the defense for Unshared context. I recently shipped portable, project-local AI guidance into a few repos on a platform team I work on, so the context travels with the code instead of living in someone’s head. The rule going forward: keep the resident layer small, and have it point to the rest instead of containing it.

In one of those repos, the always-loaded layer is a short AGENTS.md. It holds the hard constraints and a list of pointers outward, each one naming where the deeper reference docs for an area live. The heavier rules live in path-scoped files under .claude/rules/, which load only when the agent touches matching paths. The largest of them, more than twice the length of AGENTS.md, never enters a session that doesn’t touch the code it covers.

Undecided needs someone to decide

None of this helps with the third kind. You can’t lazy-load an answer nobody has written down, and you can’t write down an answer nobody has made.

The defense for Undecided context is a person making a decision on purpose. Left unresolved, a conflict reads to an agent as “satisfy both.” The tags-only decision only became real knowledge once it was made and written where the next implementor would run into it. Otherwise the next person — or the next agent — rediscovers the same hedge.

When I went looking for where the tags-only decision lives, I didn’t find an architecture decision record, a runbook, or a line in the guidance file. I found it in a deployment schema:

"ref": { "type": "string", "pattern": "^<service>-v[0-9]+\\.[0-9]+\\.[0-9]+$" }

The schema accepts a tag and nothing else, and nobody types that tag by hand. When a release merges, release automation in CI writes the new tag into the ref. The decision isn’t something the next implementor has to read. It’s a shape their change has to fit.

Make the ambiguity impossible to express

The strongest fixes for Unshared and Undecided context alike didn’t document anything. They removed the choice:

  • One fixed place for each secret, so a secret can’t land somewhere a deployment won’t find it.
  • Tag-pinned deployment values, so there’s exactly one identifier for “what’s live.”
  • Environment-scoped endpoints, so a stack in one environment can’t reach another by accident.

Each one turns a judgment call into a configuration with only one valid shape. An agent can’t hedge between options that don’t exist.

So that’s the order I reach for them in. First, remove the choice. Where I can’t, write the decision where the next implementor will hit it. For everything else, ship small just-in-time context.

The question I ask in review now

This changed what I ask when I review agent output. I used to ask: does this code work? The SHA-and-tag change worked. The secrets change worked, until a deployment tried to read them.

Now I ask: what does the implementor not know about our environment? That question catches the Unshared and Undecided kinds. The old question catches neither. It slots right into the review gates I already run — one more thing a reviewer persona checks, instead of trusting the diff to look normal.

The thread so far

Part 1 said every token in the window costs money on every turn. Part 2 adds what goes wrong when the window holds the wrong context, and what to do about it:

Missing context makes an agent hedge; too much makes it confused. Keep a small index resident, load the rest just in time, and make the important decisions before the agent arrives.

That covers Unshared and Undecided. It doesn’t cover Unknowable. You can’t ship context nobody has, and you can’t write a decision for a hack nobody predicted. Part 3 is about that case, and why the answer there is fewer documents and more rules.

Further reading