tool-creator

tool-creator

Overview

AnimaWorks tools are categorized into three types:

Type	Location	Discovery
Core tools	core/tools/*.py	discover_core_tools() → TOOL_MODULES (fixed at startup)
Shared tools	{data_dir}/common_tools/*.py	discover_common_tools()
Personal tools	{anima_dir}/tools/*.py	discover_personal_tools()

{data_dir} is typically ~/.animaworks/. Personal and shared tools are re-scanned by ExternalToolDispatcher via refresh_tools and can be hot-reloaded. ToolHandler checks the tool creation permission in permissions.json when writing to tools/*.py with write_memory_file.

Personal and shared tools are invoked via Bash with animaworks-tool <tool> <subcommand> [args]. Schema name format is {tool_name}_{action} (e.g., my_tool + query → my_tool_query).

Procedure

Step 1: Design the Tool

1. Decide the tool name (snake_case, e.g., my_api_tool)
2. Define the schema(s) (operations) to provide
3. Define required parameters

Step 2: Create the Module File

Create a Python file following the template below.

Single-Schema Tool (Simple)

For file my_tool.py, animaworks-tool my_tool action [args] invokes it; schema name my_tool_action is passed to dispatch.

from __future__ import annotations

import logging
from typing import Any

logger = logging.getLogger("animaworks.tools")


def get_tool_schemas() -> list[dict]:
    """Return tool schema(s) (required)."""
    return [
        {
            "name": "my_tool_action",
            "description": "Description of what this tool does",
            "input_schema": {
                "type": "object",
                "properties": {
                    "param1": {
                        "type": "string",
                        "description": "Parameter description",
                    },
                    "param2": {
                        "type": "integer",
                        "description": "Optional parameter",
                        "default": 10,
                    },
                },
                "required": ["param1"],
            },
        }
    ]


def dispatch(name: str, args: dict[str, Any]) -> Any:
    """Execute handling by schema name (recommended)."""
    args.pop("anima_dir", None)  # Injected by framework; unused in this tool
    if name == "my_tool_action":
        return _do_action(
            param1=args["param1"],
            param2=args.get("param2", 10),
        )
    raise ValueError(f"Unknown tool: {name}")


def _do_action(param1: str, param2: int = 10) -> dict[str, Any]:
    """Actual logic implementation."""
    # Implement here
    return {"result": f"Processed {param1} with {param2}"}