[Question]: ReActAgent Not Consistently Using Tools & Only Calling One Tool

[MuhammadMaazK]

Question Validation

• I have searched both the documentation and discord for an answer.

Question

Hi,
I am using a workflow-based ReActAgent with multiple RAG tools (more than 5), for example: info, data, market, brand, history, specs.
Each tool is implemented using a CitationQueryEngine because I need citations in the final response.

However, I’m running into several issues with how the ReActAgent behaves:

1. ReActAgent Often Responds Without Using Any Tool

In many cases, the agent ignores the tools completely and generates a direct LLM response — which leads to poor-quality answers.

I want the agent to always use tools, especially the first tool (info), because that tool contains the most critical context.
Even after updating the prompt to instruct the agent to use tools, the majority of responses still come directly from the LLM.

Here is the snippet:

agent = ReActAgent(
    llm=Settings.llm,
    tools=tools_list,
    max_iterations=5,
)

# Update prompts
react_system_prompt = PromptTemplate(system_prompt)
agent.update_prompts({"react_header": react_system_prompt})

# Create context
ctx = Context(agent)

# Run agent
handler = agent.run(user_message, ctx=ctx, memory=chat_memory)

Question:
How can I force (or strongly encourage) the ReActAgent to always call at least one tool, ideally starting with info?

2. ReActAgent Uses Only One Tool Even When Multiple Tools Are Needed

In cases where multiple tools need to be combined for a high–quality answer, the agent usually stops after using just one tool.
It rarely chains multiple tool calls (which ReAct theoretically supports).

Question:
How can I improve multi-tool reasoning so the agent uses more than one tool when required?

3. Are There Better Approaches or Recommended Prompt Templates?

Since ReActAgent behavior is inconsistent, I’m wondering:

Is there a better agent architecture for chaining multiple RAG tools?

Are there recommended prompt templates specifically for ReActAgent to enforce tool usage?

Is there any way to enable strict tool-calling mode?

Environment

LlamaIndex version: 0.12.52

I do not have LlamaIndex source files locally (installed via pip)

[dosubot]

There’s no strict tool-calling mode in ReActAgent—tool usage is always at the LLM’s discretion, guided by the prompt and tool descriptions. The agent will sometimes skip tools or only call one tool if the LLM reasons it can answer directly, even if you nudge it in the prompt. Here’s what you can do to strongly encourage tool usage and improve multi-tool reasoning:

• Write very clear tool descriptions, e.g., “Use this tool when you need any background context. The input is a question, and the output is a citation-backed answer.”
• In your system prompt, explicitly instruct the agent to always use the “info” tool first, and to chain tools as needed before answering.
• Lower the LLM temperature (e.g., to 0.0) to reduce creative direct answers and make the agent more likely to follow instructions.
• Use verbose=True to monitor tool usage and debug agent reasoning.
• Increase max_iterations to allow more tool calls in sequence if needed.
• Use a stronger LLM (like gpt-4o) for better adherence to instructions.
• Setting return_direct=True on tools can sometimes help the agent use them more consistently.
• Make sure your custom prompt matches the template variables of the default prompt, or it may be ignored.
• There’s no built-in way to force the agent to always start with a specific tool; this can only be nudged via prompt engineering or by writing a custom agent/workflow if you need strict enforcement.

If you need guaranteed multi-tool chaining or strict tool invocation, you’d need to subclass the agent and orchestrate tool calls yourself in take_step, or combine multiple tool actions into a single tool as a workaround. See this discussion and the code reference for more details.

The default ReActAgent prompt already encourages chaining:

“You are responsible for using the tools in any sequence you deem appropriate to complete the task at hand. This may require breaking the task into subtasks and using different tools to complete each subtask.”
But the LLM can still choose to answer directly if it thinks it has enough information. Prompt engineering is your main lever here—there’s no strict enforcement in the agent code itself.
More details and prompt examples are in this thread and the system prompt template.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}