From d028846a145b0e29e89455ce1e8cb3143e3d9139 Mon Sep 17 00:00:00 2001
From: Jerome <jerome@anthropic.com>
Date: Thu, 12 Jun 2025 12:08:10 +0100
Subject: [PATCH] Update conversation system documentation for tool naming fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update MCP tool naming from server.tool to server__tool format
- Add tool naming requirements section with OpenRouter API constraints
- Update troubleshooting guide with tool naming validation errors
- Add specific troubleshooting for agent loop hanging with MCP tools

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/conversation_system_design.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/docs/conversation_system_design.md b/docs/conversation_system_design.md
index 521dbf6..fb85a88 100644
--- a/docs/conversation_system_design.md
+++ b/docs/conversation_system_design.md
@@ -132,19 +132,32 @@ Built-in tools for development and testing:
 
 #### MCP Tools
 Tools from connected MCP servers are:
-- **Name-prefixed**: `${serverName}.${toolName}` to avoid conflicts
+- **Name-prefixed**: `${serverName}__${toolName}` to avoid conflicts and comply with API requirements
 - **Dynamically routed**: Tool calls extract server name and route to correct connection
 - **Auto-discovered**: Available tools update when servers connect/disconnect
 
 ```typescript
 // Tool execution routing
-if (toolCall.function.name.includes('.')) {
-  const [serverName] = toolCall.function.name.split('.');
+if (toolCall.function.name.includes('__')) {
+  const [serverName] = toolCall.function.name.split('__');
   const connection = connections.find(conn => conn.name === serverName);
   return await callMCPTool(connection.id, toolCall.function.name, toolCall.function.arguments);
 }
 ```
 
+#### Tool Naming Requirements
+
+**Important**: Tool names must comply with OpenRouter API requirements:
+- **Pattern**: Must match `^[a-zA-Z0-9_-]{1,64}$`
+- **No dots allowed**: This is why we use double underscore (`__`) as separator
+- **Length limit**: Maximum 64 characters total
+
+Example tool names:
+- ✅ `test__echo` (valid)
+- ✅ `weather_service__get_forecast` (valid) 
+- ❌ `test.echo` (invalid - contains dot)
+- ❌ `server__very_long_tool_name_that_exceeds_the_sixty_four_character_limit` (invalid - too long)
+
 ## State Management
 
 ### Conversation Persistence
@@ -384,8 +397,9 @@ Debug conversation state in browser DevTools:
 
 **Tool calls not working**
 - Verify MCP server connections in MCP Status panel
-- Check tool name prefixing for MCP tools (`server.tool_name`)
+- Check tool name prefixing for MCP tools (`server__tool_name`)
 - Ensure tool schemas match expected format
+- Verify tool names comply with API requirements (alphanumeric, underscore, hyphen only)
 
 **Conversations not persisting**
 - Check localStorage quota and permissions
@@ -397,4 +411,10 @@ Debug conversation state in browser DevTools:
 - Verify `refreshAuthState()` is called after auth changes
 - Check React DevTools for proper context updates
 
+**Agent loop hangs with MCP tools connected**
+- Check browser console for OpenRouter API errors about tool names
+- Verify tool names don't contain dots or other invalid characters
+- Ensure tool names are under 64 characters total length
+- Look for pattern validation errors: `String should match pattern '^[a-zA-Z0-9_-]{1,64}'`
+
 This system provides a robust foundation for conversational AI with extensible tool calling capabilities, proper state management, and a clean user experience.
\ No newline at end of file