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.
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:
Enable discovery and chat selection¶
Two settings control whether a new optional tool can be used in chats:
- Append
text_transformtoTOOLS_ALLOWLISTin your configuration (keeping the existing default tools) and make sure it is not inTOOLS_DENYLIST. - Add
"text_transform"toCUSTOM_TOOL_NAMESinsrc/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¶
- Open a chat and click the tools button in the composer.
- Enable Other.
- Send:
Use text_transform to convert "Hello World" to uppercase. - 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. Implementavailability_reason()to log a clear message when the tool is skipped at startup. - Set
concurrency_safe = Falseif the tool mutates shared state and must run serially rather than in the parallel tool batch. - Set
register_in_registry = Falseon 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.