Dynamic Tool Discovery Guide for AI Agents

Understanding GABS Dynamic Tool System

GABS uses a progressive tool disclosure system that helps AI agents handle the dynamic expansion of available tools as games connect. This guide explains how AI agents can effectively work with GABS's growing tool ecosystem.

Related guides: AI Integration Guide for connecting AI agents, Configuration Guide for game setup, AI Dynamic Tools FAQ for common questions.

The Progressive Tool Discovery Pattern

Phase 1: Initial State (Core Game Management)

When GABS starts, AI agents see only core game management tools:

Stable core tools:
- games.list         - List configured game IDs
- games.show         - Inspect one configured game
- games.start        - Start a game
- games.stop         - Stop a game gracefully
- games.kill         - Force terminate a game
- games.status       - Check game status
- games.tool_names   - Compact mirrored-tool discovery
- games.tool_detail  - Detailed schema for one tool
- games.tools        - Rich compatibility listing
- games.connect      - Reattach to a running game's GABP server
- games.get_attention - Inspect the current blocking attention item
- games.ack_attention - Acknowledge attention and resume normal calls
- games.call_tool    - Call a mirrored tool through the stable core surface

Phase 2: Game Connection (Dynamic Expansion)

After starting a game with GABP mods, tools expand dramatically:

Available tools expand with mirrored game tools. The exact set depends on the
connected game and mod:

Minecraft-Specific Examples:
- minecraft.inventory.get     - Get player inventory
- minecraft.inventory.set     - Modify player inventory  
- minecraft.world.get_block   - Check block at position
- minecraft.world.place_block - Place block in world
- minecraft.player.teleport   - Teleport player
- minecraft.chat.send         - Send chat message
- minecraft.time.set          - Set world time
- minecraft.weather.set       - Control weather

RimWorld-Specific Tools (if rimworld also starts):
- rimworld.inventory.get      - Get colonist inventory
- rimworld.crafting.build     - Build items/structures
- rimworld.colonist.command   - Give colonist orders
- rimworld.research.progress  - Check research status

GABS can also have multiple live sessions. If another session already owns a running game, games.start and games.connect return quickly instead of hanging, and games.connect {"forceTakeover": true} can intentionally move ownership to the current session.

AI Discovery Strategies

1. The `games.tool_names` -> `games.tool_detail` Discovery Pattern (Recommended)

Best Practice: Use games.tool_names for low-token discovery, then call games.tool_detail only for the few tools you might actually use. Keep games.tools for compatibility or when you intentionally want the richer one-shot listing.

// AI Discovery Workflow
async function discoverGameCapabilities() {
  // 1. See what games are available
  const games = await mcp.callTool("games.list", {});
  
  // 2. Check what games are running  
  const status = await mcp.callTool("games.status", {});
  
  // 3. Discover compact tool names for each running game
  const allToolNames = await mcp.callTool("games.tool_names", {"brief": true});
  
  // 4. Get specific names for the game of interest
  const minecraftToolNames = await mcp.callTool("games.tool_names", {"gameId": "minecraft", "brief": true});

  // 5. Inspect one candidate in detail only when needed
  const inventoryDetail = await mcp.callTool("games.tool_detail", {
    "tool": "minecraft.inventory.get"
  });
  
  return { games, status, allToolNames, minecraftToolNames, inventoryDetail };
}

2. Progressive Enhancement Pattern

AI agents should treat tool discovery as a progressive enhancement:

Phase 1: Use core tools to start games
"Start the Minecraft server" → games.start {"gameId": "minecraft"}

Phase 2: Discover what's now possible  
"What can I do with Minecraft now?" → games.tool_names {"gameId": "minecraft", "brief": true}

Phase 2b: Inspect one candidate when needed
"What does minecraft.inventory.get accept?" → games.tool_detail {"tool": "minecraft.inventory.get"}

Phase 3: Use discovered tools
"Get Steve's inventory" → minecraft.inventory.get {"playerId": "steve"}

3. Context-Aware Tool Usage

Tools are namespaced by game ID to prevent conflicts:

✅ Clear Intent:
- minecraft.inventory.get {"playerId": "steve"}      # Steve's Minecraft inventory
- rimworld.inventory.get {"colonistId": "alice"}     # Alice's RimWorld inventory

❌ Ambiguous (avoided by design):  
- inventory.get {"playerId": "steve"}                # Which game?

Real-World AI Interaction Examples

Example 1: Starting Fresh

User: "Help me manage my games"
AI: Let me see what games you have configured...
    → games.list
    
AI: I see you have minecraft and rimworld configured. Neither is running.
    Would you like me to start one of them?

User: "Start Minecraft"  
AI: Starting Minecraft...
    → games.start {"gameId": "minecraft"}
    
AI: Minecraft started! Let me see what I can help you with...
    → games.tool_names {"gameId": "minecraft", "brief": true}
    
AI: Great! Now I can help you with:
    - Managing your inventory (minecraft.inventory.get/set)
    - Building in your world (minecraft.world.place_block) 
    - Teleporting around (minecraft.player.teleport)
    - Controlling time and weather
    What would you like to do?

Example 2: Multi-Game Management

User: "I want to run both games and manage them"
AI: I'll start both games and show you the expanded capabilities...
    → games.start {"gameId": "minecraft"}
    → games.start {"gameId": "rimworld"}  
    → games.tool_names {"brief": true}
    
AI: Perfect! Now I can help you with:
    
    Minecraft:
    - Inventory management
    - World building  
    - Player control
    
    RimWorld:
    - Colony management
    - Crafting systems
    - Research progress
    
    The tools are clearly separated by game name, so I can help
    you manage both simultaneously without confusion.

Example 3: Discovery-Driven Assistance

User: "What's possible with my Minecraft server?"
AI: Let me check what your Minecraft mod exposes...
    → games.tool_names {"gameId": "minecraft", "brief": true}
    → games.tool_detail {"tool": "minecraft.inventory.get"}
    
AI: Your Minecraft setup provides these capabilities:
    - Inventory System: Get/modify player inventories
    - World Interaction: Place/check blocks, teleport players  
    - Server Control: Manage time, weather, send chat messages
    
    This suggests you have a comprehensive admin/creative mod installed.
    What would you like me to help you with?

User: "Give me a diamond sword"
AI: I'll add a diamond sword to your inventory...
    → minecraft.inventory.set {"playerId": "steve", "item": "diamond_sword", "count": 1}

Technical Implementation for AI Developers

1. Tool List Caching with Refresh

class GABSToolManager {
  constructor(mcpClient) {
    this.mcp = mcpClient;
    this.toolCache = new Map();
    this.lastRefresh = 0;
    this.refreshInterval = 30000; // 30 seconds
  }
  
  async getAvailableTools(gameId = null) {
    if (this.shouldRefresh()) {
      await this.refreshToolCache();
    }
    
    if (gameId) {
      return this.toolCache.get(gameId) || [];
    }
    
    return Array.from(this.toolCache.values()).flat();
  }
  
  async refreshToolCache() {
    const tools = await this.mcp.callTool("games.tool_names", {"brief": true});
    // Parse and cache by game...
    this.lastRefresh = Date.now();
  }
}

2. Smart Tool Discovery

async function intelligentGameManagement(request) {
  // 1. Parse user intent
  const intent = parseUserRequest(request);
  
  // 2. Check if we need to start games first
  if (intent.requiresGame && !await isGameRunning(intent.gameId)) {
    await startGame(intent.gameId);
    
    // 3. Wait a moment for GABP connection
    await sleep(2000);
    
    // 4. Refresh tool knowledge
    await refreshAvailableTools();
  }
  
  // 5. Execute with discovered tools
  return await executeWithDiscoveredTools(intent);
}

Best Practices for AI Agents

✅ Do:

Use games.tool_names for discovery before attempting game-specific actions; add brief: true when a one-line structured summary helps ranking
Cache tool lists but refresh periodically or after game state changes
Use games.tool_detail only for the few tools you might actually call; omit gameId when the tool name is already fully qualified
Handle tool expansion gracefully - treat new tools as opportunities
Use game-prefixed tool names explicitly to avoid ambiguity
Group tools by game in user interfaces for clarity

❌ Don't:

Don't assume tools exist without checking via games.tool_names
Don't cache tools indefinitely - they change as games start/stop
Don't try to use generic tool names like inventory.get
Don't overwhelm users with massive detailed tool dumps - group and filter intelligently
Don't treat duplicate starts as success signals - if another live GABS session already owns the game, expect games.start or games.connect to return a quick "already running/owned" style message

GABS Design Advantages for AI

The GABS architecture specifically helps AI agents handle dynamic tools:

Clear Namespacing: minecraft.inventory.get vs rimworld.inventory.get eliminates ambiguity
Discovery Tools: games.tool_names and games.tool_detail provide structured tool exploration
Gradual Disclosure: Tools appear as games connect, not all at once
Status Awareness: AI can check game state before attempting tool use
Fallback Gracefully: Core game management always available

Conclusion

AI agents working with GABS will handle dynamic tool expansion effectively because:

The discovery pattern is predictable - start with games.tool_names
Tool names are unambiguous - game prefixes prevent conflicts
Expansion is progressive - tools appear as capabilities are needed
The core remains stable - basic game management always works

The key insight is that AI agents should embrace the discovery process rather than trying to know all tools upfront. GABS's design makes this discovery natural and reliable.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Dynamic Tool Discovery Guide for AI Agents

Understanding GABS Dynamic Tool System

The Progressive Tool Discovery Pattern

Phase 1: Initial State (Core Game Management)

Phase 2: Game Connection (Dynamic Expansion)

AI Discovery Strategies

1. The `games.tool_names` -> `games.tool_detail` Discovery Pattern (Recommended)

2. Progressive Enhancement Pattern

3. Context-Aware Tool Usage

Real-World AI Interaction Examples

Example 1: Starting Fresh

Example 2: Multi-Game Management

Example 3: Discovery-Driven Assistance

Technical Implementation for AI Developers

1. Tool List Caching with Refresh

2. Smart Tool Discovery

Best Practices for AI Agents

✅ Do:

❌ Don't:

GABS Design Advantages for AI

Conclusion

FilesExpand file tree

DYNAMIC_TOOLS_GUIDE.md

Latest commit

History

DYNAMIC_TOOLS_GUIDE.md

File metadata and controls

Dynamic Tool Discovery Guide for AI Agents

Understanding GABS Dynamic Tool System

The Progressive Tool Discovery Pattern

Phase 1: Initial State (Core Game Management)

Phase 2: Game Connection (Dynamic Expansion)

AI Discovery Strategies

1. The games.tool_names -> games.tool_detail Discovery Pattern (Recommended)

2. Progressive Enhancement Pattern

3. Context-Aware Tool Usage

Real-World AI Interaction Examples

Example 1: Starting Fresh

Example 2: Multi-Game Management

Example 3: Discovery-Driven Assistance

Technical Implementation for AI Developers

1. Tool List Caching with Refresh

2. Smart Tool Discovery

Best Practices for AI Agents

✅ Do:

❌ Don't:

GABS Design Advantages for AI

Conclusion

1. The `games.tool_names` -> `games.tool_detail` Discovery Pattern (Recommended)