devtu-create-tool

ToolUniverse Tool Creator

Create new scientific tools for the ToolUniverse framework following established best practices.

---

Table of Contents

1. Critical Knowledge
2. Core Concepts
3. Implementation Guide
4. Testing Strategy
5. Common Patterns
6. Troubleshooting
7. Reference

---

Critical Knowledge

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 (NEW #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

Most Common (2026): Mistake #2 affects 60% of new tools. Always make mutually exclusive parameters nullable: {"type": ["string", "null"]}

Tool Creator vs SDK User

SDK User (Using)	Tool Creator (Building)
tu.tools.ToolName()	@register_tool() + JSON
Handle responses	Design schemas
One-level usage	Three-step registration

---

Core Concepts

Two-Stage Architecture

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

Key Points:

• One class handles multiple operations
• JSON defines individual tool wrappers
• Users call wrappers, which route to class
• Need BOTH for tools to work

Three-Step Registration

Step 1: Class Registration

@register_tool("MyAPITool")  # Decorator registers class
class MyAPITool(BaseTool):
    pass