Building Tools with Supypowers

Tools are the bridge between your agent and the real world. Every tool is a Python script in powers/ that follows the supypower contract: a function that takes a Pydantic input model and returns structured data.

The Supypower Contract

# /// script
# dependencies = ["httpx"]
# ///
"""My custom tool."""

from pydantic import BaseModel, Field

class MyInput(BaseModel):
    """Tool description shown to the LLM."""
    query: str = Field(description="What to process")

def my_function(input: MyInput):
    """Process the query and return results."""
    return {"result": f"Processed: {input.query}"}

Rules:

1. Every function takes exactly one input parameter typed as a BaseModel
2. Dependencies go in the # /// script header — isolated per-script via uv
3. No print() (breaks JSON output), no input() (no interactive terminal)
4. Return a dict or Pydantic model — serialized to JSON automatically

Tool Output Format

All tool results follow a consistent format:

{"ok": true, "data": {"result": "Processed: hello"}}

Or on error:

{"ok": false, "error": "Something went wrong"}

In This Section

• Creating Tools — Step-by-step guide to building tools
• Dependencies — Per-script dependency isolation
• Testing — Test tools before giving them to agents
• Publishing — Share tools across projects
• Examples — Annotated example tools
• Built-in Tools — Reference for all default tools