Adding Custom Tools to ToolUniverse

Three ways to add tools — pick the one that fits your needs:

Approach	When to use
JSON config	REST API with standard request/response — no coding needed
Python class (workspace)	Custom logic for local/private use only
Plugin package	Reusable tools you want to share or install via pip

Option A — Workspace tools (local use)

Tools in .tooluniverse/tools/ are auto-discovered at startup. No installation needed.

mkdir -p .tooluniverse/tools

JSON config

Create .tooluniverse/tools/my_tools.json:

[
  {
    "name": "MyAPI_search",
    "description": "Search my internal database. Returns matching records with id, title, and score.",
    "type": "BaseRESTTool",
    "fields": {
      "endpoint": "https://my-api.example.com/search"
    },
    "parameter": {
      "type": "object",
      "properties": {
        "q": {
          "type": "string",
          "description": "Search query"
        },
        "limit": {
          "type": ["integer", "null"],
          "description": "Max results to return (default 10)"
        }
      },
      "required": ["q"]
    }
  }
]

One JSON file can define multiple tools — just add more objects to the array.

For the full JSON field reference, see references/json-tool.md.

Python class

Create .tooluniverse/tools/my_tool.py:

from tooluniverse.tool_registry import register_tool

@register_tool
class MyAPI_search:
    name = "MyAPI_search"
    description = "Search my internal database. Returns matching records with id, title, and score."
    input_schema = {
        "type": "object",
        "properties": {
            "q": {"type": "string", "description": "Search query"},
            "limit": {"type": "integer", "description": "Max results (default 10)"}
        },
        "required": ["q"]
    }

    def run(self, q: str, limit: int = 10) -> dict:
        import requests
        resp = requests.get(
            "https://my-api.example.com/search",
            params={"q": q, "limit": limit},
            timeout=30,
        )
        resp.raise_for_status()
        return {"status": "success", "data": resp.json()}

Note: workspace Python tools use run(self, **named_params) — arguments are unpacked as keyword arguments matching the input_schema properties.

For the full Python class reference, see references/python-tool.md.

Test workspace tools

# Uses test_examples from the tool's JSON config — zero config needed
tu test MyAPI_search

# Single ad-hoc call
tu test MyAPI_search '{"q": "test"}'

# Full config with assertions
tu test --config my_tool_tests.json

tu test automatically runs these checks on every call:

Result is not None or empty
return_schema validation — validates result["data"] against the JSON Schema defined in return_schema (if present)
expect_status and expect_keys — only if set in the config file

Gotcha: tu test does NOT verify that results are non-empty. An empty array [] satisfies "type": "array" and passes all checks. Make sure your test_examples use args that actually return results — otherwise a completely broken tool can pass all tests silently.

Verify test_examples manually before finalizing. Run a quick Python snippet against the real API with your chosen args BEFORE writing them into test_examples. Some APIs require all query words to appear literally in a title field (intitle-style); overly specific queries like "I2C pull-up resistor value" will return 0 results even though the tool works. Use 2-4 key words that are reliably present in real content.

Use urllib rather than curl for API verification — curl requires shell quoting tricks and may not follow redirects correctly, while urllib matches what the tool will actually do:

import urllib.request, json
with urllib.request.urlopen("https://api.example.com/search?q=test") as r:
    print(json.dumps(json.loads(r.read()), indent=2))

Also check that the URL is still a real JSON API before writing any tool code. Some candidate URLs (e.g. certification.oshwa.org/api/projects) may redirect to a GitHub Pages static site that returns HTML, not JSON. A quick urllib fetch will reveal this immediately.

my_tool_tests.json (optional extra assertions):

{
  "tool_name": "MyAPI_search",
  "tests": [
    {
      "name": "basic search",
      "args": {"q": "climate change"},
      "expect_status": "success",
      "expect_keys": ["data"]
    }
  ]
}

Add test_examples and return_schema to your JSON config for best coverage:

{
  "name": "MyAPI_search",
  ...
  "test_examples": [
    {"q": "climate change"},
    {"q": "CRISPR", "limit": 3}
  ],
  "return_schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id":    { "type": "string" },
        "title": { "type": "string" },
        "score": { "type": "number" }
      }
    }
  }
}

tu test validates result["data"] against return_schema. Match the schema type to what your run() returns under the "data" key:

If data is a list: "type": "array"
If data is a dict: "type": "object"

Use with MCP server

Tools in .tooluniverse/tools/ are automatically available when you run:

tu serve          # MCP stdio server (Claude Desktop, etc.)
tooluniverse      # same

The workspace directory is auto-detected in this priority order: --workspace flag → TOOLUNIVERSE_HOME env var → ./.tooluniverse/ (current dir) → ~/.tooluniverse/ (global)

Point to a different tools directory

Add a sources entry in .tooluniverse/profile.yaml:

name: my-profile
sources:
  - ./my-custom-tools/    # relative to profile.yaml location
  - /absolute/path/tools/

Then start with:

tooluniverse --load .tooluniverse/profile.yaml

Option B — Plugin package (shareable, pip-installable)

Use this when you want to distribute tools as a reusable Python package that other users can install with pip install. The plugin package has the same directory layout as a workspace, plus a pyproject.toml that declares the entry point.

Package layout

my_project_root/           # directory containing pyproject.toml
    pyproject.toml
    my_tools_package/      # importable Python package (matches entry-point value)
        __init__.py        # minimal — one-line docstring, no registration code
        my_api_tool.py     # tool class(es) with @register_tool
        data/
            my_api_tools.json  # JSON tool configs (type must match registered class name)
        profile.yaml       # optional: name, description, required_env

JSON config files are discovered from both data/ and the package root directory. The convention is data/.

`pyproject.toml` entry point

[project.entry-points."tooluniverse.plugins"]
my-tools = "my_tools_package"

The value (my_tools_package) must be the importable Python package name.

Python class in a plugin package

Plugin package tools use BaseTool and receive all arguments as a single Dict:

import requests
from typing import Dict, Any
from tooluniverse.base_tool import BaseTool
from tooluniverse.tool_registry import register_tool

@register_tool("MyAPITool")
class MyAPITool(BaseTool):
    """Tool description here."""

    def __init__(self, tool_config: Dict[str, Any]):
        super().__init__(tool_config)
        self.timeout = tool_config.get("timeout", 30)
        fields = tool_config.get("fields", {})
        self.operation = fields.get("operation", "search")

    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
        query = arguments.get("query", "")
        if not query:
            return {"error": "query parameter is required"}
        try:
            resp = requests.get(
                "https://my-api.example.com/search",
                params={"q": query},
                timeout=self.timeout,
            )
            resp.raise_for_status()
            return {"status": "success", "data": resp.json()}
        except requests.exceptions.RequestException as e:
            return {"error": str(e)}

Key differences from the workspace pattern:

Inherit from BaseTool (from tooluniverse.base_tool)
@register_tool("ClassName") takes the class name as a string argument
run(self, arguments: Dict) receives all arguments in a single dict — extract them with .get()
__init__ receives tool_config dict; call super().__init__(tool_config) first

JSON config in a plugin package

Place configs in data/my_api_tools.json. The "type" field must match the string passed to @register_tool(...):

[
  {
    "name": "MyAPI_search",
    "description": "Search my API. Returns matching records.",
    "type": "MyAPITool",
    "fields": { "operation": "search" },
    "parameter": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "Search query" },
        "limit": { "type": ["integer", "null"], "description": "Max results" }
      },
      "required": ["query"]
    }
  }
]

`init.py`

Keep it minimal — no registration code needed. The plugin system imports every .py file in the package directory automatically (via _discover_entry_point_plugins()), so @register_tool decorators fire on their own:

"""My tools plugin for ToolUniverse."""

If you want IDE autocompletion or to make it easy to import specific classes directly, you can add explicit imports — they are harmless because @register_tool is idempotent (registering the same class twice is a no-op):

"""My tools plugin for ToolUniverse."""

from . import my_api_tool       # optional — for IDE support
from . import my_other_tool     # optional

Do not add registration logic, JSON loading, or register_tool_configs() calls here. Those run automatically at plugin discovery time.

Install and verify

# Install in editable mode — path must point to the directory containing pyproject.toml
pip install -e /path/to/my_project_root

# Verify the entry point is registered
python -c "
from importlib.metadata import entry_points
eps = entry_points(group='tooluniverse.plugins')
print([ep.name for ep in eps])
"

# Test the tool — MUST run from the plugin repo directory
cd /path/to/my_project_root
tu test MyAPI_search '{"query": "test"}'

tu test finds plugin tools via the installed entry point — the package must be pip install -e'd first. Always run tu test from the plugin repo directory (not from an arbitrary location): ToolUniverse's workspace auto-detection looks for .tooluniverse/ in the current directory, which is where the plugin's profile.yaml and any workspace-level config lives.

Add test_examples to your JSON config for zero-config testing:

{ "name": "MyAPI_search", ..., "test_examples": [{"query": "test"}] }

Then: tu test MyAPI_search

Note: tu list shows tool counts grouped by category, not individual tool names. To confirm your specific tool loaded, use tu info MyAPI_search or run tu test MyAPI_search directly. If "Tool not found", see the gotcha above about the lazy registry refresh.

Offline / pure-computation tools

Calculator tools that perform local math (no HTTP) follow the plugin-package pattern but skip the HTTP layer entirely. Common designs:

Preset lookup tables

Define named presets at module level as a Dict[str, float], then resolve the parameter with a priority chain: explicit user value → preset name → default. Always include the preset table in metadata so callers can discover valid names without reading source code:

_PACKAGE_THETA_JA = {"sot-23": 200.0, "to-220": 50.0, "bga-256": 20.0}

def run(self, arguments):
    theta = arguments.get("theta_ja")
    if theta is None and arguments.get("package"):
        key = arguments["package"].lower()
        if key not in _PACKAGE_THETA_JA:
            return {"status": "error",
                    "message": f"Unknown package. Known: {list(_PACKAGE_THETA_JA)}"}
        theta = _PACKAGE_THETA_JA[key]
    return {
        "status": "success",
        "data": {"theta_ja": theta, ...},
        "metadata": {"package_presets": _PACKAGE_THETA_JA},
    }

Solving the same equation in both directions

When the same formula can be rearranged to solve for different unknowns, expose them as separate operation values with a single runtime-dispatch tool:

# C_min = I × Δt / ΔV  →  also: ΔV = I × Δt / C
op = arguments.get("operation") or self.operation
if op == "solve_capacitance":
    dV = _req_float(arguments, "voltage_droop_V")
    C_min = I * dt / dV
    ...
elif op == "solve_droop":
    C = _req_float(arguments, "capacitance_F")
    dV = I * dt / C
    ...

The two directions share a single JSON config entry. Use "fields": {"operation": "default_op"} in the JSON to set the default, and document both modes clearly in the description.

Physical constants at module level

Define fundamental constants once, near the top of the file, so they appear in code review and are easy to update:

import math

_MU0   = 4.0 * math.pi * 1e-7   # H/m — permeability of free space
_KB_EV = 8.617333e-5             # eV/K — Boltzmann constant

# Material-specific values as a named dict
_MATERIAL_EA = {"al": 0.7, "cu": 0.9, "w": 1.0}   # activation energy in eV

Multi-output operations

When a single computation naturally yields multiple related results (e.g., Tj AND headroom AND pass/fail), return them all in data rather than forcing a second call:

data = {
    "junction_temp_C":   tj,
    "headroom_C":        tj_max - tj,
    "passes_thermal":    (tj_max - tj) >= 0,
    ...
}

For the complete patterns (significant-figure rounding, _req_float helper, preset resolution), see references/python-tool.md.

tooluniverse-custom-tool