pydantic-ai-tool-system

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)

Critical Rules

1. @agent.tool: First parameter MUST be RunContext[DepsType]
2. @agent.tool_plain: MUST NOT have RunContext parameter
3. Docstrings: Required for LLM to understand tool purpose
4. Google-style docstrings: Used for parameter descriptions

Gates (verify in the file, not from memory)

1. Decorator matches signature — If the first parameter is RunContext[...], the decorator must be @agent.tool (not @agent.tool_plain). Pass: the same def line’s decorator stack includes @agent.tool, and the first parameter is typed RunContext[...].
2. Plain tools — With @agent.tool_plain, the parameter list must not include RunContext. Pass: a quick scan of the signature shows no RunContext.
3. Docstring for the model — Non-empty docstring; if the tool has parameters, describe them (Google Args: or Sphinx :param when using docstring_format='sphinx'). Pass: each parameter in the signature is mentioned in the docstring body.

Docstring Formats

Google style (default):

@agent.tool_plain
async def search(query: str, limit: int = 10) -> list[str]:
    """Search for items.

    Args:
        query: The search query.
        limit: Maximum results to return.
    """

Sphinx style:

@agent.tool_plain(docstring_format='sphinx')
async def search(query: str) -> list[str]:
    """Search for items.

    :param query: The search query.
    """