- In short
- System prompt tool conflicts occur when keyword-sensitive instructions in the system prompt create unintended associations that pull Claude toward a particular tool, overriding otherwise well-written tool descriptions. Resolving them means reviewing the system prompt for conflicting keywords whenever you change tool descriptions.
What system prompt tool conflicts are
You can write a flawless tool description and still watch the agent ignore it. The reason is that descriptions are not read in isolation. When Claude selects a tool, it weighs the user request against the tool descriptions and the system prompt, all in one context. If the system prompt contains an instruction worded in a way that pulls toward a particular tool, that pull can override the description that should have won. These are system prompt tool conflicts: an unintended association, planted by the prompt, that beats the descriptions you carefully tuned.
This is an analyse-level skill because the cause is invisible if you only look at the toolset. The descriptions can be perfect, the schemas correct, and the agent still misbehaves, because the interference lives one layer up. Diagnosing it means widening your gaze from the tools to the whole prompt context and finding the keyword that is bending the model's hand.
- System prompt tool conflict
- An unintended tool association created by keyword-sensitive instructions in the system prompt, which biases Claude's tool selection and can override well-written tool descriptions. The fix is to detect and reword the conflicting instruction.
Why the prompt can beat the description
Anthropic's documentation notes that when you pass tools, the API builds a single tool-use system prompt that combines your tool definitions, your tool configuration, and your own system prompt. Everything the model uses to decide is fused into one block of context. That fusion is what makes conflicts possible: your instruction and your descriptions are now neighbours competing for the model's attention.
Anthropic's guidance on building effective agents reinforces that tool selection is steerable from the system prompt, a light instruction can increase or decrease tool use, and a strong one pushes harder. That steerability is usually a feature. It becomes a bug when the steering is accidental: a sentence written for some other purpose happens to mention a tool's name, its domain, or a near-synonym, and the model reads it as a standing preference. The description says "use lookup_order for shipment questions," but a line in the prompt that reads "always start by confirming the customer's account" quietly biases the model toward get_customer on the very requests where lookup_order should win.
Detecting system prompt tool conflicts
The detection rule is procedural and easy to remember: whenever you change a tool description, re-read the system prompt for keywords that conflict with it. Most conflicts are introduced by exactly this sequence. You sharpen a description, declare victory, and never notice that a prompt line written weeks ago still nudges the model the old way. The two artefacts drifted out of sync.
When you read the prompt, look for three things. Direct mentions of a tool name or a near-synonym of one. Standing instructions about order of operations ("always start by...", "first check...") that privilege one tool's domain. And domain keywords that overlap a tool's described territory ("account," "customer," "profile" all leaning toward get_customer). Any of these can create an association the model treats as a rule. Once found, the fix is usually a reword: make the instruction conditional, remove the loaded keyword, or state explicitly that tool selection follows the descriptions.
Where this fits in the diagnostic ladder
System prompt tool conflicts are what you check when the cheaper fixes have not worked. The diagnostic order runs: confirm descriptions drive selection, sharpen overlapping descriptions (diagnosing tool misrouting), split overloaded tools (tool splitting for specificity), and, when good descriptions still lose, inspect the system prompt for interference. It is a hard prerequisite of this concept that you have already diagnosed plain misrouting, because a prompt conflict looks identical to description overlap from the outside. The difference is that the descriptions are already correct, so the cause must lie elsewhere.
Worked example
After rewriting get_customer and lookup_order with crisp boundaries, an agent still routes 'where is my refund?' to get_customer about a third of the time. The descriptions are demonstrably unambiguous on their own.
Because the descriptions are now clean, plain overlap is ruled out, re-reading them, a person can always tell which tool a refund question belongs to. That eliminates the cheap cause and points one layer up. Open the system prompt and read it as the model does, fused with the tool context.
There it is: a line near the top reads, "For every interaction, begin by confirming the customer's identity and account before taking action." The word "customer" and the standing "begin by" instruction create an association: whenever a request arrives, the model feels a pull to reach for the customer tool first. On refund questions that pull sometimes outvotes the correct lookup_order description. The descriptions did not fail; the prompt overrode them.
Resolve the conflict by rewording, not by touching the tools. Change the instruction to "When the request requires account or contact details, confirm the customer's identity using get_customer; otherwise route by the tool descriptions." The order-of-operations bias is now conditional and explicitly defers to the descriptions for everything else. Re-run the refund requests and the routing settles onto lookup_order. The lesson: when good descriptions still misroute, the conflict is often in the prompt, and the fix is to reword the prompt, after which you again review for any new conflict you may have introduced.
Common misreadings to avoid
Misconception
If my tool descriptions are correct, the system prompt cannot affect tool selection.
What's actually true
Misconception
When good descriptions still misroute, the next step is to add a routing classifier.
What's actually true
Where conflicting keywords hide
Once you accept that the prompt can override descriptions, the practical question becomes where in the prompt to look. Three locations account for most conflicts. The first is standing order-of-operations instructions near the top of the prompt, sentences like "always begin by", "first confirm", or "before anything else", which the model reads as a default move it should make regardless of the specific request. If the privileged action maps to one tool's territory, that tool gets an unearned advantage.
The second location is role or persona text that leans on a domain word. A support agent whose prompt repeatedly emphasises the customer, the account, or the profile will feel a gentle, persistent pull toward a customer-oriented tool, because those words overlap that tool's described domain. The third is example dialogue or canned phrasing embedded in the prompt, where a sample interaction happens to demonstrate one tool and the model generalises from it. None of these are bugs in the descriptions; all of them are associations planted upstream. Knowing the three usual hiding places turns prompt review from a vague re-read into a targeted search.
Keeping descriptions and prompts in sync
The deeper lesson is that tool descriptions and the system prompt are two halves of one selection surface, and they drift apart whenever one is edited without the other. The classic failure sequence is exactly this drift: a team diagnoses misrouting, sharpens the descriptions, ships the fix, and never revisits a prompt instruction written weeks earlier that still encodes the old bias. The descriptions now say one thing and the prompt quietly says another, and the model splits the difference.
The remedy is a discipline, not a tool: treat any change to a description as a trigger to re-read the prompt, and any change to the prompt as a trigger to re-check tool behaviour. Because the two artefacts are fused into a single context at selection time, they must be maintained as a single artefact in your head. Architects who hold that mental model stop being surprised when a fixed toolset keeps misbehaving, because they always ask the second question, what does the prompt say about these tools, before reaching for anything heavier. That habit is the practical payoff of understanding system prompt tool conflicts.
The API system prompt is not the app system prompt
One more source of confusion is worth flagging for architects who study published system prompts. The system prompt Anthropic releases for claude.ai and the Claude mobile apps is a product-surface prompt, and it does not apply to the Claude API. When you build on the API, the only system prompt that governs your agent's tool selection is the one you send, fused with your tool definitions into a single tool-use context.
Assumptions copied from the public claude.ai prompt, whether its tone, its standing instructions, or its tool habits, have no bearing on your API agent and can quietly mislead a debugging session. The practical rule is to reason only about the prompt and tools in your own request payload. Anthropic maintains separate release notes for the app system prompts precisely because they evolve independently of the API, so treat the two as different artefacts and never debug an API tool conflict against an app prompt you happened to read online.
How it shows up on the exam
The exam tests this with a two-stage scenario: the team fixes the obvious description overlap, yet the agent keeps favouring one tool. You are asked for the cause or the next action. The credited answer points at the system prompt, a keyword or instruction is creating an unintended association, and the fix is to review and reword the prompt. Distractors will offer to consolidate the tools, add examples, or build a classifier, all of which ignore that the descriptions are already fine. The exam is checking that you know tool selection is a property of the whole prompt context, not the tool definitions alone, and that updating descriptions without re-checking the prompt is a known trap.
To lock the pattern in, rehearse the giveaway shape the exam uses for this concept. You will see two beats: first, a description fix that should have worked, and second, a residual bias that it did not. The moment those two facts sit side by side, your hand should move to the system prompt rather than back to the descriptions. A description that is already unambiguous cannot be the cause of a bias that survives it, so the cause must live in the other half of the selection surface. Then look for the specific instruction the scenario plants, usually an order-of-operations line or a domain keyword, and choose the reword that makes it conditional and defers to the descriptions.
The inverse mistake is just as testable. If a scenario shows misrouting and the descriptions have not yet been examined, jumping straight to the system prompt is premature, because plain overlap is the cheaper and more common cause. The exam rewards the correct sequence: confirm the descriptions are clean first, and only then attribute a surviving bias to the prompt. Holding that order in mind keeps you from over-applying this concept to problems that a simple boundary edit would have solved.
A team rewrites two overlapping tool descriptions until they are clearly distinct, but the agent still over-selects get_customer. The system prompt opens with 'Always begin by confirming the customer account.' What is the most likely cause and fix?
People also ask
Can a system prompt override a tool description?
Why does Claude ignore my tool descriptions?
How do keywords in a system prompt bias tool selection?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
System prompts
Why watch: Keyword-heavy system prompts can unintentionally bias tool associations, the conflict this KP warns about.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.