Tool Calling

Kowork features a powerful tool calling system that enables AI assistants to execute commands, read files, and perform actions on your behalf with built-in security controls.

Overview

Tool calling allows the AI assistant to:

Execute terminal commands - run shell commands, navigate directories, execute scripts
Read and write files - access your filesystem securely
Use MCP tools - extend capabilities via Model Context Protocol servers
Parallel execution - multiple tools run simultaneously for speed

Three Tool Calling Modes

Kollabor supports three tool calling modes, each with different trade-offs:

Native Mode

Default - Most reliable

Uses formal function calling APIs (OpenAI/Anthropic standard). The AI receives structured tool definitions and responds with tool_calls array containing tool invocations.

Best for: Production use, GPT-4, Claude 3+, models with function calling support

XML Mode

Experimental - Tag-based

Uses XML tags embedded in the AI's text response like <terminal>ls</terminal>. Works with any text model that doesn't support function calling.

Best for: Text-only models, testing, research, models without native function calling

None Mode

Chat-only

Tool calling completely disabled. The AI cannot execute commands or access files - pure conversational mode only.

Best for: Chat-only interactions, when tool execution is not needed, security restrictions

Built-in Tools

Kollabor includes native tools that are always available:

execute_commandCore

Execute terminal commands directly in the chat. Supports working directory specification and configurable timeouts.

// Parameters

command: "ls -la"

workingDir: "/home/user/projects" (optional)

read_fileMCP

Read file contents from your filesystem. Available through MCP filesystem server.

write_fileMCP

Write content to files. Available through MCP filesystem server with path validation.

Tool Runner Architecture

The tool execution system uses a multi-layered architecture for reliability and security:

User sends message
       |
       v
LLM generates response (with tool calls)
       |
       v
[Native: tool_calls array | XML: parse tags]
       |
       v
ToolRunner.execute_tools() - Parallel execution
       |
       +---> For each tool:
       |      |
       |      v
       |   Security checks (dangerous operations, rate limits)
       |      |
       |      v
       |   Execute tool (terminal/MCP/filesystem)
       |      |
       |      v
       |   Collect results
       |
       v
Add tool results to chat
       |
       v
LLM analyzes results and responds

Key Components

ToolRunnerRust backend service that manages parallel tool execution (src-tauri/src/commands/tool_runner.rs)

ChatStreamServiceFrontend service handling streaming and tool orchestration (src-vue/src/services/ChatStreamService.ts)

XMLToolParserParses XML tags from text responses in XML mode (src-tauri/src/commands/xml_tool_parser.rs)

Security Layer

Tool execution includes multiple security controls to protect your system:

Dangerous Operations Check

Blocks access to sensitive system paths and dangerous tools:

System directories: /etc, /usr/bin, /bin, /sbin, /var
Windows system paths: C:\Windows, C:\Program Files
User config: ~/.ssh, ~/.aws, ~/.config
Tools with dangerous names: delete, remove, execute in system paths

Rate Limiting

Maximum 10 tool executions per minute per tool to prevent abuse and runaway processes.

Command Validation

MCP server commands validated against whitelist:

node, python, python3, npx, uvx, uv

Audit Logging

All tool executions logged with timestamps, parameters (sanitized), and results for security review.

Configuration

Tool calling mode is determined by priority (highest to lowest):

Priority	Level	How to Set
1	Chat-level	Chat settings gear icon > Tool Call Mode
2	LLM Profile	Settings > LLM > Edit Profile > Tool Call Mode
3	Global default	Settings > LLM > Tool Calling Mode dropdown

// Example: Per-profile configuration
{
  "llmProfiles": {
    "gpt-4": {
      "provider": "openai-compatible",
      "toolCallMode": "native"  // Uses function calling
    },
    "experimental-model": {
      "provider": "openai-compatible",
      "toolCallMode": "xml"  // Uses XML tags
    },
    "chat-only": {
      "provider": "anthropic",
      "toolCallMode": "none"  // No tools
    }
  }
}

XML Mode Details

In XML mode, the AI outputs special XML tags that Kollabor parses and converts to tool calls:

// Supported XML tags
<terminal>ls -la</terminal>
<terminal dir="/tmp">pwd</terminal>
<file_read path="README.md"/>
<file_write path="output.txt">content here</file_write>

The parser (src-tauri/src/commands/xml_tool_parser.rs) uses regex to extract tags and converts them to the standard tool format for execution.