When the agent errs from a lack of context, the first urge is to give it more context. Attach the whole module, dump the full logs, add adjacent files "just in case". The logic feels ironclad: the more material, the smaller the chance that something important was left off-screen. The most common mistake in working with an agent is built on exactly this logic.
The naive model is simple: context is a warehouse, and the fuller it is, the better. Since the agent reads fast, let it read everything and pick out what it needs. This reasoning carries over to the model the human habit of over-caution: better to give too much than too little. With a person able to ignore the irrelevant it even works - but the agent is built differently.
It breaks on the fact that surplus context is not neutral. Every attached file is a signal "look here", and ten such signals blur the single one that led to the goal. A model's retrieval and attention work the more precisely the clearer the shape of the question; a stream of loosely related artifacts, on the contrary, raises the chance that the agent latches onto the similar-but-wrong. A model has a limited attention budget per turn, and it is split among everything you put in: the more pieces, the less weight each one gets, including the single piece the whole thing was started for. A warehouse does not help find the needed thing - it hides it among the similar.
Hence a different metaphor: hand over a map, not a warehouse. The map is one confirmed entry point, the expected and the actual behavior, and a way to reproduce. That is enough for the agent to walk on its own from the entry point to the related places: find the callers, pull up the tests, restore the chain. You give the start of the route and the destination, rather than dumping the contents of every warehouse along the road.
A separate technique inside the map is to separate facts from hypotheses, and to do it explicitly. "The test fails on line X with this message" is a fact, it can be checked. "It is probably a race condition" is a hypothesis, and it must be offered as a hypothesis, not as an established cause. The mixing is dangerous because the agent takes your guess for a given and starts fixing the presumed cause instead of the observed symptom, steering the work off course from the very start.
Why a pointed anchor is more reliable than a massive dump is clear from how code search is built. An @-mention of a specific file or symbol is a precise anchor: it says "start here" without asserting "look nowhere else". From it the agent unfolds the search itself and finds what you might not have known. The difference is visible in practice: from a single anchor "start with this handler" the agent will pull up its callers and covering tests on its own; from a folder of thirty files it will more likely describe what catches the eye rather than what bears on the matter. A mass of attachments, on the contrary, both blurs the anchor and suppresses independent retrieval - the model assumes all the needed material is already given and stops searching.
The cost of overloaded context is not only in quality. Wide context is a direct expense: more tokens on input, more material to re-read at every step, a higher chance of drifting into research the task did not require. A precise map is cheaper twice over: it both shrinks the input and reduces the number of wrong moves, each of which is also paid for.
There is a simple criterion for what to put into the task and what to remove. If you cannot explain why a specific artifact is needed for this task, it should not be there. Not "seems related" but a nameable role: this is the entry point, this is the test that fixes the contract, this is the version in which the bug reproduces. A simple way to apply the criterion is to say the role out loud: if it comes out as "well, it might come in handy", the artifact does not pass; if it is "this is the test that will fail on the bug", it passes. Anything that does not pass this question is noise, and its place is outside the context.
It is more convenient to check the sufficiency of context not by its volume but by the agent's behavior. Ask it, before changing anything, to name its evidence: which facts it relies on and which entry point it treats as the start. If it confidently reconstructs the chain from what you gave, the map was enough. If it starts guessing or asks you to "send more", what is missing is not volume but precision: one supporting point is lacking, not ten extra files.
The typical failures of the map and the warehouse differ. With the warehouse the agent drowns in the attachments and fixes the similar-but-wrong; with an empty map it guesses about the entry point and goes astray. The common sign of both is that the agent cannot name why it is looking exactly here. Give one confirmed entry point, separate facts from hypotheses, strip the surplus - and in most cases "too little context" turns out to be "context of the wrong shape".