tool_creation

Tool Creation Guide

This guide covers the four ways to extend InitRunner with tools: built-in tools (contributing to InitRunner itself), custom tools (Python modules), declarative API tools (YAML-only), and the plugin registry (distributable packages).

Built-in Tools

Built-in tools ship with InitRunner. Each one lives in a single file and self-registers using the @register_tool decorator. Use this pattern when contributing a new tool to the InitRunner codebase itself. For external/third-party tools, use Custom Tools or the Plugin Registry instead.

Single-file pattern

A built-in tool is one Python file containing a config class, a builder function, and the @register_tool decorator:

# initrunner/agent/tools/redis.py

from typing import Literal
from pydantic_ai.toolsets.function import FunctionToolset
from initrunner.agent.schema.tools import ToolConfigBase
from initrunner.agent.tools._registry import register_tool, ToolBuildContext


class RedisToolConfig(ToolConfigBase):
    type: Literal["redis"] = "redis"
    host: str = "localhost"
    port: int = 6379

    def summary(self) -> str:
        return f"redis: {self.host}:{self.port}"


@register_tool("redis", RedisToolConfig)
def build_redis_toolset(config: RedisToolConfig, ctx: ToolBuildContext) -> FunctionToolset:
    toolset = FunctionToolset()

    @toolset.tool_plain
    def redis_get(key: str) -> str:
        """Get a value from Redis."""
        import redis
        r = redis.Redis(host=config.host, port=config.port)
        return r.get(key) or ""

    return toolset

The tool is immediately available in role YAML as type: redis — no other files need editing.

Tools use PydanticAI's FunctionToolset under the hood. The @toolset.tool_plain decorator registers individual functions (use @toolset.tool only when the function takes a RunContext as its first parameter), and PydanticAI handles parameter schema generation from type annotations and docstrings.