Pydantic Ai Tool System

This covers the decorator patterns for registering tools in PydanticAI agents. The key thing to remember is that @agent.tool requires RunContext as the first parameter while @agent.tool_plain doesn't allow it at all. Mix them up and your tools won't work. The skill walks through docstring requirements (the LLM reads these to understand what your tools do), return type handling, and some useful patterns like prepare_tools for filtering capabilities based on user permissions. It's straightforward once you internalize the decorator rules, but the context parameter requirement trips people up initially. Worth referencing when you're adding function calling to agents.

skills.sh installs: 161
GitHub stars: 87
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add existential-birds/beagle --skill pydantic-ai-tool-system --agent claude-code

Installs into .claude/skills of the current project.

Files

PydanticAI Tool System

Tool Registration

Two decorators based on whether you need context:

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o')

# @agent.tool - First param MUST be RunContext
@agent.tool
async def get_user_data(ctx: RunContext[MyDeps], user_id: int) -> str:
    """Get user data from database.

    Args:
        ctx: The run context with dependencies.
        user_id: The user's ID.
    """
    return await ctx.deps.db.get_user(user_id)

# @agent.tool_plain - NO context parameter allowed
@agent.tool_plain
def calculate_total(prices: list[float]) -> float:
    """Calculate total price.

    Args:
        prices: List of prices to sum.
    """
    return sum(prices)