Expose strict-safe MCP tool names

Author: pardeike

README.md

@@ -158,34 +158,44 @@ In the GABP layer, your mod is the server and GABS is the client.
 
 ## Common MCP Tools
 
-Most users only need a few tools at first:
-
-- **`games.list`** - List configured game IDs
-- **`games.show`** - Show one saved game config
-- **`games.start`** - Start a game
-- **`games.stop`** - Stop a game gracefully
-- **`games.kill`** - Force stop a game
-- **`games.status`** - Check if a game is running
-- **`games.connect`** - Reconnect to a running game's mod bridge
-- **`games.tool_names`** - List mirrored game-specific tools after a mod connects
-- **`games.tool_detail`** - Show the schema for one mirrored tool
-- **`games.call_tool`** - Call a mirrored tool through the stable core surface
+Most users only need a few tools at first. Release builds expose strict-safe MCP
+tool names by default because some clients reject dots in tool names:
+
+- **`games_list`** - List configured game IDs
+- **`games_show`** - Show one saved game config
+- **`games_start`** - Start a game
+- **`games_stop`** - Stop a game gracefully
+- **`games_kill`** - Force stop a game
+- **`games_status`** - Check if a game is running
+- **`games_connect`** - Reconnect to a running game's mod bridge
+- **`games_tool_names`** - List mirrored game-specific tools after a mod connects
+- **`games_tool_detail`** - Show the schema for one mirrored tool
+- **`games_call_tool`** - Call a connected game tool through the stable core surface
+
+The older dotted names such as `games.list` and `games.call_tool` remain accepted
+as call aliases, but `tools/list` advertises strict-safe names unless you
+explicitly disable normalization in config.
 
 For the full MCP surface and advanced behavior, see the
 [AI Integration Guide](docs/INTEGRATION.md).
 
 ## Game-Specific Tools from Mods
 
-When a GABP-compatible mod connects, GABS mirrors the mod's canonical tool
-names into MCP-friendly names such as `minecraft.inventory.get` or
-`rimworld.crafting.build`.
+When a GABP-compatible mod connects, GABS mirrors the mod's canonical
+slash-delimited GABP tool names into strict-safe MCP names such as
+`minecraft_inventory_get` or `rimworld_crafting_build`.
+After `games_start`, tool mirroring can finish asynchronously so the first game
+command is not delayed by large `tools/list` responses. Use `games_call_tool`
+with a fully qualified slash or dotted alias when you want to issue the first
+command immediately; `games_tool_names` and direct mirrored MCP tools become
+available as soon as mirroring completes.
 
 The usual discovery flow is:
 ```
 AI: "Reconnect to RimWorld and show me its mod tools"
-GABS: games.connect {"gameId": "rimworld"}
-GABS: games.tool_names {"gameId": "rimworld", "brief": true}
-GABS: games.tool_detail {"tool": "rimworld.crafting.build"}
+GABS: games_connect {"gameId": "rimworld"}
+GABS: games_tool_names {"gameId": "rimworld", "brief": true}
+GABS: games_tool_detail {"tool": "rimworld_crafting_build"}
 ```
 
 Most users can ignore attention gating, resource mirroring, and protocol

docs/AI_CLIENT_SETUP.md

@@ -157,7 +157,8 @@ the `server` subcommand.
 
 ### OpenAI-Style Tool Calling Clients
 
-Only do this if your client has strict OpenAI-style tool naming rules.
+This is enabled by default in current releases. Keep it enabled if your client
+has strict OpenAI- or Claude-style tool naming rules.
 
 Enable tool normalization in `~/.gabs/config.json`:
 
@@ -171,8 +172,9 @@ Enable tool normalization in `~/.gabs/config.json`:
 }
 ```
 
-This turns tool names like `minecraft.inventory.get` into
-`minecraft_inventory_get`.
+This turns tool names like `games.call_tool` and `minecraft.inventory.get` into
+`games_call_tool` and `minecraft_inventory_get`. Older dotted names remain
+accepted as call aliases.
 
 See also:
 
@@ -197,7 +199,7 @@ curl -X POST http://localhost:8080/mcp \
     "id": 1,
     "method": "tools/call",
     "params": {
-      "name": "games.list",
+      "name": "games_list",
       "arguments": {}
     }
   }'

docs/AI_DYNAMIC_TOOLS_FAQ.md

@@ -18,30 +18,30 @@ GABS provides a compact two-step discovery flow specifically for this purpose:
 
 ```javascript
 // AI discovers compact names for a specific game
-const minecraftToolNames = await mcp.callTool("games.tool_names", {"gameId": "minecraft", "brief": true});
+const minecraftToolNames = await mcp.callTool("games_tool_names", {"gameId": "minecraft", "brief": true});
 
 // AI inspects one candidate in detail
-const inventoryDetail = await mcp.callTool("games.tool_detail", {
-  "tool": "minecraft.inventory.get"
+const inventoryDetail = await mcp.callTool("games_tool_detail", {
+  "tool": "minecraft_inventory_get"
 });
 
 // The richer compatibility listing still exists when needed
-const allGameTools = await mcp.callTool("games.tools", {});
+const allGameTools = await mcp.callTool("games_tools", {});
 ```
 
-This gives AI agents a predictable "discover names first, inspect details second" workflow, which is much more context-efficient than always dumping every schema up front. `games.tool_names` defaults to 50 names per page and can add one-line summaries in structured output with `brief: true`.
+This gives AI agents a predictable "discover names first, inspect details second" workflow, which is much more context-efficient than always dumping every schema up front. `games_tool_names` defaults to 50 names per page and can add one-line summaries in structured output with `brief: true`.
 
 ### 2. **Clear Namespacing Prevents Chaos**
 Even with many tools from multiple games, AI agents can stay oriented because:
 
 ```
 ✅ Clear and Unambiguous:
-- minecraft.inventory.get 
-- minecraft.world.place_block
-- rimworld.inventory.get
-- rimworld.crafting.build
-- valheim.inventory.get
-- valheim.building.construct
+- minecraft_inventory_get
+- minecraft_world_place_block
+- rimworld_inventory_get
+- rimworld_crafting_build
+- valheim_inventory_get
+- valheim_building_construct
 
 ❌ Confusing (what GABS avoids):
 - inventory.get  (which game?)
@@ -68,7 +68,7 @@ up front.
 User: "Help me with my Minecraft server"
 
 AI: Let me see what I can do with Minecraft...
-    → games.tool_names {"gameId": "minecraft", "brief": true}
+    -> games_tool_names {"gameId": "minecraft", "brief": true}
 
 AI: I can help you with:
     - Managing player inventories
@@ -81,15 +81,15 @@ AI: I can help you with:
 User: "Give me a diamond sword"
 
 AI: I'll add that to your inventory...
-    → minecraft.inventory.set {"playerId": "steve", "item": "diamond_sword", "count": 1}
+    -> minecraft_inventory_set {"playerId": "steve", "item": "diamond_sword", "count": 1}
 ```
 
 ### Example 2: Multi-Game Awareness  
 ```
 User: "I'm running both Minecraft and RimWorld, help me manage both"
 
 AI: Let me check what I can do with both games...
-    → games.tool_names {"brief": true}
+    -> games_tool_names {"brief": true}
 
 AI: Perfect! I can help you with:
     
@@ -109,11 +109,11 @@ AI: Perfect! I can help you with:
 class GABSClient {
   async refreshToolsWhenNeeded() {
     // Check if games have changed state
-    const currentGames = await this.mcp.callTool("games.status", {});
+    const currentGames = await this.mcp.callTool("games_status", {});
 
     if (this.gameStateChanged(currentGames)) {
       // Refresh compact tool names
-      this.availableTools = await this.mcp.callTool("games.tool_names", {"brief": true});
+      this.availableTools = await this.mcp.callTool("games_tool_names", {"brief": true});
       this.lastRefresh = Date.now();
     }
   }
@@ -128,13 +128,13 @@ The test suite covers the important discovery behaviors:
 ```
 ✅ AI starts with the stable core management surface
 ✅ AI discovers mirrored tools after a game connects
-✅ AI uses games.tool_names and games.tool_detail to understand capabilities
+✅ AI uses games_tool_names and games_tool_detail to understand capabilities
 ✅ AI manages multiple connected games without tool-name collisions
 ✅ AI can recover after reconnects and session ownership changes
 ```
 
 ### AI Discovery Patterns That Work:
-1. **Discovery-First**: Always check `games.tool_names` before attempting game actions
+1. **Discovery-First**: Always check `games_tool_names` before attempting game actions
 2. **Caching with Refresh**: Cache tools but refresh after game state changes
 3. **Intent-Based Filtering**: Filter large tool sets by user intent
 4. **Lazy Loading**: Only load tools for games the user is actually using
@@ -145,7 +145,7 @@ The test suite covers the important discovery behaviors:
 ```javascript
 // Pattern 1: Always discover before acting
 async handleGameRequest(gameId, action) {
-  const gameTools = await mcp.callTool("games.tool_names", {gameId, brief: true});
+  const gameTools = await mcp.callTool("games_tool_names", {gameId, brief: true});
   const availableActions = parseToolsForCapabilities(gameTools);
 
   if (availableActions.includes(action)) {
@@ -170,10 +170,10 @@ function organizeToolsForUser(allTools) {
 ### ❌ Anti-Patterns to Avoid:
 ```javascript
 // Don't cache tools indefinitely
-const toolsCache = await mcp.callTool("games.tool_names", {}); // DON'T cache forever
+const toolsCache = await mcp.callTool("games_tool_names", {}); // DON'T cache forever
 
 // Don't assume tools exist without checking
-await mcp.callTool("minecraft.inventory.get", {...}); // Check games.tool_names first!
+await mcp.callTool("minecraft_inventory_get", {...}); // Check games_tool_names first!
 
 // Don't overwhelm users with massive tool lists
 console.log("Here are all available tools..."); // Group by game instead!
@@ -184,10 +184,10 @@ console.log("Here are all available tools..."); // Group by game instead!
 ### GABS Architecture Supports This:
 1. **MCP Compliance**: Standard JSON-RPC with proper tool metadata
 2. **Game Prefixing**: Automatic namespacing prevents conflicts
-3. **Discovery APIs**: `games.tool_names` and `games.tool_detail` provide structured exploration
+3. **Discovery APIs**: `games_tool_names` and `games_tool_detail` provide structured exploration
 4. **Status Awareness**: AI can check game state before tool usage
 5. **Mirror System**: Automatic GABP→MCP tool conversion
-6. **Session Ownership Guardrails**: Duplicate `games.start` and `games.connect`
+6. **Session Ownership Guardrails**: Duplicate `games_start` and `games_connect`
    requests return quickly instead of racing a second live GABS session
 
 ## What About Multiple GABS Sessions?
@@ -196,11 +196,11 @@ This matters in the real world because developers often have more than one AI
 session open.
 
 - If one live GABS session already owns a running or starting game,
-  `games.start` returns quickly instead of launching a duplicate process
-- `games.connect` also returns quickly instead of hanging on a competing bridge
+  `games_start` returns quickly instead of launching a duplicate process
+- `games_connect` also returns quickly instead of hanging on a competing bridge
   connection
-- `games.status` can report that another GABS session owns the process
-- If takeover is intentional, `games.connect {"gameId": "rimworld",
+- `games_status` can report that another GABS session owns the process
+- If takeover is intentional, `games_connect {"gameId": "rimworld",
   "forceTakeover": true}` moves ownership to the current session
 
 ### Current State
@@ -226,7 +226,7 @@ The concern is valid: dynamic tool expansion can be confusing if the system does
 not provide structure. GABS provides that structure.
 
 ### Why It Works:
-1. **Predictable Discovery**: `games.tool_names` makes tool exploration systematic
+1. **Predictable Discovery**: `games_tool_names` makes tool exploration systematic
 2. **Clear Namespacing**: Game prefixes eliminate all ambiguity
 3. **Progressive Disclosure**: Tools appear as capabilities are needed, not all at once
 4. **Standard MCP**: AI agents already know how to handle MCP tool expansion
@@ -235,8 +235,8 @@ not provide structure. GABS provides that structure.
 ### Real-World Outcome:
 AI agents working with GABS will naturally develop patterns like:
 
-1. **Start with basics**: Use core `games.*` tools to manage games
-2. **Discover capabilities**: Use `games.tool_names`, then `games.tool_detail` for the few tools you want to inspect; fully qualified tool names let you omit `gameId` in the detail and call steps
+1. **Start with basics**: Use core `games_*` tools to manage games
+2. **Discover capabilities**: Use `games_tool_names`, then `games_tool_detail` for the few tools you want to inspect; fully qualified tool names let you omit `gameId` in the detail and call steps
 3. **Use clear names**: Always use game-prefixed tool names for clarity
 4. **Cache intelligently**: Refresh tool knowledge after game state changes
 

docs/CONFIGURATION.md

@@ -234,20 +234,32 @@ use `games.connect` with `forceTakeover: true`.
 
 ## Tool Normalization Configuration
 
-Only use this if your AI platform has strict tool naming rules, such as the
-OpenAI API.
+GABS exposes strict-safe MCP tool names by default. This keeps `tools/list`
+accepted by clients that reject dotted names, including Claude variants seen in
+the field. The configuration key keeps its historical name for compatibility.
 
 ### Tool Normalization Options
 
 The `toolNormalization` section supports these options:
 
-- **`enableOpenAINormalization`** (boolean): Enable/disable OpenAI-compatible normalization (default: `false`)
-  - Replaces dots (.) with underscores (_) in tool names
+- **`enableOpenAINormalization`** (boolean): Enable/disable strict-safe MCP name normalization (default: `true` when `toolNormalization` is omitted)
+  - Replaces dots, slashes, and other unsafe separators with underscores
   - Enforces 64-character length limit
-  - Ensures tool names start with a letter
 - **`maxToolNameLength`** (integer): Maximum length for tool names (default: `64`)
 - **`preserveOriginalName`** (boolean): Store original name in tool description/metadata (default: `true`)
 
+Set `enableOpenAINormalization` to `false` only when you intentionally need the
+old dotted MCP names in `tools/list`.
+
+**Example transformations:**
+- `games.call_tool` -> `games_call_tool`
+- `minecraft.inventory.get` -> `minecraft_inventory_get`
+- GABP `rimbridge/ping` for game `rimworld` -> `rimworld_rimbridge_ping`
+
+Call aliases remain backward compatible: `games_call_tool`, `games.call_tool`,
+qualified slash names, qualified dotted names, and discovered strict-safe names
+all resolve without underscore guessing.
+
 ### Example Configuration
 
 ```json
@@ -264,6 +276,8 @@ The `toolNormalization` section supports these options:
 }
 ```
 
+For complete details about tool normalization, see the [Tool Normalization Guide](OPENAI_TOOL_NORMALIZATION.md).
+
 ## Startup Timeout Configuration
 
 If your game takes longer to appear in the process list or longer for its GABP
@@ -280,6 +294,10 @@ The `timeouts.startup` section supports these options:
   game's GABP server to become available before returning control to you
   (default: `60`)
 
+`games_start` only waits for the GABP handshake. Mirroring the connected mod's
+full tool list can continue briefly in the background, so known startup commands
+can be sent immediately through `games_call_tool` while discovery tools refresh.
+
 ### Example Configuration
 
 ```json
@@ -297,19 +315,6 @@ The `timeouts.startup` section supports these options:
 }
 ```
 
-### When to Use OpenAI Normalization
-
-Enable this feature when:
-- Using GABS with OpenAI's API directly
-- Your game mods use dotted tool names (e.g., `minecraft.inventory.get`)
-- You need strict OpenAI API compliance
-
-**Example transformations:**
-- `minecraft.inventory.get` → `minecraft_inventory_get`
-- `rimworld.crafting.build` → `rimworld_crafting_build`
-
-For complete details about tool normalization, see the [OpenAI Tool Normalization Guide](OPENAI_TOOL_NORMALIZATION.md).
-
 ## Improved Game Stopping
 
 GABS can stop games more reliably when `stopProcessName` is set correctly.