Skip to content

Adding Custom Tools

This tutorial walks through creating a custom tool, testing it in isolation, and enabling it in a chat. Start from a working development setup.

Build a custom tool, test its result, and activate it for a conversation.

Create the tool

Create src/numi_chat/tools/text_transform.py:

from typing import Any

from numi_chat.tools.base import BaseTool


class TextTransformTool(BaseTool):
    @property
    def name(self) -> str:
        return "text_transform"

    @property
    def description(self) -> str:
        return "Convert text to uppercase or lowercase."

    @property
    def parameters(self) -> dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "text": {"type": "string", "minLength": 1, "maxLength": 10000},
                "case": {"type": "string", "enum": ["upper", "lower"]},
            },
            "required": ["text", "case"],
            "additionalProperties": False,
        }

    def execute(self, **kwargs: Any) -> str:
        text = kwargs.get("text")
        case = kwargs.get("case")
        if not isinstance(text, str) or not 1 <= len(text) <= 10000:
            return self._error("text must contain 1 to 10000 characters")
        if case not in ("upper", "lower"):
            return self._error("case must be upper or lower")
        result = text.upper() if case == "upper" else text.lower()
        return self._ok(data={"transformed": result})

Every BaseTool subclass defines name, description, parameters, and execute. The JSON schema tells the model what arguments to pass, and execute validates them before returning a JSON string via self._ok(...) or self._error(...).

Accept **kwargs in execute so server-injected context (chat_id, chat_uuid, user_id) is absorbed cleanly without exposing those fields in the model-facing parameter schema.

Test the tool locally

Add tests/tools/test_text_transform.py:

import json

from numi_chat.tools.text_transform import TextTransformTool


def test_text_transform():
    tool = TextTransformTool()
    for case, expected in (("upper", "HELLO"), ("lower", "hello")):
        result = json.loads(tool.execute(text="Hello", case=case))
        assert result == {"status": "success", "data": {"transformed": expected}}
    for args in (
        {},
        {"text": 123, "case": "upper"},
        {"text": "", "case": "upper"},
        {"text": "x" * 10001, "case": "upper"},
        {"text": "Hello", "case": "unknown"},
    ):
        assert json.loads(tool.execute(**args))["status"] == "error"

Run the test:

uv run pytest tests/tools/test_text_transform.py

Enable discovery and chat selection

Two settings control whether a new optional tool can be used in chats:

  1. Append text_transform to TOOLS_ALLOWLIST in your configuration (keeping the existing default tools) and make sure it is not in TOOLS_DENYLIST.
  2. Add "text_transform" to CUSTOM_TOOL_NAMES in src/numi_chat/tools/registry.py.

ToolRegistry discovers the class automatically at startup. Adding the name to CUSTOM_TOOL_NAMES makes it selectable per chat in the web UI. Any custom tool not assigned to a specific group in CUSTOM_TOOL_GROUPS appears under Other in the composer's tool picker.

Restart and verify

Restart the server (make run-web) and check the startup log for Registered tool: text_transform.

You can also verify registration from the command line:

uv run python -c 'from numi_chat.tools.registry import tool_registry; assert "text_transform" in tool_registry.registered_tool_names(); assert "text_transform" in tool_registry.custom_tool_names(); print("text_transform is available for chat selection")'

Use it in a chat

  1. Open a chat and click the tools button in the composer.
  2. Enable Other.
  3. Send: Use text_transform to convert "Hello World" to uppercase.
  4. Expand the tool step in the response and confirm that its output contains {"transformed": "HELLO WORLD"}.

Optional tool hooks

  • Override is_available() when your tool depends on an API key or external binary. Implement availability_reason() to log a clear message when the tool is skipped at startup.
  • Set concurrency_safe = False if the tool mutates shared state and must run serially rather than in the parallel tool batch.
  • Set register_in_registry = False on base or helper classes that should not be registered as standalone tools.
  • Decorate the class with @tool_system_hints({...}) when the model benefits from a short follow-up instruction attached to the tool's output.

Custom Python tools run in the server process rather than inside the code interpreter's sandbox. Always set timeouts on network calls, cap output size, and scope any file access to the server-provided chat_id / user_id.

Troubleshooting

Symptom What to check
No registration log at startup The file is directly in src/numi_chat/tools/, ends in .py, imports cleanly, and subclasses BaseTool
Tool is skipped at startup TOOLS_ALLOWLIST, TOOLS_DENYLIST, and is_available()
Registered but missing from the composer picker Add the tool name to CUSTOM_TOOL_NAMES, then restart the server and reload the browser
Listed in the picker but the model never calls it Confirm the tool's group is enabled for the active chat

See Tool Schema for the full BaseTool reference and Tool System for how discovery and execution work.