fix: update agent loop iterations and improve tool usage guidelines in chat_with_mcp_tools

src/unpredictable_lord/chat/chat.py

@@ -20,8 +20,10 @@ from unpredictable_lord.settings import USE_MODAL
 
 logger = logging.getLogger(__name__)
 
-# Maximum iterations for tool calling loop
-MAX_TOOL_CALL_ITERATIONS = 5
+# Maximum iterations for agent loop (LLM call -> tool execution -> LLM call ...)
+# Typically completes in 2 iterations: (1) tool call, (2) text response with results
+# Higher values allow for complex multi-step reasoning if needed
+MAX_AGENT_ITERATIONS = 3
 
 
 if USE_MODAL:
@@ -74,6 +76,10 @@ Available advice options:
 
 After calling execute_turn, summarize the results to your advisor in character.
 
+TOOL USAGE GUIDELINES:
+- After receiving tool results, ALWAYS respond with text (do not call more tools)
+- Keep the conversation flowing naturally without excessive tool calls
+
 IMPORTANT: After each action or when starting a conversation:
 1. Explain the current situation and any recent changes
 2. Ask your advisor what they suggest next
@@ -187,9 +193,16 @@ async def chat_with_mcp_tools(
 
         accumulated_response = ""
 
-        # Tool calling loop
-        for iteration in range(MAX_TOOL_CALL_ITERATIONS):
-            logger.info(f"Tool calling iteration {iteration + 1}")
+        # Agent loop: LLM generates response -> extract tool calls -> execute tools -> repeat
+        for iteration in range(MAX_AGENT_ITERATIONS):
+            is_final_iteration = iteration == MAX_AGENT_ITERATIONS - 1
+            logger.info(f"Agent loop iteration {iteration + 1}/{MAX_AGENT_ITERATIONS}")
+
+            # Show thinking status
+            partial_history[-1]["content"] = accumulated_response + (
+                "\n\n*(...thinking...)*" if not accumulated_response else ""
+            )
+            yield partial_history
 
             result = StreamResult()
             async for history in _stream_response(
@@ -204,16 +217,26 @@ async def chat_with_mcp_tools(
             tool_calls = extract_tool_calls(result.parsed_messages)
 
             if not tool_calls:
-                logger.info("No tool calls found, ending loop")
+                logger.info("No tool calls found, ending agent loop")
                 break
 
-            logger.info(f"Found {len(tool_calls)} tool call(s)")
+            # If this is the final iteration, execute tools but don't loop again
+            # (LLM won't get another chance to respond with the results)
+            if is_final_iteration:
+                logger.warning(
+                    f"Max agent iterations ({MAX_AGENT_ITERATIONS}) reached, "
+                    "executing final tool calls without follow-up"
+                )
+
+            logger.info(f"Found {len(tool_calls)} tool call(s), executing...")
 
             # Add parsed messages to conversation
             messages.extend(result.parsed_messages)
 
-            # Indicate tool execution in UI
-            partial_history[-1]["content"] += "\n\n*(Executing orders...)*"
+            # Show tool execution status
+            partial_history[-1]["content"] = (
+                accumulated_response + "\n\n*(executing...)*"
+            )
             yield partial_history
 
             # Execute tools via MCP
@@ -221,7 +244,7 @@ async def chat_with_mcp_tools(
 
             messages.extend(tool_result_messages)
 
-            # Remove status message
+            # Clear status message before next iteration
             partial_history[-1]["content"] = accumulated_response
             yield partial_history