I ran into a simple problem that can be surprisingly difficult to diagnose:
The AI Agent understands the user’s request, but sometimes it doesn’t call the tool I expected it to use.
Instead of changing the prompt over and over, I found it much easier to reduce the workflow to a minimal tool-calling test.
Here’s the debugging pattern I use.
The problem
When an AI Agent doesn’t call a tool, there are several possible causes:
- The model doesn’t think the tool is necessary.
- The tool description isn’t clear enough.
- The tool input schema doesn’t match what the model is generating.
- The system prompt doesn’t clearly define when the tool must be used.
- Memory or additional context is affecting the decision.
- The tool itself is failing.
The important part is that these problems can look very similar from the outside.
So instead of debugging everything at once, I use a minimal test workflow first.
The minimal test
I start with the smallest possible workflow:
Chat Trigger → AI Agent → Chat Model
Then I connect just one tool to the AI Agent.
For this example, I’m using the Calculator tool.
The idea is simple: if the Agent is supposed to perform a calculation, I want to be able to clearly see whether it actually called the Calculator tool.
Give the Agent an explicit instruction
For the first test, I use a system message like this:
You are a tool-testing assistant.
Whenever the user asks you to perform a calculation, you MUST use the Calculator tool.
Do not calculate the result yourself.
For calculation requests, never answer from your own mathematical knowledge.
The Calculator tool is mandatory.
If you have not called the Calculator tool, you are not allowed to provide the final numerical answer.
Always use the result returned by the Calculator tool in your final answer.
The important part here isn’t the exact wording.
The important thing is that the expected tool behaviour is explicit.
Run a simple test
I then test the workflow with something very obvious:
Calculate 8472 × 39. You must use the Calculator tool.
The result should be:
330408
But the number itself isn’t the important part.
What I’m checking is the execution.
I want to see something like:
User request → AI Agent → Calculator tool → Calculator result → Final answer
If the Calculator tool was actually called, I know the basic tool-calling setup is working.
Check the execution
This is the step I find most useful.
Instead of looking only at the final answer, open the execution and inspect what the AI Agent actually did.
I’m looking for:
- Did the Agent decide to use the tool?
- Which tool did it select?
- What input did it send?
- Did the tool return a result?
- Did the Agent use that result in its final response?
This makes a big difference.
An Agent returning the correct answer does not necessarily mean the tool was called.
If I specifically need the tool to be used, I want to verify the actual tool call.
Don’t debug everything at once
If the Agent doesn’t call the tool, I don’t immediately start changing five different things.
I isolate the problem.
My checklist is:
- Remove Memory temporarily.
- Remove all other tools.
- Keep only one model.
- Keep only one tool.
- Give the Agent an explicit instruction to use that tool.
- Run a simple test request.
- Inspect the execution.
- Confirm whether the tool was actually called.
This turns a complicated AI workflow into a much easier debugging problem.
Test without Memory
If the workflow works without Memory but stops calling the tool after Memory is added, I know the problem isn’t simply the basic tool configuration.
That gives me a much smaller area to investigate.
This is especially useful with more complex Agents where conversation history and additional context can influence the model’s decision.
I don’t assume Memory is the problem.
I use this as an isolation test.
Add the other tools back one at a time
Once the minimal workflow works, I add the other components back one at a time.
For example:
Calculator
↓
Calculator + Search
↓
Calculator + Search + HTTP Request
↓
Full workflow
After each change, I run the same test again.
If the Agent stops calling the expected tool after adding another component, I now have a much smaller area to investigate instead of debugging the entire workflow blindly.
Check the tool description
Another thing I check is the tool description.
A tool description should make it clear:
- What the tool does.
- When the Agent should use it.
- What information it needs.
- What it returns.
- When it should NOT be used.
For example:
Use this tool whenever the user asks for a mathematical calculation. Always use this tool instead of calculating the result yourself. The tool returns the calculated result.
This becomes particularly important when an Agent has several tools that could potentially be used for similar requests.
What if the tool is actually failing?
This is a different problem.
If the Agent calls the tool but the tool itself fails, I don’t treat that as the same problem as:
“The Agent didn’t call the tool.”
I check the tool execution separately.
For example, with an HTTP Request tool, I want to be able to inspect the response status and error information rather than simply seeing a generic failure.
That lets me distinguish between:
Agent → Tool selection
and:
Tool → External service
Those are two completely different problems and should be debugged differently.
My quick debugging checklist
| Symptom | What I check first |
|---|---|
| Agent doesn’t call the tool | Tool description + System Message |
| Agent calls the wrong tool | Tool descriptions + overlapping tools |
| Tool input is rejected | Input schema |
| Tool works alone but not with Agent | Agent/tool configuration |
| Problem appears after adding Memory | Test without Memory |
| Tool is called but fails | Tool execution/logs |
| HTTP tool returns an error | Response status + error handling |
| Everything becomes difficult to diagnose | Reduce to one model + one tool |
The main takeaway
When an AI Agent doesn’t call a tool, I try not to “fix the prompt” blindly.
I reduce the workflow to the smallest possible version:
one model + one Agent + one tool
Then I verify the actual execution.
Once the tool call works reliably, I add Memory, additional tools and the rest of the workflow back one component at a time.
This makes it much easier to identify whether the problem is:
- tool selection,
- tool description,
- input schema,
- memory/context,
- or the tool itself.
It also gives me a reproducible test instead of relying on trial and error.
If anyone has a different debugging pattern for AI Agent tool-calling issues, I’d be interested to hear how you isolate the problem, especially in larger workflows with Memory and multiple tools.