NVIDIA-AI-Blueprints · AjayThorve · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/configs/config_cli_default.yml b/configs/config_cli_default.yml
@@ -140,7 +140,7 @@ functions:
     exclude_tools:
       - advanced_web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_frontier_models.yml b/configs/config_frontier_models.yml
@@ -156,7 +156,7 @@ functions:
       - web_search_tool
       - knowledge_search
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_mcp.yml b/configs/config_mcp.yml
@@ -115,7 +115,7 @@ functions:
     exclude_tools:
       - advanced_web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_openshell.yml b/configs/config_openshell.yml
@@ -141,7 +141,7 @@ functions:
       - advanced_web_search_tool
     verbose: true
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   # OpenShell configuration: skills + sandbox
   deep_research_skills:

diff --git a/configs/config_web_azure_ai_search.yml b/configs/config_web_azure_ai_search.yml
@@ -215,7 +215,7 @@ functions:
       - advanced_web_search_tool
     verbose: true
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_web_default_guardrails.yml b/configs/config_web_default_guardrails.yml
@@ -246,7 +246,7 @@ functions:
       - advanced_web_search_tool
     verbose: true
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_web_default_llamaindex.yml b/configs/config_web_default_llamaindex.yml
@@ -214,7 +214,7 @@ functions:
       - advanced_web_search_tool
     verbose: true
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_web_frag.yml b/configs/config_web_frag.yml
@@ -182,7 +182,7 @@ functions:
     exclude_tools:
       - advanced_web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_web_frag_mcp_auth.yml b/configs/config_web_frag_mcp_auth.yml
@@ -231,7 +231,7 @@ functions:
     exclude_tools:
       - advanced_web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/configs/config_web_opensearch.yml b/configs/config_web_opensearch.yml
@@ -189,7 +189,7 @@ functions:
     exclude_tools:
       - advanced_web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/docs/source/architecture/agents/shallow-researcher.md b/docs/source/architecture/agents/shallow-researcher.md
@@ -17,7 +17,9 @@ with configurable iteration limits.
 The shallow path is optimized for speed and cost:
 
 - A single LLM with bound tools handles the full research cycle
-- Tool calls are counted against a budget (`max_tool_iterations`)
+- Tool calls are counted against a total budget (`max_tool_iterations`): one
+  initial search and, when needed, one rewritten-query retry. Values above two
+  remain loadable for compatibility but the runtime caps them at two.
 - When the budget is exhausted, a synthesis anchor forces the LLM to produce
   a final answer with citations instead of making more tool calls
 - Context compaction keeps the message window manageable for long tool chains
@@ -99,7 +101,7 @@ Configured through `ShallowResearchAgentConfig` (NeMo Agent Toolkit type name: `
 | `llm` | `LLMRef` | required | LLM to use for research |
 | `tools` | `list[FunctionRef \| FunctionGroupRef]` | `[]` | Tools available for research (web search, document search, etc.) |
 | `max_llm_turns` | `int` | `10` | Maximum LLM interaction turns |
-| `max_tool_iterations` | `int` | `5` | Maximum tool calls before forcing synthesis |
+| `max_tool_iterations` | `int` | `2` | Maximum total tool calls before synthesis; values above two are accepted but capped at two |
 | `verbose` | `bool` | `false` | Enable verbose logging |
 
 **Example YAML:**
@@ -112,7 +114,7 @@ functions:
     tools:
       - web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
     verbose: true
 ```
 
@@ -144,7 +146,8 @@ queries with the full context the user assumed but did not state.
 
 ### Synthesis Anchor
 
-When `tool_iterations >= max_tool_iterations`, the agent appends a
+When `tool_iterations` reaches the effective limit
+(`min(max_tool_iterations, 2)`), the agent appends a
 `HumanMessage` synthesis anchor after the conversation history:
 
 > "You have exhausted your research budget. Synthesize the final answer now

diff --git a/docs/source/customization/configuration-reference.md b/docs/source/customization/configuration-reference.md
@@ -432,7 +432,7 @@ functions:
       - web_search_tool
       - knowledge_search
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
     verbose: true
 ```
 
@@ -441,7 +441,7 @@ functions:
 | `llm` | `str` | **required** | LLM for research and synthesis. |
 | `tools` | `list[str]` | `[]` | Search tools available to the agent. |
 | `max_llm_turns` | `int` | `10` | Maximum number of LLM turns (includes both reasoning and tool-calling steps). |
-| `max_tool_iterations` | `int` | `5` | Maximum tool-calling iterations before forcing synthesis. |
+| `max_tool_iterations` | `int` | `2` | Maximum total tool calls before synthesis. Values above two remain valid but are capped at two. |
 | `verbose` | `bool` | `false` | Enable verbose logging. |
 
 ### `deep_research_agent`
@@ -676,7 +676,7 @@ functions:
     tools:
       - web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:                 # Multi-phase deep research
     _type: deep_research_agent

diff --git a/docs/source/examples/cli-with-local-nims.md b/docs/source/examples/cli-with-local-nims.md
@@ -126,7 +126,7 @@ functions:
     tools:
       - web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/docs/source/examples/full-pipeline-llamaindex.md b/docs/source/examples/full-pipeline-llamaindex.md
@@ -166,7 +166,7 @@ functions:
       - web_search_tool
       - knowledge_search
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   deep_research_agent:
     _type: deep_research_agent

diff --git a/docs/source/examples/full-pipeline-web.md b/docs/source/examples/full-pipeline-web.md
@@ -189,7 +189,7 @@ functions:
       - web_search_tool
       - knowledge_search
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
 
   # -------------------------------------------------------------------------
   # Deep research agent

diff --git a/docs/source/examples/minimal-shallow-only.md b/docs/source/examples/minimal-shallow-only.md
@@ -59,7 +59,7 @@ functions:
     tools:
       - web_search
     max_llm_turns: 10    # Max reasoning steps before forced output
-    max_tool_iterations: 5    # Max tool invocations per session
+    max_tool_iterations: 2    # Max total calls: initial search + one retry
 
 # ---------------------------------------------------------------------------
 # Workflow

diff --git a/docs/source/resources/troubleshooting.md b/docs/source/resources/troubleshooting.md
@@ -36,7 +36,7 @@ Common issues and solutions for the AI-Q blueprint.
 |-------|-------|-----|
 | Agent hangs on deep research | LLM timeout or rate limit | Set `verbose: true` in config to see progress; check LLM API availability and rate limits |
 | HTTP 429 or 503 on deep research | Nemotron hosted endpoint availability | Retry after a short delay, reduce concurrency, or follow the [self-hosting guidance](#nemotron-hosted-endpoint-availability) for consistent throughput |
-| Shallow research returns generic answers | Insufficient tool calls | Increase `max_tool_iterations` (default: 5) |
+| Shallow research returns generic answers | Weak or irrelevant search evidence | Keep `max_tool_iterations: 2` (the supported cap) and improve the selected source or query wording |
 | Clarifier keeps asking questions | Too many clarification turns | Reduce `max_turns`, or set `enable_clarifier: false` in the workflow to disable clarification |
 | SSE stream disconnects | Network timeout | Client auto-reconnects using `last_event_id`; refer to [Data Flow](../architecture/data-flow.md) |
 | Job status stuck on RUNNING | Dask worker crashed | Check Dask logs; the ghost job reaper will eventually mark it FAILURE |

diff --git a/frontends/aiq_api/src/aiq_api/jobs/runner.py b/frontends/aiq_api/src/aiq_api/jobs/runner.py
@@ -1311,7 +1311,7 @@ def _create_agent_instance(
         return agent_cls(
             llm_provider=llm_provider,
             tools=tools,
-            max_tool_iterations=getattr(fn_config, "max_tool_iterations", 5),
+            max_tool_iterations=getattr(fn_config, "max_tool_iterations", 2),
             callbacks=callbacks,
         )
     except TypeError:

diff --git a/frontends/benchmarks/freshqa/configs/config_full_workflow.yml b/frontends/benchmarks/freshqa/configs/config_full_workflow.yml
@@ -90,7 +90,7 @@ functions:
     tools:
       - web_search_tool
     max_llm_turns: 10
-    max_tool_iterations: 5
+    max_tool_iterations: 2
     verbose: true
 
   deep_research_agent: