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 .