Tool Calling

Kollab gives the model two ways to call tools: native function calling and XML tags in the response text. Both modes run through one execution pipeline, and every call passes through the permission system before it runs.

Overview

Which mode a session uses is decided per LLM profile by the supports_tools setting (default on):

Native mode - the provider's formal function calling API. Tool definitions are sent with the request and the model answers with a structured tool_calls list. Preferred whenever the model supports it.
XML mode - the model writes tool calls as XML tags inside its text response. Turn this on with supports_tools: false for models without function calling.
One pipeline - both modes are parsed and executed by the same unified tool pipeline, so permissions, MCP tools, and plugin tools behave identically either way.

XML Tool Tags

In XML mode the model emits tags that Kollab parses into tool calls. These tags are real, parsed by kollabor_ai.response_parser and executed by the file operations executor:

Tag	What It Does
`<terminal>`	Run a shell command. Attributes: background, name, timeout, cwd
`<read>`	Read file contents
`<create>`	Create a new file
`<create_overwrite>`	Create a file, replacing it if it exists
`<edit>`	Replace matched text in an existing file
`<append>`	Append content to a file
`<insert_after>`	Insert content after a matching pattern
`<insert_before>`	Insert content before a matching pattern
`<delete>`	Delete a file
`<move>`	Move or rename a file
`<copy>`	Copy a file
`<copy_overwrite>`	Copy a file, overwriting the destination
`<mkdir>`	Create a directory
`<rmdir>`	Remove a directory
`<grep>`	Search file contents for a pattern
`<tool name="...">`	Call an MCP tool by name with attributes as arguments

File operation tags carry their parameters in inner elements:

<terminal cwd="/tmp" timeout="5m">npm test</terminal>

<create>
  <file>src/new_module.py</file>
  <content>print("hello")</content>
</create>

<edit>
  <file>src/app.py</file>
  <find>text to find</find>
  <replace>replacement text</replace>
</edit>

<insert_after>
  <file>README.md</file>
  <pattern>## Install</pattern>
  <content>New section content</content>
</insert_after>

Plugins can register their own XML tags as real tools through the plugin tool SDK (register_plugin_tag and register_plugin_handler), and those tags flow through the same pipeline.

Native Tools

With supports_tools enabled (the default), Kollab sends tool definitions using the provider's function calling API. The model responds with a structured tool_calls list instead of inline tags, which avoids parsing ambiguity and is the reliable path for models that support it.

MCP tools join the same pipeline: servers you connect expose their tools to the model, and calls arrive as native tools or as <tool> tags depending on the profile's mode. See the MCP guide.

How Execution Works

Native and XML tools share one execution path. The response parser runs on every response regardless of whether native tools are present, so a model can mix plain text, native calls, and XML tags in one reply:

Model response
       |
       v
Response parser (kollabor_ai.response_parser)
  - native tool_calls, if any
  - XML tags: terminal, file operations, <tool>, plugin tags
       |
       v
Unified tool pipeline (queue processor)
       |
       +---> Permission system check (every call)
       |        |
       |        v
       |     Approve, ask, or deny
       |
       +---> Execute (shell, filesystem, MCP, plugin handler)
       |
       v
Results returned to the model for the next turn

Key Components

ResponseParserExtracts tool calls from every response, native or XML (kollabor_ai/response_parser.py)

Queue ProcessorSingle pipeline that executes native and XML tools on one code path (queue_processor.py)

File Operations ExecutorRuns the file operation tags against the filesystem (file_operations_executor)

Safety

Tool safety in Kollab is the permission system, not path blocklists. Every tool call, native or XML, is hooked at SECURITY priority (900) on the event bus and checked before execution:

Risk levels - each call is assessed and high-risk actions prompt you before running
Approval modes - from confirm-everything to trust-everything, switchable at runtime with /permissions
Session-scoped approvals - grant once, for the session, or permanently per tool

See the Permissions guide for the full reference.

Configuration

The mode is a per-profile setting. In a profile, set:

// ~/.kollab/config.json
{
  "kollabor": {
    "llm": {
      "profiles": {
        "main": {
          "supports_tools": true    // Native function calling (default)
        },
        "old-model": {
          "supports_tools": false   // XML tags in the response text
        }
      }
    }
  }
}

Profiles are managed with the /llm command. See the Configuration guide and the Loadouts guide.