OpenGauss Toolsets: Enable and Configure Agent Tools

Toolsets are named bundles that determine which tools the Gauss agent can call during a conversation. Rather than exposing every possible capability all at once, toolsets let you scope the agent’s surface area to exactly what a given platform or workflow needs — keeping prompts tight, costs low, and the agent focused.

What Is a Toolset?

A toolset is a named group of tools defined in toolsets.py. Each entry has a human-readable description, a list of direct tool names, and an optional list of other toolsets it composes from. When the agent starts, the resolved union of all enabled toolsets determines the tool schemas sent to the model. Toolsets are resolved recursively. If toolset autoformalize includes web, file, and browser, calling resolve_toolset("autoformalize") returns the full deduplicated set of all tools from all three children. The special aliases all and * resolve every registered toolset at once.

Core Tools — Always Active

_GAUSS_CORE_TOOLS is a fixed list that every platform toolset (gauss-cli, gauss-telegram, gauss-discord, etc.) shares by default. These tools are always present and are not configurable per-platform.

_GAUSS_CORE_TOOLS = [
    # File manipulation
    "read_file", "write_file", "patch", "search_files",
    # Web
    "web_search",
    # Browser automation
    "browser_navigate", "browser_snapshot", "browser_click",
    "browser_type", "browser_scroll", "browser_back",
    "browser_press", "browser_close", "browser_get_images",
    "browser_vision",
]

_GAUSS_CORE_TOOLS is intentionally narrow: file work, web lookup, and browser use. This is the minimal surface Gauss needs to autoformalize papers, run web research, and interact with browser-based resources.

Available Toolsets

The following toolsets are defined in toolsets.py. Leaf toolsets contain direct tools; composite toolsets are composed entirely from other toolsets.

Leaf Toolsets

file

File manipulation: read_file, write_file, patch (fuzzy-match patching), search_files (content and filename search).

web

Web research: web_search. Use when you need search results but not full browser interaction.

search

Web search only — identical tools to web but semantically scoped to search without content extraction or scraping.

browser

Full browser automation: navigate, snapshot, click, type, scroll, back, press, close, get images, vision — plus web_search for finding URLs.

Platform Toolsets

Each messaging and editor platform has its own named toolset. All currently resolve to _GAUSS_CORE_TOOLS and differ only in their description, which is used for display and logging.

Toolset	Platform
`gauss-cli`	Interactive terminal CLI
`gauss-acp`	VS Code, Zed, JetBrains (ACP server)
`gauss-telegram`	Telegram bot
`gauss-discord`	Discord bot
`gauss-whatsapp`	WhatsApp bot
`gauss-slack`	Slack bot
`gauss-signal`	Signal messenger
`gauss-homeassistant`	Home Assistant
`gauss-email`	Email (IMAP/SMTP)

The composite toolset gauss-gateway resolves to the union of all messaging-platform toolsets (telegram, discord, whatsapp, slack, signal, homeassistant, email).

Composite Toolsets

Toolset	Includes	Use case
`autoformalize`	`web`, `file`, `browser`	Minimal workflow for papers, source files, and browser-driven research
`gauss-gateway`	All messaging platform toolsets	Union surface for the unified messaging gateway

Configuring Toolsets

There are three ways to control which toolsets are active.

CLI Flag
config.yaml
gauss tools TUI

Pass --toolsets (comma-separated) directly when launching Gauss. This is the fastest way to narrow or expand capabilities for a single session.

# Enable only web and file tools
gauss --toolsets web,file

# Enable all tools
gauss --toolsets all

Use --disabled-toolsets to remove a toolset from an otherwise full set:

gauss --disabled-toolsets browser

Set a persistent default in ~/.gauss/config.yaml. This applies to every session unless overridden by a CLI flag.

toolsets:
  - file
  - web
  - browser

disabled_toolsets:
  - browser

The config is loaded by load_cli_config() in cli.py and by load_config() in gauss_cli/config.py depending on the invocation context.

Run gauss tools to open the interactive curses-based TUI. You can enable or disable individual toolsets per platform — changes are persisted to ~/.gauss/config.yaml.

gauss tools

The TUI lets you select a platform first (CLI, Telegram, Discord, etc.) and then toggle individual tools or entire toolsets for that context.

Tool Registry

tools/registry.py is the central registry that all tool files register into at import time. model_tools.py queries the registry instead of maintaining parallel data structures. The dependency chain is strictly one-way:

tools/registry.py  (no deps — imported by all tool files)
       ↑
tools/*.py  (each calls registry.register() at import time)
       ↑
model_tools.py  (imports tools/registry + triggers tool discovery)
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

The registry exposes:

get_definitions(tool_names) — returns OpenAI-format tool schemas filtered through check_fn() availability checks
dispatch(name, args) — executes the handler, bridges async handlers, and wraps all exceptions into a consistent {"error": "..."} JSON string
is_toolset_available(toolset) — returns True only if the toolset’s check_fn passes; returns False (never raises) on any exception
check_toolset_requirements() — returns {toolset: bool} availability map for every registered toolset

Availability Checks (`check_fn`)

Every tool registration can supply a check_fn — a zero-argument callable that returns True if the tool is available in the current environment. If check_fn returns False or raises, the tool is silently excluded from the schema list sent to the model. The first check_fn registered for a toolset becomes the toolset-level availability check surfaced in is_toolset_available() and the gauss tools TUI. Common patterns:

# Check for a required API key
def check_requirements() -> bool:
    return bool(os.getenv("FIRECRAWL_API_KEY"))

# Check for a required binary
def check_requirements() -> bool:
    return shutil.which("ffmpeg") is not None

A small number of agent-level tools — todo and memory — are intercepted by run_agent.py before handle_function_call() reaches the registry. They do not go through the normal dispatch() path. See todo_tool.py for the pattern if you need to replicate it.

Adding Custom Tools

Adding a new tool requires changes in exactly three files.

Create tools/your_tool.py

Define the handler function and register it with the registry. The handler must return a JSON string.

import json
import os
from tools.registry import registry

def check_requirements() -> bool:
    return bool(os.getenv("EXAMPLE_API_KEY"))

def example_tool(param: str, task_id: str = None) -> str:
    # All handlers must return a JSON string
    return json.dumps({"success": True, "data": f"processed: {param}"})

registry.register(
    name="example_tool",
    toolset="example",
    schema={
        "name": "example_tool",
        "description": "Does something useful with the given param.",
        "parameters": {
            "type": "object",
            "properties": {
                "param": {
                    "type": "string",
                    "description": "Input parameter to process."
                }
            },
            "required": ["param"]
        }
    },
    handler=lambda args, **kw: example_tool(
        param=args.get("param", ""),
        task_id=kw.get("task_id"),
    ),
    check_fn=check_requirements,
    requires_env=["EXAMPLE_API_KEY"],
    emoji="🔧",
)

Add import in model_tools.py

Open model_tools.py and add your module to the _discover_tools() import list. Registration happens at module level when the file is imported, so simply importing it is enough.

# Inside _discover_tools() in model_tools.py
import tools.your_tool  # registers example_tool into the registry

Add to toolsets.py

Either add your tool name to _GAUSS_CORE_TOOLS (available on every platform) or define a new named toolset:

TOOLSETS = {
    # ... existing toolsets ...
    "example": {
        "description": "Example integration tools",
        "tools": ["example_tool"],
        "includes": []
    },
}

You can also extend an existing toolset at runtime using create_custom_toolset():

from toolsets import create_custom_toolset

create_custom_toolset(
    name="my_custom",
    description="Custom toolset combining web + my tool",
    tools=["example_tool"],
    includes=["web", "file"],
)

All tool handlers must return a JSON string. Returning a plain string, None, or raising an unhandled exception will cause the registry’s dispatch() to wrap the error in {"error": "..."} and the agent will see a tool failure rather than a result.

CLI Reference

Toolsets & Skills

API & Embedding

OpenGauss Toolsets: Enable and Configure Agent Tools

What Is a Toolset?

Core Tools — Always Active

Available Toolsets

Leaf Toolsets

file

web

search

browser

Platform Toolsets

Composite Toolsets

Configuring Toolsets

Tool Registry

Availability Checks (`check_fn`)

Adding Custom Tools

Build docs developers (and LLMs) love

CLI Reference

Toolsets & Skills

API & Embedding

Documentation Index

​What Is a Toolset?

​Core Tools — Always Active

​Available Toolsets

​Leaf Toolsets

file

web

search

browser

​Platform Toolsets

​Composite Toolsets

​Configuring Toolsets

​Tool Registry

​Availability Checks (check_fn)

​Adding Custom Tools

Build docs developers (and LLMs) love

What Is a Toolset?

Core Tools — Always Active

Available Toolsets

Leaf Toolsets

Platform Toolsets

Composite Toolsets

Configuring Toolsets

Tool Registry

Availability Checks (`check_fn`)

Adding Custom Tools