Pydantic Ai Tool System

Register and implement PydanticAI tools with proper context handling, type annotations, and docstrings. Use when adding tool capabilities to agents, implemen...

Security Scan

This is an instruction-only skill that documents how to register PydanticAI tools; its requirements and instructions are internally consistent and proportional to that purpose.

Purpose & Capability

The name/description (registering and implementing PydanticAI tools) matches the SKILL.md content: decorators, RunContext usage, docstring conventions, return types, and examples. The skill does not request unrelated binaries, env vars, or config paths.

Instruction Scope

The instructions are focused on how to define tools and use RunContext; they do not instruct the agent to read arbitrary host files, export data to external endpoints, or access environment variables beyond the normal ctx.deps usage. Examples reference db and api clients via ctx.deps, which is expected for tool implementations.

Install Mechanism

No install spec or code files—this is instruction-only so nothing is written to disk or downloaded. Low installation risk.

Credentials

The skill declares no required environment variables, credentials, or config paths. The doc instructs use of ctx.deps for dependencies (DB, API clients) which is appropriate for tool implementations; those dependencies are provided by the host runtime, not requested by this skill.

Persistence & Privilege

always:false and default autonomous invocation are fine for this kind of skill. The skill does not request permanent presence or attempt to modify other skills or system-wide settings.

Assessment

This SKILL.md is documentation for how to implement PydanticAI tools and is internally consistent. It does not itself request credentials or perform installs. Before using it in an agent: (1) confirm the runtime's ctx.deps values (DB clients, API clients, user_role, etc.) are limited to the minimum necessary and do not expose unrelated secrets; (2) review any actual tool code you or others add (tools execute in the agent runtime and can use ctx.deps to access services); and (3) ensure the pydantic_ai library implementation you depend on comes from a trusted source. If you want, provide the agent runtime or any tool code to evaluate whether those specific implementations introduce additional risks.

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

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.
    """

Tool Return Types

Tools can return various types:

# String (direct)
@agent.tool_plain
def get_info() -> str:
    return "Some information"

# Pydantic model (serialized to JSON)
@agent.tool_plain
def get_user() -> User:
    return User(name="John", age=30)

# Dict (serialized to JSON)
@agent.tool_plain
def get_data() -> dict[str, Any]:
    return {"key": "value"}

# ToolReturn for custom content types
from pydantic_ai import ToolReturn, ImageUrl

@agent.tool_plain
def get_image() -> ToolReturn:
    return ToolReturn(content=[ImageUrl(url="https://...")])

Accessing Context

RunContext provides:

@agent.tool
async def my_tool(ctx: RunContext[MyDeps]) -> str:
    # Dependencies
    db = ctx.deps.db
    api = ctx.deps.api_client

    # Model info
    model_name = ctx.model.model_name

    # Usage tracking
    tokens_used = ctx.usage.total_tokens

    # Retry info
    attempt = ctx.retry  # Current retry attempt (0-based)
    max_retries = ctx.max_retries

    # Message history
    messages = ctx.messages

    return "result"

Tool Prepare Functions

Dynamically modify tools per-request:

from pydantic_ai.tools import ToolDefinition

async def prepare_tools(
    ctx: RunContext[MyDeps],
    tool_defs: list[ToolDefinition]
) -> list[ToolDefinition]:
    """Filter or modify tools based on context."""
    if ctx.deps.user_role != 'admin':
        # Hide admin tools from non-admins
        return [t for t in tool_defs if not t.name.startswith('admin_')]
    return tool_defs

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

Toolsets

Group and compose tools:

from pydantic_ai import FunctionToolset, CombinedToolset

# Create a toolset
db_tools = FunctionToolset()

@db_tools.tool
def query_users(name: str) -> list[dict]:
    """Query users by name."""
    ...

@db_tools.tool
def update_user(id: int, data: dict) -> bool:
    """Update user data."""
    ...

# Use in agent
agent = Agent('openai:gpt-4o', toolsets=[db_tools])

# Combine toolsets
all_tools = CombinedToolset([db_tools, api_tools])

Common Mistakes

Wrong: Context in tool_plain

@agent.tool_plain
async def bad_tool(ctx: RunContext[MyDeps]) -> str:  # ERROR!
    ...

Wrong: Missing context in tool

@agent.tool
def bad_tool(user_id: int) -> str:  # ERROR!
    ...

Wrong: Context not first parameter

@agent.tool
def bad_tool(user_id: int, ctx: RunContext[MyDeps]) -> str:  # ERROR!
    ...

Async vs Sync

Both work, but async is preferred for I/O:

# Async (preferred for I/O operations)
@agent.tool
async def fetch_data(ctx: RunContext[Deps]) -> str:
    return await ctx.deps.client.get('/data')

# Sync (fine for CPU-bound operations)
@agent.tool_plain
def compute(x: int, y: int) -> int:
    return x * y