My Project's Own Instructions Told My Agent to Use Tools That Don't Exist

I keep a CLAUDE.md at the root of one of my repos. It's the file a coding agent reads before it does anything else in that project — conventions, gotchas, "do this, never do that." Mine has a section titled, in bold, "MANDATORY routing rules." It tells the agent that a set of MCP tools exist for routing large command output through a sandbox instead of dumping it into context, that curl and wget are intercepted and blocked, that WebFetch is denied outright and redirected to a fetch-and-index tool instead.

None of that is true in every environment that repo gets checked out into. In the one I was actually running in, those tools were never wired up. The MCP server that would have provided them wasn't connected. curl wasn't blocked. WebFetch worked fine.

If I'd let the agent take CLAUDE.md at face value, here's what would have happened: it hits a step that needs to fetch a URL, sees the "WebFetch is BLOCKED, use ctx_fetch_and_index instead" line, calls a tool that isn't in its tool list, gets a hard failure, and either retries the same non-existent tool a few times or gives up on the step entirely. Either way, time and context burned solving a problem that didn't exist, to avoid a problem the file swore did.

This isn't a malicious prompt injection. Nobody snuck that text in to sabotage anything. It's just stale documentation. Someone set up a context-routing MCP server for one environment, wrote the rules into the repo's instructions so every future session would use it correctly, and then the tooling moved, or a different environment picked up the same repo without the server attached. The instructions didn't get updated because nothing forced them to — CLAUDE.md isn't code, nothing runs it, nothing fails CI when it goes stale.

The part that actually worries me

The file used the word "MANDATORY." Not "prefer" or "if available" — mandatory, in a section that explicitly says these rules are "NOT optional" and exist to "protect your context window." That's exactly the framing that gets an agent to comply without checking. It's phrased like a safety rule, and safety-rule phrasing is designed to short-circuit judgment. The stronger the imperative language, the less likely an agent — or a person — is to pause and ask "wait, is this still accurate?"

I don't think that's a coincidence specific to my repo, either. As more projects grow their own CLAUDE.md / AGENTS.md / .cursorrules, the instructions inside them accumulate the same failure mode regular code has always had: they describe a system that used to be true. The difference is code has tests that fail loudly when reality diverges from the description. Instruction files have nothing. They just sit there being wrong, confidently, until an agent runs into the gap.

What I actually do about it now

I stopped treating "MANDATORY" language in a project's own instructions as something to execute unconditionally. Before an agent commits to a documented tool-routing rule, it's cheap to check whether the tool it's being routed to actually exists in this session:

# pseudocode for the check I want an agent to run
# before trusting a "you MUST use tool X" rule in project docs
def verify_routing_claim(claimed_tool_name, available_tools):
    if claimed_tool_name not in available_tools:
        return "STALE: doc claims this tool exists, session shows otherwise"
    return "OK: proceed as documented"

In practice that's a ToolSearch (or your harness's equivalent — a tool-listing call) against the exact tool names the doc references, done once at the start of a session rather than trusted blindly step by step. If the search comes back empty, that's a signal, not a dead end: fall back to the direct approach (plain curl, plain WebFetch, whatever the doc told you to avoid) and — this is the part I actually care about — log the drift somewhere a human will see it. In my repos that's a line in docs/project_notes/bugs.md: "CLAUDE.md references ctx_fetch_and_index, not present in this environment as of 2026-07." That turns a silent failure into a fixable one. The next person, or the next session, gets a doc that's honest again.

The broader habit is treating instruction files the way I'd treat a comment in code claiming a function does something — worth reading, worth following most of the time, but not worth trusting over what's actually observable right now. "MANDATORY" is a claim about the world, and claims about the world can be wrong. The fix isn't ignoring project instructions — most of the time they're exactly right and save real work. It's building in the one cheap check that tells you when they aren't: does the thing the doc says exists actually exist here, right now, in this session. If yes, comply. If no, don't retry the ghost tool three times and burn the budget finding that out the hard way — fall back, and write down what you found so the doc gets fixed instead of staying wrong for the next agent that reads it.