Tools API

Core tools register with tools.registry.registry. Plugin tools should use the plugin context instead.

Handler contract

Handlers receive parsed arguments and keyword context. They must return a JSON string.

import json
from tools.registry import registry

def example_tool(param: str, task_id: str | None = None) -> str:
    return json.dumps({"success": True, "param": param})

registry.register(
    name="example_tool",
    toolset="example",
    schema={
        "name": "example_tool",
        "description": "Example tool.",
        "parameters": {
            "type": "object",
            "properties": {
                "param": {"type": "string"}
            }
        }
    },
    handler=lambda args, **kw: example_tool(
        param=args.get("param", ""),
        task_id=kw.get("task_id"),
    ),
)

State and paths

Use get_arcen_home() for persistent state and display_arcen_home() for user-facing path text in schemas.

Exposure

Registration makes the tool known. Toolset membership makes it available to agents.

Add core tools to _ARCEN_CORE_TOOLS or an explicit toolset in toolsets.py.