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.

bash

mkdir -p .tooluniverse/tools

JSON config

Create

.tooluniverse/tools/my_tools.json

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

python

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

bash

# 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:

python

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):

json

{
  "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:

json

{
  "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:

bash

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

yaml

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

Then start with:

bash

tu serve --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

toml

[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

python

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(...)

json

[
  {
    "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:

python

"""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):

python

"""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

bash

# 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:

json

{ "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:

python

_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:

python

# 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:

python

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:

python

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

NPX Install

Tags

SKILL.md Content

Adding Custom Tools to ToolUniverse

Option A — Workspace tools (local use)

JSON config

Python class

Test workspace tools

Use with MCP server

Point to a different tools directory

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

Package layout

`pyproject.toml`
entry point

Python class in a plugin package

JSON config in a plugin package

`init.py`

Install and verify

Offline / pure-computation tools

Preset lookup tables

Solving the same equation in both directions

Physical constants at module level

Multi-output operations