devtu-create-tool

ToolUniverse Tool Creator

Create new scientific tools following established patterns.

Top 7 Mistakes (90% of Failures)

1. Missing default_config.py Entry — tools silently won't load
2. Non-nullable Mutually Exclusive Parameters — validation errors (#1 issue in 2026)
3. Fake test_examples — tests fail, agents get bad examples
4. Single-level Testing — misses registration bugs
5. Skipping test_new_tools.py — misses schema/API issues
6. Tool Names > 55 chars — breaks MCP compatibility
7. Raising Exceptions — should return error dicts instead

Two-Stage Architecture

Stage 1: Tool Class              Stage 2: Wrappers (Auto-Generated)
@register_tool("MyTool")         MyAPI_list_items()
class MyTool(BaseTool):          MyAPI_search()
    def run(arguments):          MyAPI_get_details()

One class handles multiple operations. JSON defines individual wrappers. Need BOTH.

Three-Step Registration

Step 1: Class registration via @register_tool("MyAPITool")

Step 2 (MOST COMMONLY MISSED): Config registration in default_config.py:

TOOLS_CONFIGS = {
    "my_category": os.path.join(current_dir, "data", "my_category_tools.json"),
}

Step 3: Automatic wrapper generation on tu.load_tools()

Implementation Guide

Files to Create

• src/tooluniverse/my_api_tool.py — implementation
• src/tooluniverse/data/my_api_tools.json — tool definitions
• tests/tools/test_my_api_tool.py — tests

Python Tool Class (Multi-Operation Pattern)

from typing import Dict, Any
from tooluniverse.tool import BaseTool
from tooluniverse.tool_utils import register_tool
import requests

@register_tool("MyAPITool")
class MyAPITool(BaseTool):
    BASE_URL = "https://api.example.com/v1"

    def __init__(self, tool_config):
        super().__init__(tool_config)
        self.parameter = tool_config.get("parameter", {})
        self.required = self.parameter.get("required", [])

    def run(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
        operation = arguments.get("operation")
        if not operation:
            return {"status": "error", "error": "Missing: operation"}
        if operation == "search":
            return self._search(arguments)
        return {"status": "error", "error": f"Unknown: {operation}"}

    def _search(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
        query = arguments.get("query")
        if not query:
            return {"status": "error", "error": "Missing: query"}
        try:
            response = requests.get(
                f"{self.BASE_URL}/search",
                params={"q": query}, timeout=30
            )
            response.raise_for_status()
            data = response.json()
            return {"status": "success", "data": data.get("results", [])}
        except requests.exceptions.Timeout:
            return {"status": "error", "error": "Timeout after 30s"}
        except requests.exceptions.HTTPError as e:
            return {"status": "error", "error": f"HTTP {e.response.status_code}"}
        except Exception as e:
            return {"status": "error", "error": str(e)}