Custom Tools: Build Your Own PocketPaw Extensions

PocketPaw’s tool system is extensible. You can create custom tools by implementing the ToolProtocol.

ToolProtocol Interface

from pocketpaw.tools.registry import ToolProtocol, ToolDefinition

class MyCustomTool:
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return "Does something useful"

    @property
    def definition(self) -> ToolDefinition:
        return ToolDefinition(
            name=self.name,
            description=self.description,
            input_schema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The input query"
                    }
                },
                "required": ["query"]
            }
        )

    async def execute(self, **kwargs) -> str:
        query = kwargs.get("query", "")
        # Your tool logic here
        return f"Result for: {query}"

Registering Custom Tools

from pocketpaw.tools.registry import ToolRegistry

registry = ToolRegistry()
registry.register(MyCustomTool())

Schema Export

ToolDefinition supports exporting to both Anthropic and OpenAI formats:

tool = MyCustomTool()

# Anthropic format
anthropic_schema = tool.definition.to_anthropic()

# OpenAI format
openai_schema = tool.definition.to_openai()

Best Practices

Keep tools focused - Each tool should do one thing well
Validate inputs - Check required parameters before execution
Return strings - Tool results are always strings
Handle errors - Return error messages instead of raising exceptions
Be async - The execute method must be async
Document inputs - Provide clear descriptions in the schema so the LLM knows how to use the tool