pydantic-ai-tool-system

Register tools using @agent.tool decorator for context-aware functions or @agent.tool_plain for plain functions. Both require Google-style docstrings and type annotations. Context-aware tools expose RunContext data including dependencies, model info, usage metrics, and message history for dynamic tool behavior.

PydanticAI tools support multiple return types: strings, dictionaries, Pydantic models, and ToolReturn objects. Choose based on your agent's needs—simple strings for basic responses, Pydantic models for structured data, or ToolReturn for advanced control over tool execution results.

Group registered tools into toolsets for reuse across multiple agents. Toolsets enable dynamic preparation to filter or modify tools per request, allowing you to customize tool availability based on context, request type, or agent requirements without redefining individual tools.

Yes, use the @agent.tool decorator (not @agent.tool_plain) to receive RunContext in your tool function. RunContext exposes dependencies, model information, usage metrics, retry state, and message history, enabling tools to adapt behavior based on request-specific data and agent state.

PydanticAI tools require Google-style or Sphinx-format docstrings. These formats ensure clear tool semantics and are enforced during registration. Proper docstrings help agents understand tool purpose and parameters, improving function-calling reliability and agent decision-making.

Use toolset dynamic preparation to filter or modify tools per request before agent execution. This approach lets you customize tool availability, adjust tool parameters, or exclude tools based on request context, model info, or runtime dependencies without creating separate tool registrations.