Four tools, one agent, and a mistake that wouldn’t quit. Every time the workflow called for reading an existing record, the model reached for the tool built to create a brand new one instead. The Redditor behind this story, u/Karen-Allenv0l1b, watched it happen run after run and assumed the model itself was confused.
So the fix had to be the prompt, right? Days went into rewriting the system prompt. Explicit rules went in. Examples went in. Warnings went in. Eventually a full decision table spelled out exactly which tool to grab and when.
Nothing changed. The agent kept reaching for the wrong tool like the new instructions weren’t even there.
Quick start: skip the prompt rewrite. Go straight to the actual payload sent to the model, tool schemas included, before touching a single paragraph of the system prompt. That’s the whole trick this guide walks through.
🧭 Why It Matters
Here’s the twist that makes this worth reading. The prompt was never broken. The tool descriptions were.
They’d been copied straight from internal API docs. Technically accurate, sure, but written to describe what each function does, not when an agent should reach for it. One tool even had a parameter called “type” that accepted several values with zero explanation of what separated one from another.
I love this example because it exposes a blind spot a lot of us share. We treat the system prompt as the entire conversation with the model and forget that tool schemas ride along in that same payload. If a description reads like documentation instead of a decision guide, the model has to guess every time it picks a tool.
This matters way beyond one Reddit thread. Any agent with more than a couple of similar tools runs this exact risk. Two functions can sound almost identical. Describe them in API language instead of plain use cases, and the model flies blind no matter how good your prompt is.
🛠️ The Fix, Step by Step
Here’s how the original poster tracked the problem down and solved it, in the order it actually happened.
- Notice the pattern. The same tool-selection mistake kept showing up on a fairly simple workflow, not a random one-off.
- Try the obvious fix first. Add rules, examples, warnings, and a decision table to the system prompt.
- Watch it fail anyway. The mistake persisted no matter how detailed the prompt instructions got.
- Log the real payload. Capture the exact tool definitions being sent to the model, not just the prompt text.
- Read the descriptions like a stranger. Ask whether each one explains when to use the tool, not just what it does.
- Check every generic parameter. A field called “type” or “mode” needs its values spelled out with clear semantic differences.
- Rewrite the schema, not the prompt. Fix the tool descriptions and tighten the parameter constraints directly.
- Leave the system prompt alone. This Redditor barely touched it after the schema rewrite.
Tool selection accuracy improved right away. No new paragraphs, no bigger decision table, just clearer tools doing the explaining for the model.
🔑 Tips & Tricks
A few extra notes worth keeping in your back pocket:
- Make payload logging step one on any agent debugging checklist, not a last resort. One commenter, u/Lootteyng, pointed out that most tool-selection issues trace straight back to a schema nobody read carefully.
- Check your MCP tool descriptions too. Another commenter, u/Dorna_Brown, ran into the identical problem with MCP tools. The descriptions read like API documentation, with no way for the model to tell two similar functions apart.
- Treat every parameter name as a question. If a value like “type” would need a comment to explain it to a human teammate, it needs one for the model too.
- Write descriptions like a decision, not a manual. “Use this to fetch an existing record” beats “Retrieves a record by ID” every time.
- Save the prompt rewrite for later. Once the schema is clean, plenty of tool-selection bugs disappear on their own.
- Name tools for the decision, not the endpoint. If two tools sound like siblings, give them names that hint at when each one applies.
⚓ Try It On Your Own Agent
If an agent keeps making the same tool-selection mistake, don’t reach for the system prompt first. Open the actual definitions being sent to the model and read them like they’re brand new to you.
Grab your worst-behaved tool schema this week and give it a real rewrite. Head over to the original thread on r/PromptEngineering for the full back and forth, including a few more sharp comments worth reading!
Frequently Asked Questions
Q: My agent keeps picking the wrong tool. Where do I even start debugging?
Log the full payload (including tool schemas) being sent to the model first thing. Most tool selection issues come from ambiguous or API documentation-style descriptions, not from missing system prompt rules. Check whether your tool descriptions actually explain when to use each tool, not just what it does.
Q: How should I write tool descriptions so the model picks the right one?
Write for intent and usage conditions, not API docs. Explain what problem each tool solves and when the model should reach for it. For parameters with multiple values (like a vague type field), spell out the semantic differences instead of just listing options. People in the comments found this beats adding more rules to your system prompt by a mile.
Q: Should I just keep rewriting my system prompt when tool selection goes wrong?
Not first. Check the tool definitions before you add another paragraph to your prompt. Tool schemas are basically part of your prompt whether you treat them that way or not. Fixing vague or API-doc-focused descriptions usually works better than piling on more examples or warnings.
Q: How specific should I get when describing parameters?
Be as specific as you can. If a parameter accepts several values, explain what each one does and when to use it. That clarity helps the model actually understand why it’s reaching for a tool, which is what stops the wrong choice from happening in the first place.
I spent days fixing the prompt when the real problem was the tool schema
by u/Karen-Allenv0l1b in PromptEngineering