Tool System

Last Updated: 2026-02-20
Primary Source: backend/src/services/tools/toolCompilation.service.ts
Service Files: backend/src/services/langchain/langchainToolTurn.service.ts, backend/src/services/toolExecutor.service.ts
Config: backend/src/config/toolCatalog.ts

---

Overview

The Tool System enables the agent to perform actions and interact with game systems through LangChain tool calling.

Tools are Level A:

• Tool handlers are implemented in code (safe/reviewable).
• Tool availability is dynamic (protocol allowlists + admin overrides) and kept in sync between:
  • LangChain tool list
  • prompt injection

---

Architecture

Tool Execution Flow

---

Tool Executor

Service

File: backend/src/services/toolExecutor.service.ts

Function: executeTool(toolId, payload, context)

Process:

1. Look up tool definition in toolCatalog.ts
2. Enforce enablement override + access policy (protocol allowlist + scope)
3. Validate tool arguments (Zod schemas)
4. Execute tool handler
5. Return tool result

Tool Handlers

Each tool has a handler function that:

• Validates input
• Performs the action
• Returns success/failure message
• Optionally returns data

---

Available Tools

1. direct_config_update

ID: direct_config_update

Purpose: Safely merge structured JSON into ASO persona/config

Mode: direct

Category: persona

Schema:

{
  action: 'get' | 'set' | 'merge' | 'append' | 'replace',
  key: string,
  value?: any
}

Handler: modifyAsoConfig()

2. learn_by_heart

ID: learn_by_heart

Purpose: Capture facts/reminders the ASO must never forget (shared with all ASOs)

Mode: direct

Category: memory

Requires: File upload

Handler: trainingService.ingestTextByHeart() or ingestFileByHeart()

3. screenshot_ocr

ID: screenshot_ocr

Purpose: Upload screenshots for OCR (user-scoped)

Mode: direct

Category: analysis

Requires: File upload (images)

Handler: extractTextFromImage()

4. web_search

ID: web_search

Purpose: Let ASO look outside its memory when needed

Mode: hybrid

Category: insight

Schema:

{
  query: string
}

Handler: specialistService.askWebSearchExpert()

5. complete_quest

ID: complete_quest

Purpose: Mark an active quest as completed

Mode: conversational

Category: analysis

Schema:

{
  questId: number
}

Handler: questService.completeQuest()

6. modify_inventory

ID: modify_inventory

Purpose: Add/remove items from user inventory

Mode: conversational

Category: analysis

Schema:

{
  itemId: number,
  quantity: number
}

Handler: inventoryService.modifyInventory()

7. modify_currency

ID: modify_currency

Purpose: Modify user currency

Mode: conversational

Category: analysis

Schema:

{
  amount: number
}

Handler: inventoryService.modifyCurrency()

8. set_relationship_flag

ID: set_relationship_flag

Purpose: Set relationship milestone flag

Mode: conversational

Category: analysis

Schema:

{
  flag: string,
  value: any
}

Handler: relationshipService.setRelationshipFlag()

---

Tool Catalog

Configuration

File: backend/src/config/toolCatalog.ts

Structure:

interface ToolDefinition {
  id: ToolId;
  label: string;
  description: string;
  icon: string;
  mode: 'direct' | 'conversational' | 'hybrid';
  enabled: boolean;
  category: 'persona' | 'memory' | 'insight' | 'analysis';
  metadata?: {
    requiresModal?: boolean;
    requiresUpload?: boolean;
    defaultPreference?: {
      autoEnabled?: boolean;
      enabled?: boolean;
    };
  };
}

Tool Modes

• direct: Tools executed directly (bypass conversation)
• conversational: Tools executed as part of conversation
• hybrid: Can be used in both contexts

---

Tool Execution Flow

---

Tool Calling Modes

Legacy JSON-Block (Current Default)

Format:

{
  "tool": "complete_quest",
  "arguments": { "questId": 123 },
  "spokenResponse": "I've completed the quest for you!"
}

Process:

1. LLM outputs JSON block
2. Gateway parses JSON
3. Executor validates and executes
4. ASO generates final response

Native Tool Calling (Optional)

Format: OpenAI-compatible tool_calls array

Process:

1. LLM returns tool_calls in response
2. Gateway extracts tool calls
3. Tool executor runs tools with policy enforcement
4. Tool results are returned to the agent loop
5. The agent produces the final response

---

API Endpoints

Tool Management

• GET /api/tools - List all available tools
• POST /api/tools/:toolId - Execute tool directly

Admin (runtime overrides)

• GET /api/admin/tool-permissions - View tool access overrides (protocol allowlist + target scope)
• PUT /api/admin/tool-permissions/:toolId - Update access override
• DELETE /api/admin/tool-permissions/:toolId - Reset access override
• GET /api/admin/tool-enablement - View tool enablement overrides (runtime on/off)
• PUT /api/admin/tool-enablement/:toolId - Update enablement override
• DELETE /api/admin/tool-enablement/:toolId - Reset enablement override

---

Source Files

Primary Sources:

• backend/src/services/toolExecutor.service.ts - Tool execution
• backend/src/config/toolCatalog.ts - Tool definitions
• backend/src/services/tools/toolSchemas.ts - Tool input schemas (shared by executor + LangChain)
• backend/src/services/tools/toolCompilation.service.ts - Tool compiler + prompt tool definitions

Related Files:

• backend/src/services/langchain/langchainToolTurn.service.ts - LangChain tool calling loop

---

Related Documentation

• AI Director - Story orchestration using tools
• Quest System - Quest tool implementation
• Inventory System - Inventory tool implementation
• Prompt System - Tool definitions in prompts
• 06-ARCHITECTURE/Data-Flow.md - Tool execution flow
• 00-OVERVIEW.md - Complete system overview