🛠️ Custom Tools Development

HelseCLI is designed to be highly extensible. You can add new capabilities to the AI by creating and registering custom tools.

🏗️ Tool Structure

All tools in HelseCLI inherit from a base BaseTool class and follow a strict schema-driven approach.

1. Create the Tool Class

Create a new file in src/tools/ or custom_tools/.

from src.tools.base import BaseTool
from typing import Dict, Any

class MyCustomTool(BaseTool):
    def __init__(self):
        super().__init__(
            name="my_custom_tool",
            description="Explain what this tool does clearly so the AI knows when to use it.",
            parameters={
                "type": "object",
                "properties": {
                    "input_text": {
                        "type": "string",
                        "description": "The text to process."
                    }
                },
                "required": ["input_text"]
            }
        )

    async def execute(self, **kwargs) -> Dict[str, Any]:
        input_text = kwargs.get("input_text")
        # Your logic here
        result = f"Processed: {input_text}"
        return {"status": "success", "output": result}

2. Registration

Add your tool to the registry.py file:

from src.tools.my_custom_tool import MyCustomTool

# Inside the Registry class
self.register_tool(MyCustomTool())

💡 Best Practices for Tool Design

1. Descriptive Name: Use snake_case. The name should be a verb-noun pair (e.g., calculate_metrics, fetch_latest_logs).
2. Clear Description: This is what the AI uses to decide if it should call the tool. Be specific about inputs and outputs.
3. Robust Error Handling: Always return a dictionary with a status key. If it fails, provide a clear error message in the output so the AI can troubleshoot.
4. Asynchronous: Use async def execute to ensure the CLI remains responsive.

🛡️ Tool Safety

If your tool performs destructive operations (e.g., deleting a database table), ensure it is marked as destructive=True in the constructor. HelseCLI will then force a user confirmation even in Agent Mode (unless !build is active).

🧪 Testing Your Tool

Use a simple script to test your tool in isolation before letting the AI use it:

import asyncio
from src.tools.my_custom_tool import MyCustomTool

async def test():
    tool = MyCustomTool()
    result = await tool.execute(input_text="Hello Helse")
    print(result)

if __name__ == "__main__":
    asyncio.run(test())