tooluniverse-custom-tool

# 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](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](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](references/python-tool.md).