How do I troubleshoot an agent that keeps missing tool calls?

If an agent is “missing” tool calls, the issue is usually one of these: the model never chose the tool, the tool call was generated but not executed, or the result was executed but not fed back correctly.

Here’s a practical troubleshooting checklist:

1) Verify the tool is actually available to the agent

• Confirm the tool is included in the agent’s tool list / schema.
• Check the tool name exactly matches what the model is allowed to call.
• Make sure the tool description clearly says when to use it.

2) Inspect the raw model output

Look at the assistant message before your orchestration layer processes it:

• Did the model produce a tool call at all?
• Was it valid JSON / valid function-call structure?
• Did it call a different tool than expected?

If you only inspect the final natural-language answer, you can miss tool calls that were malformed or dropped by middleware.

3) Check your parsing and execution layer

Common bugs:

• The model emits a tool call, but your code doesn’t detect it.
• The tool call is detected, but arguments fail schema validation.
• The tool call executes, but the result never gets appended back into the conversation.
• The tool call is there, but your code only allows one tool call and ignores the rest.

Log:

• raw assistant output
• parsed tool call(s)
• validation errors
• execution status
• tool result returned to model

4) Make the tool use more obvious in the prompt

If the agent should always use a tool for certain tasks, say so explicitly:

• “For current weather, you must call get_weather.”
• “Do not answer from memory if the tool can provide the answer.”
• “If user asks about X, always use tool Y first.”

If the model is being vague about when to use tools, it may answer directly instead.

5) Reduce ambiguity in tool descriptions

A weak tool description often causes missed calls. Compare:

• Weak: “Gets data”
• Better: “Fetches the latest account balance for a given user ID. Use whenever the user asks for balance or recent transactions.”

The model needs clear trigger conditions.

6) Check context length and instruction conflicts

Tool calls are more likely to be missed when:

• the conversation is long and earlier instructions got lost
• system/developer instructions conflict
• the model is overloaded with too many tools

Try:

• shortening the prompt
• moving critical tool-use instructions into the system message
• reducing the number of exposed tools

7) Test whether the model can call the tool in a minimal example

Create a small reproducible test:

• one user message
• one tool
• one explicit instruction to use the tool

If it works there, the problem is likely in prompt complexity or orchestration, not the model itself.

8) Watch for streaming issues

If you stream responses:

• tool call deltas may arrive incrementally
• your client may be reading only text chunks and ignoring tool-call chunks
• partial arguments may look invalid until the stream completes

Make sure you assemble the full stream before deciding the model didn’t call a tool.

9) Check model settings

Depending on the platform:

• tool choice may be “auto,” “required,” or “none”
• temperature can increase variability and reduce consistent tool use
• some models are better at tool calling than others

If the tool must be used, consider forcing tool choice if supported.

10) Add guardrails in your application logic

If a tool is mandatory for a request type, don’t rely only on the model:

• detect intent in your app
• route the request to the tool directly
• let the model summarize the result afterward

This is often more reliable than expecting the model to always choose correctly.

---

A quick debugging flow

1. Did the model emit a tool call?
   • No → prompt/tooling/model choice issue
   • Yes → go to 2
2. Was the tool call parsed successfully?
   • No → schema/parser issue
   • Yes → go to 3
3. Did the tool execute successfully?
   • No → tool/runtime issue
   • Yes → go to 4
4. Was the result returned to the model?
   • No → orchestration issue
   • Yes → go to 5
5. Did the model ignore the tool result?
   • Then prompt design or conversation state is likely the problem

If you want, I can also give you:

• a debug logging template for tool calls,
• a minimal reproducible test case, or
• a checklist specific to OpenAI/Responses API / function calling.