[ Skip to content ](https://ai.pydantic.dev/api/tools/#pydantic_aitools)
**Join us at the inaugural PyAI Conf in San Francisco on March 10th![Learn More](https://pyai.events/?utm_source=pydantic-ai) **
[ ![logo](https://ai.pydantic.dev/img/logo-white.svg) ](https://ai.pydantic.dev/ "Pydantic AI")
Pydantic AI
pydantic_ai.tools
Type to start searching
[ pydantic/pydantic-ai
  * v1.63.0
  * 15.1k
  * 1.7k

](https://github.com/pydantic/pydantic-ai "Go to repository")
[ ![logo](https://ai.pydantic.dev/img/logo-white.svg) ](https://ai.pydantic.dev/ "Pydantic AI") Pydantic AI
[ pydantic/pydantic-ai
  * v1.63.0
  * 15.1k
  * 1.7k

](https://github.com/pydantic/pydantic-ai "Go to repository")
  * [ Pydantic AI  ](https://ai.pydantic.dev/)
  * [ Installation  ](https://ai.pydantic.dev/install/)
  * [ Getting Help  ](https://ai.pydantic.dev/help/)
  * [ Troubleshooting  ](https://ai.pydantic.dev/troubleshooting/)
  * [ Pydantic AI Gateway  ](https://ai.pydantic.dev/gateway/)
  * Documentation
    * Core Concepts
      * [ Agents  ](https://ai.pydantic.dev/agent/)
      * [ Dependencies  ](https://ai.pydantic.dev/dependencies/)
      * [ Function Tools  ](https://ai.pydantic.dev/tools/)
      * [ Output  ](https://ai.pydantic.dev/output/)
      * [ Messages and chat history  ](https://ai.pydantic.dev/message-history/)
      * [ Direct Model Requests  ](https://ai.pydantic.dev/direct/)
    * Models & Providers
      * [ Overview  ](https://ai.pydantic.dev/models/overview/)
      * [ OpenAI  ](https://ai.pydantic.dev/models/openai/)
      * [ Anthropic  ](https://ai.pydantic.dev/models/anthropic/)
      * [ Google  ](https://ai.pydantic.dev/models/google/)
      * [ xAI  ](https://ai.pydantic.dev/models/xai/)
      * [ Bedrock  ](https://ai.pydantic.dev/models/bedrock/)
      * [ Cerebras  ](https://ai.pydantic.dev/models/cerebras/)
      * [ Cohere  ](https://ai.pydantic.dev/models/cohere/)
      * [ Groq  ](https://ai.pydantic.dev/models/groq/)
      * [ Hugging Face  ](https://ai.pydantic.dev/models/huggingface/)
      * [ Mistral  ](https://ai.pydantic.dev/models/mistral/)
      * [ OpenRouter  ](https://ai.pydantic.dev/models/openrouter/)
      * [ Outlines  ](https://ai.pydantic.dev/models/outlines/)
    * Tools & Toolsets
      * [ Function Tools  ](https://ai.pydantic.dev/tools/)
      * [ Advanced Tool Features  ](https://ai.pydantic.dev/tools-advanced/)
      * [ Toolsets  ](https://ai.pydantic.dev/toolsets/)
      * [ Deferred Tools  ](https://ai.pydantic.dev/deferred-tools/)
      * [ Built-in Tools  ](https://ai.pydantic.dev/builtin-tools/)
      * [ Common Tools  ](https://ai.pydantic.dev/common-tools/)
      * [ Third-Party Tools  ](https://ai.pydantic.dev/third-party-tools/)
    * Advanced Features
      * [ Image, Audio, Video & Document Input  ](https://ai.pydantic.dev/input/)
      * [ Thinking  ](https://ai.pydantic.dev/thinking/)
      * [ HTTP Request Retries  ](https://ai.pydantic.dev/retries/)
    * MCP
      * [ Overview  ](https://ai.pydantic.dev/mcp/overview/)
      * [ Client  ](https://ai.pydantic.dev/mcp/client/)
      * [ FastMCP Client  ](https://ai.pydantic.dev/mcp/fastmcp-client/)
      * [ Server  ](https://ai.pydantic.dev/mcp/server/)
    * [ Multi-Agent Patterns  ](https://ai.pydantic.dev/multi-agent-applications/)
    * [ Web Chat UI  ](https://ai.pydantic.dev/web/)
    * [ Embeddings  ](https://ai.pydantic.dev/embeddings/)
    * [ Testing  ](https://ai.pydantic.dev/testing/)
  * Pydantic Evals
    * [ Overview  ](https://ai.pydantic.dev/evals/)
    * Getting Started
      * [ Quick Start  ](https://ai.pydantic.dev/evals/quick-start/)
      * [ Core Concepts  ](https://ai.pydantic.dev/evals/core-concepts/)
    * Evaluators
      * [ Overview  ](https://ai.pydantic.dev/evals/evaluators/overview/)
      * [ Built-in Evaluators  ](https://ai.pydantic.dev/evals/evaluators/built-in/)
      * [ LLM Judge  ](https://ai.pydantic.dev/evals/evaluators/llm-judge/)
      * [ Custom Evaluators  ](https://ai.pydantic.dev/evals/evaluators/custom/)
      * [ Report Evaluators  ](https://ai.pydantic.dev/evals/evaluators/report-evaluators/)
      * [ Span-Based  ](https://ai.pydantic.dev/evals/evaluators/span-based/)
    * How-To Guides
      * [ Logfire Integration  ](https://ai.pydantic.dev/evals/how-to/logfire-integration/)
      * [ Dataset Management  ](https://ai.pydantic.dev/evals/how-to/dataset-management/)
      * [ Dataset Serialization  ](https://ai.pydantic.dev/evals/how-to/dataset-serialization/)
      * [ Concurrency & Performance  ](https://ai.pydantic.dev/evals/how-to/concurrency/)
      * [ Multi-Run Evaluation  ](https://ai.pydantic.dev/evals/how-to/multi-run/)
      * [ Retry Strategies  ](https://ai.pydantic.dev/evals/how-to/retry-strategies/)
      * [ Metrics & Attributes  ](https://ai.pydantic.dev/evals/how-to/metrics-attributes/)
    * Examples
      * [ Simple Validation  ](https://ai.pydantic.dev/evals/examples/simple-validation/)
  * Pydantic Graph
    * [ Overview  ](https://ai.pydantic.dev/graph/)
    * [ Beta API  ](https://ai.pydantic.dev/graph/beta/)
      * [ Steps  ](https://ai.pydantic.dev/graph/beta/steps/)
      * [ Joins & Reducers  ](https://ai.pydantic.dev/graph/beta/joins/)
      * [ Decisions  ](https://ai.pydantic.dev/graph/beta/decisions/)
      * [ Parallel Execution  ](https://ai.pydantic.dev/graph/beta/parallel/)
  * Integrations
    * [ Debugging & Monitoring with Pydantic Logfire  ](https://ai.pydantic.dev/logfire/)
    * Durable Execution
      * [ Overview  ](https://ai.pydantic.dev/durable_execution/overview/)
      * [ Temporal  ](https://ai.pydantic.dev/durable_execution/temporal/)
      * [ DBOS  ](https://ai.pydantic.dev/durable_execution/dbos/)
      * [ Prefect  ](https://ai.pydantic.dev/durable_execution/prefect/)
    * UI Event Streams
      * [ Overview  ](https://ai.pydantic.dev/ui/overview/)
      * [ AG-UI  ](https://ai.pydantic.dev/ui/ag-ui/)
      * [ Vercel AI  ](https://ai.pydantic.dev/ui/vercel-ai/)
    * [ Agent2Agent (A2A)  ](https://ai.pydantic.dev/a2a/)
  * Related Packages
    * [ clai  ](https://ai.pydantic.dev/cli/)
  * Examples
    * [ Setup  ](https://ai.pydantic.dev/examples/setup/)
    * Getting Started
      * [ Pydantic Model  ](https://ai.pydantic.dev/examples/pydantic-model/)
      * [ Weather agent  ](https://ai.pydantic.dev/examples/weather-agent/)
    * Conversational Agents
      * [ Chat App with FastAPI  ](https://ai.pydantic.dev/examples/chat-app/)
      * [ Bank support  ](https://ai.pydantic.dev/examples/bank-support/)
    * Data & Analytics
      * [ SQL Generation  ](https://ai.pydantic.dev/examples/sql-gen/)
      * [ Data Analyst  ](https://ai.pydantic.dev/examples/data-analyst/)
      * [ RAG  ](https://ai.pydantic.dev/examples/rag/)
    * Streaming
      * [ Stream markdown  ](https://ai.pydantic.dev/examples/stream-markdown/)
      * [ Stream whales  ](https://ai.pydantic.dev/examples/stream-whales/)
    * Complex Workflows
      * [ Flight booking  ](https://ai.pydantic.dev/examples/flight-booking/)
      * [ Question Graph  ](https://ai.pydantic.dev/examples/question-graph/)
    * Business Applications
      * [ Slack Lead Qualifier with Modal  ](https://ai.pydantic.dev/examples/slack-lead-qualifier/)
    * UI Examples
      * [ Agent User Interaction (AG-UI)  ](https://ai.pydantic.dev/examples/ag-ui/)
  * API Reference
    * pydantic_ai
      * [ pydantic_ai.ag_ui  ](https://ai.pydantic.dev/api/ag_ui/)
      * [ pydantic_ai.agent  ](https://ai.pydantic.dev/api/agent/)
      * [ pydantic_ai.builtin_tools  ](https://ai.pydantic.dev/api/builtin_tools/)
      * [ pydantic_ai.common_tools  ](https://ai.pydantic.dev/api/common_tools/)
      * [ pydantic_ai — Concurrency  ](https://ai.pydantic.dev/api/concurrency/)
      * [ pydantic_ai.direct  ](https://ai.pydantic.dev/api/direct/)
      * [ pydantic_ai.durable_exec  ](https://ai.pydantic.dev/api/durable_exec/)
      * [ pydantic_ai.embeddings  ](https://ai.pydantic.dev/api/embeddings/)
      * [ pydantic_ai.exceptions  ](https://ai.pydantic.dev/api/exceptions/)
      * [ pydantic_ai.ext  ](https://ai.pydantic.dev/api/ext/)
      * [ pydantic_ai.format_prompt  ](https://ai.pydantic.dev/api/format_prompt/)
      * [ pydantic_ai.mcp  ](https://ai.pydantic.dev/api/mcp/)
      * [ pydantic_ai.messages  ](https://ai.pydantic.dev/api/messages/)
      * [ pydantic_ai.models.anthropic  ](https://ai.pydantic.dev/api/models/anthropic/)
      * [ pydantic_ai.models  ](https://ai.pydantic.dev/api/models/base/)
      * [ pydantic_ai.models.bedrock  ](https://ai.pydantic.dev/api/models/bedrock/)
      * [ pydantic_ai.models.cerebras  ](https://ai.pydantic.dev/api/models/cerebras/)
      * [ pydantic_ai.models.cohere  ](https://ai.pydantic.dev/api/models/cohere/)
      * [ pydantic_ai.models.fallback  ](https://ai.pydantic.dev/api/models/fallback/)
      * [ pydantic_ai.models.function  ](https://ai.pydantic.dev/api/models/function/)
      * [ pydantic_ai.models.google  ](https://ai.pydantic.dev/api/models/google/)
      * [ pydantic_ai.models.xai  ](https://ai.pydantic.dev/api/models/xai/)
      * [ pydantic_ai.models.groq  ](https://ai.pydantic.dev/api/models/groq/)
      * [ pydantic_ai.models.huggingface  ](https://ai.pydantic.dev/api/models/huggingface/)
      * [ pydantic_ai.models.instrumented  ](https://ai.pydantic.dev/api/models/instrumented/)
      * [ pydantic_ai.models.mcp_sampling  ](https://ai.pydantic.dev/api/models/mcp-sampling/)
      * [ pydantic_ai.models.mistral  ](https://ai.pydantic.dev/api/models/mistral/)
      * [ pydantic_ai.models.openai  ](https://ai.pydantic.dev/api/models/openai/)
      * [ pydantic_ai.models.openrouter  ](https://ai.pydantic.dev/api/models/openrouter/)
      * [ pydantic_ai.models.outlines  ](https://ai.pydantic.dev/api/models/outlines/)
      * [ pydantic_ai.models.test  ](https://ai.pydantic.dev/api/models/test/)
      * [ pydantic_ai.models.wrapper  ](https://ai.pydantic.dev/api/models/wrapper/)
      * [ pydantic_ai.output  ](https://ai.pydantic.dev/api/output/)
      * [ pydantic_ai.profiles  ](https://ai.pydantic.dev/api/profiles/)
      * [ pydantic_ai.providers  ](https://ai.pydantic.dev/api/providers/)
      * [ pydantic_ai.result  ](https://ai.pydantic.dev/api/result/)
      * [ pydantic_ai.retries  ](https://ai.pydantic.dev/api/retries/)
      * [ pydantic_ai.run  ](https://ai.pydantic.dev/api/run/)
      * [ pydantic_ai.settings  ](https://ai.pydantic.dev/api/settings/)
      * pydantic_ai.tools  [ pydantic_ai.tools  ](https://ai.pydantic.dev/api/tools/)
        * [ tools  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools)
        * [ AgentDepsT  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT)
        * [ RunContext  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext)
          * [ deps  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.deps)
          * [ model  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.model)
          * [ usage  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.usage)
          * [ prompt  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.prompt)
          * [ messages  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.messages)
          * [ validation_context  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.validation_context)
          * [ tracer  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tracer)
          * [ trace_include_content  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.trace_include_content)
          * [ instrumentation_version  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.instrumentation_version)
          * [ retries  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.retries)
          * [ tool_call_id  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_call_id)
          * [ tool_name  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_name)
          * [ retry  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.retry)
          * [ max_retries  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.max_retries)
          * [ run_step  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.run_step)
          * [ tool_call_approved  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_call_approved)
          * [ tool_call_metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_call_metadata)
          * [ partial_output  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.partial_output)
          * [ run_id  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.run_id)
          * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.metadata)
          * [ last_attempt  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.last_attempt)
        * [ ToolParams  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams)
        * [ SystemPromptFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.SystemPromptFunc)
        * [ ToolFuncContext  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncContext)
        * [ ToolFuncPlain  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncPlain)
        * [ ToolFuncEither  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncEither)
        * [ ArgsValidatorFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc)
        * [ ToolPrepareFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolPrepareFunc)
        * [ ToolsPrepareFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolsPrepareFunc)
        * [ BuiltinToolFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.BuiltinToolFunc)
        * [ DocstringFormat  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DocstringFormat)
        * [ DeferredToolRequests  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests)
          * [ calls  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests.calls)
          * [ approvals  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests.approvals)
          * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests.metadata)
        * [ ToolApproved  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolApproved)
          * [ override_args  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolApproved.override_args)
        * [ ToolDenied  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDenied)
          * [ message  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDenied.message)
        * [ DeferredToolApprovalResult  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolApprovalResult)
        * [ DeferredToolCallResult  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolCallResult)
        * [ DeferredToolResult  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResult)
        * [ DeferredToolResults  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults)
          * [ calls  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults.calls)
          * [ approvals  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults.approvals)
          * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults.metadata)
        * [ ToolAgentDepsT  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT)
        * [ Tool  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool)
          * [ __init__  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.__init__)
          * [ function_schema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.function_schema)
          * [ from_schema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.from_schema)
          * [ prepare_tool_def  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.prepare_tool_def)
        * [ ObjectJsonSchema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ObjectJsonSchema)
        * [ ToolKind  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolKind)
        * [ ToolDefinition  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition)
          * [ name  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.name)
          * [ parameters_json_schema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.parameters_json_schema)
          * [ description  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.description)
          * [ outer_typed_dict_key  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.outer_typed_dict_key)
          * [ strict  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.strict)
          * [ sequential  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.sequential)
          * [ kind  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.kind)
          * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.metadata)
          * [ timeout  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.timeout)
          * [ defer  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.defer)
      * [ pydantic_ai.toolsets  ](https://ai.pydantic.dev/api/toolsets/)
      * [ pydantic_ai.ui.ag_ui  ](https://ai.pydantic.dev/api/ui/ag_ui/)
      * [ pydantic_ai.ui  ](https://ai.pydantic.dev/api/ui/base/)
      * [ pydantic_ai.ui.vercel_ai  ](https://ai.pydantic.dev/api/ui/vercel_ai/)
      * [ pydantic_ai.usage  ](https://ai.pydantic.dev/api/usage/)
    * pydantic_evals
      * [ pydantic_evals.dataset  ](https://ai.pydantic.dev/api/pydantic_evals/dataset/)
      * [ pydantic_evals.evaluators  ](https://ai.pydantic.dev/api/pydantic_evals/evaluators/)
      * [ pydantic_evals.reporting  ](https://ai.pydantic.dev/api/pydantic_evals/reporting/)
      * [ pydantic_evals.otel  ](https://ai.pydantic.dev/api/pydantic_evals/otel/)
      * [ pydantic_evals.generation  ](https://ai.pydantic.dev/api/pydantic_evals/generation/)
    * pydantic_graph
      * [ pydantic_graph  ](https://ai.pydantic.dev/api/pydantic_graph/graph/)
      * [ pydantic_graph.nodes  ](https://ai.pydantic.dev/api/pydantic_graph/nodes/)
      * [ pydantic_graph.persistence  ](https://ai.pydantic.dev/api/pydantic_graph/persistence/)
      * [ pydantic_graph.mermaid  ](https://ai.pydantic.dev/api/pydantic_graph/mermaid/)
      * [ pydantic_graph.exceptions  ](https://ai.pydantic.dev/api/pydantic_graph/exceptions/)
      * Beta API
        * [ pydantic_graph.beta  ](https://ai.pydantic.dev/api/pydantic_graph/beta/)
        * [ pydantic_graph.beta.graph  ](https://ai.pydantic.dev/api/pydantic_graph/beta_graph/)
        * [ pydantic_graph.beta.graph_builder  ](https://ai.pydantic.dev/api/pydantic_graph/beta_graph_builder/)
        * [ pydantic_graph.beta.step  ](https://ai.pydantic.dev/api/pydantic_graph/beta_step/)
        * [ pydantic_graph.beta.join  ](https://ai.pydantic.dev/api/pydantic_graph/beta_join/)
        * [ pydantic_graph.beta.decision  ](https://ai.pydantic.dev/api/pydantic_graph/beta_decision/)
        * [ pydantic_graph.beta.node  ](https://ai.pydantic.dev/api/pydantic_graph/beta_node/)
    * fasta2a
      * [ fasta2a  ](https://ai.pydantic.dev/api/fasta2a/)
  * Project
    * [ Contributing  ](https://ai.pydantic.dev/contributing/)
    * [ Upgrade Guide  ](https://ai.pydantic.dev/changelog/)
    * [ Version policy  ](https://ai.pydantic.dev/version-policy/)


  * [ tools  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools)
  * [ AgentDepsT  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT)
  * [ RunContext  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext)
    * [ deps  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.deps)
    * [ model  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.model)
    * [ usage  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.usage)
    * [ prompt  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.prompt)
    * [ messages  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.messages)
    * [ validation_context  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.validation_context)
    * [ tracer  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tracer)
    * [ trace_include_content  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.trace_include_content)
    * [ instrumentation_version  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.instrumentation_version)
    * [ retries  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.retries)
    * [ tool_call_id  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_call_id)
    * [ tool_name  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_name)
    * [ retry  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.retry)
    * [ max_retries  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.max_retries)
    * [ run_step  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.run_step)
    * [ tool_call_approved  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_call_approved)
    * [ tool_call_metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.tool_call_metadata)
    * [ partial_output  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.partial_output)
    * [ run_id  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.run_id)
    * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.metadata)
    * [ last_attempt  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext.last_attempt)
  * [ ToolParams  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams)
  * [ SystemPromptFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.SystemPromptFunc)
  * [ ToolFuncContext  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncContext)
  * [ ToolFuncPlain  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncPlain)
  * [ ToolFuncEither  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncEither)
  * [ ArgsValidatorFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc)
  * [ ToolPrepareFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolPrepareFunc)
  * [ ToolsPrepareFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolsPrepareFunc)
  * [ BuiltinToolFunc  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.BuiltinToolFunc)
  * [ DocstringFormat  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DocstringFormat)
  * [ DeferredToolRequests  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests)
    * [ calls  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests.calls)
    * [ approvals  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests.approvals)
    * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolRequests.metadata)
  * [ ToolApproved  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolApproved)
    * [ override_args  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolApproved.override_args)
  * [ ToolDenied  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDenied)
    * [ message  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDenied.message)
  * [ DeferredToolApprovalResult  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolApprovalResult)
  * [ DeferredToolCallResult  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolCallResult)
  * [ DeferredToolResult  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResult)
  * [ DeferredToolResults  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults)
    * [ calls  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults.calls)
    * [ approvals  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults.approvals)
    * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults.metadata)
  * [ ToolAgentDepsT  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT)
  * [ Tool  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool)
    * [ __init__  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.__init__)
    * [ function_schema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.function_schema)
    * [ from_schema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.from_schema)
    * [ prepare_tool_def  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.Tool.prepare_tool_def)
  * [ ObjectJsonSchema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ObjectJsonSchema)
  * [ ToolKind  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolKind)
  * [ ToolDefinition  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition)
    * [ name  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.name)
    * [ parameters_json_schema  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.parameters_json_schema)
    * [ description  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.description)
    * [ outer_typed_dict_key  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.outer_typed_dict_key)
    * [ strict  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.strict)
    * [ sequential  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.sequential)
    * [ kind  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.kind)
    * [ metadata  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.metadata)
    * [ timeout  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.timeout)
    * [ defer  ](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition.defer)


  1. [ Pydantic AI  ](https://ai.pydantic.dev/)
  2. [ API Reference  ](https://ai.pydantic.dev/api/ag_ui/)
  3. [ pydantic_ai  ](https://ai.pydantic.dev/api/ag_ui/)


# `pydantic_ai.tools`
###  AgentDepsT `module-attribute`
```
AgentDepsT = TypeVar(
    "AgentDepsT", default=None, contravariant=True
)

```

Type variable for agent dependencies.
###  RunContext `dataclass`
Bases: `Generic[](https://docs.python.org/3/library/typing.html#typing.Generic "typing.Generic")[RunContextAgentDepsT]`
Information about the current call.
Source code in `pydantic_ai_slim/pydantic_ai/_run_context.py`
```
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
```
| ```
@dataclasses.dataclass(repr=False, kw_only=True)
class RunContext(Generic[RunContextAgentDepsT]):
    """Information about the current call."""

    deps: RunContextAgentDepsT
    """Dependencies for the agent."""
    model: Model
    """The model used in this run."""
    usage: RunUsage
    """LLM usage associated with the run."""
    prompt: str | Sequence[_messages.UserContent] | None = None
    """The original user prompt passed to the run."""
    messages: list[_messages.ModelMessage] = field(default_factory=list[_messages.ModelMessage])
    """Messages exchanged in the conversation so far."""
    validation_context: Any = None
    """Pydantic [validation context](https://docs.pydantic.dev/latest/concepts/validators/#validation-context) for tool args and run outputs."""
    tracer: Tracer = field(default_factory=NoOpTracer)
    """The tracer to use for tracing the run."""
    trace_include_content: bool = False
    """Whether to include the content of the messages in the trace."""
    instrumentation_version: int = DEFAULT_INSTRUMENTATION_VERSION
    """Instrumentation settings version, if instrumentation is enabled."""
    retries: dict[str, int] = field(default_factory=dict[str, int])
    """Number of retries for each tool so far."""
    tool_call_id: str | None = None
    """The ID of the tool call."""
    tool_name: str | None = None
    """Name of the tool being called."""
    retry: int = 0
    """Number of retries so far.

    For tool calls, this is the number of retries of the specific tool.
    For output validation, this is the number of output validation retries.
    """
    max_retries: int = 0
    """The maximum number of retries allowed.

    For tool calls, this is the maximum retries for the specific tool.
    For output validation, this is the maximum output validation retries.
    """
    run_step: int = 0
    """The current step in the run."""
    tool_call_approved: bool = False
    """Whether a tool call that required approval has now been approved."""
    tool_call_metadata: Any = None
    """Metadata from `DeferredToolResults.metadata[tool_call_id]`, available when `tool_call_approved=True`."""
    partial_output: bool = False
    """Whether the output passed to an output validator is partial."""
    run_id: str | None = None
    """"Unique identifier for the agent run."""
    metadata: dict[str, Any] | None = None
    """Metadata associated with this agent run, if configured."""

    @property
    def last_attempt(self) -> bool:
        """Whether this is the last attempt at running this tool before an error is raised."""
        return self.retry == self.max_retries

    __repr__ = _utils.dataclasses_no_defaults_repr

```

---|---
####  deps `instance-attribute`
```
deps: RunContextAgentDepsT

```

Dependencies for the agent.
####  model `instance-attribute`
```
model: Model[](https://ai.pydantic.dev/api/models/base/#pydantic_ai.models.Model "Model \(pydantic_ai.models.Model\)")

```

The model used in this run.
####  usage `instance-attribute`
```
usage: RunUsage[](https://ai.pydantic.dev/api/usage/#pydantic_ai.usage.RunUsage "RunUsage



      dataclass
   \(pydantic_ai.result.RunUsage\)")

```

LLM usage associated with the run.
####  prompt `class-attribute` `instance-attribute`
```
prompt: str[](https://docs.python.org/3/library/stdtypes.html#str) | Sequence[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "collections.abc.Sequence")[UserContent] | None = None

```

The original user prompt passed to the run.
####  messages `class-attribute` `instance-attribute`
```
messages: list[](https://docs.python.org/3/library/stdtypes.html#list)[ModelMessage[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ModelMessage "ModelMessage



      module-attribute
   \(pydantic_ai.messages.ModelMessage\)")] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=list[](https://docs.python.org/3/library/stdtypes.html#list)[ModelMessage[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ModelMessage "ModelMessage



      module-attribute
   \(pydantic_ai.messages.ModelMessage\)")]
)

```

Messages exchanged in the conversation so far.
####  validation_context `class-attribute` `instance-attribute`
```
validation_context: Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any") = None

```

Pydantic [validation context](https://docs.pydantic.dev/latest/concepts/validators/#validation-context) for tool args and run outputs.
####  tracer `class-attribute` `instance-attribute`
```
tracer: Tracer = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(default_factory=NoOpTracer)

```

The tracer to use for tracing the run.
####  trace_include_content `class-attribute` `instance-attribute`
```
trace_include_content: bool[](https://docs.python.org/3/library/functions.html#bool) = False

```

Whether to include the content of the messages in the trace.
####  instrumentation_version `class-attribute` `instance-attribute`
```
instrumentation_version: int[](https://docs.python.org/3/library/functions.html#int) = (
    DEFAULT_INSTRUMENTATION_VERSION
)

```

Instrumentation settings version, if instrumentation is enabled.
####  retries `class-attribute` `instance-attribute`
```
retries: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), int[](https://docs.python.org/3/library/functions.html#int)] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), int[](https://docs.python.org/3/library/functions.html#int)]
)

```

Number of retries for each tool so far.
####  tool_call_id `class-attribute` `instance-attribute`
```
tool_call_id: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None

```

The ID of the tool call.
####  tool_name `class-attribute` `instance-attribute`
```
tool_name: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None

```

Name of the tool being called.
####  retry `class-attribute` `instance-attribute`
```
retry: int[](https://docs.python.org/3/library/functions.html#int) = 0

```

Number of retries so far.
For tool calls, this is the number of retries of the specific tool. For output validation, this is the number of output validation retries.
####  max_retries `class-attribute` `instance-attribute`
```
max_retries: int[](https://docs.python.org/3/library/functions.html#int) = 0

```

The maximum number of retries allowed.
For tool calls, this is the maximum retries for the specific tool. For output validation, this is the maximum output validation retries.
####  run_step `class-attribute` `instance-attribute`
```
run_step: int[](https://docs.python.org/3/library/functions.html#int) = 0

```

The current step in the run.
####  tool_call_approved `class-attribute` `instance-attribute`
```
tool_call_approved: bool[](https://docs.python.org/3/library/functions.html#bool) = False

```

Whether a tool call that required approval has now been approved.
####  tool_call_metadata `class-attribute` `instance-attribute`
```
tool_call_metadata: Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any") = None

```

Metadata from `DeferredToolResults.metadata[tool_call_id]`, available when `tool_call_approved=True`.
####  partial_output `class-attribute` `instance-attribute`
```
partial_output: bool[](https://docs.python.org/3/library/functions.html#bool) = False

```

Whether the output passed to an output validator is partial.
####  run_id `class-attribute` `instance-attribute`
```
run_id: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None

```

"Unique identifier for the agent run.
####  metadata `class-attribute` `instance-attribute`
```
metadata: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None = None

```

Metadata associated with this agent run, if configured.
####  last_attempt `property`
```
last_attempt: bool[](https://docs.python.org/3/library/functions.html#bool)

```

Whether this is the last attempt at running this tool before an error is raised.
###  ToolParams `module-attribute`
```
ToolParams = ParamSpec[](https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.ParamSpec "typing_extensions.ParamSpec")('ToolParams', default=...)

```

Retrieval function param spec.
###  SystemPromptFunc `module-attribute`
```
SystemPromptFunc: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = (
    Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[[RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")]], str[](https://docs.python.org/3/library/stdtypes.html#str) | None]
    | Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
        [RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")]], Awaitable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable "collections.abc.Awaitable")[str[](https://docs.python.org/3/library/stdtypes.html#str) | None]
    ]
    | Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[[], str[](https://docs.python.org/3/library/stdtypes.html#str) | None]
    | Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[[], Awaitable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable "collections.abc.Awaitable")[str[](https://docs.python.org/3/library/stdtypes.html#str) | None]]
)

```

A function that may or maybe not take `RunContext` as an argument, and may or may not be async.
Functions which return None are excluded from model requests.
Usage `SystemPromptFunc[AgentDepsT]`.
###  ToolFuncContext `module-attribute`
```
ToolFuncContext: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
    Concatenate[](https://docs.python.org/3/library/typing.html#typing.Concatenate "typing.Concatenate")[RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")], ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")], Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")
]

```

A tool function that takes `RunContext` as the first argument.
Usage `ToolContextFunc[AgentDepsT, ToolParams]`.
###  ToolFuncPlain `module-attribute`
```
ToolFuncPlain: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)"), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]

```

A tool function that does not take `RunContext` as the first argument.
Usage `ToolPlainFunc[ToolParams]`.
###  ToolFuncEither `module-attribute`
```
ToolFuncEither: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = (
    ToolFuncContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncContext "ToolFuncContext



      module-attribute
   \(pydantic_ai.tools.ToolFuncContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)"), ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")]
    | ToolFuncPlain[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncPlain "ToolFuncPlain



      module-attribute
   \(pydantic_ai.tools.ToolFuncPlain\)")[ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")]
)

```

Either kind of tool function.
This is just a union of [`ToolFuncContext`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncContext "ToolFuncContext



      module-attribute
  ") and [`ToolFuncPlain`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncPlain "ToolFuncPlain



      module-attribute
  ").
Usage `ToolFuncEither[AgentDepsT, ToolParams]`.
###  ArgsValidatorFunc `module-attribute`
```
ArgsValidatorFunc: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = (
    Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
        Concatenate[](https://docs.python.org/3/library/typing.html#typing.Concatenate "typing.Concatenate")[RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")], ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")],
        Awaitable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable "collections.abc.Awaitable")[None],
    ]
    | Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
        Concatenate[](https://docs.python.org/3/library/typing.html#typing.Concatenate "typing.Concatenate")[RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")], ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")],
        None,
    ]
)

```

A function that validates tool arguments before execution.
The validator receives the same typed parameters as the tool function, with [`RunContext`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
  ") as the first argument for dependency access.
Should raise [`ModelRetry`](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry "ModelRetry") on validation failure.
###  ToolPrepareFunc `module-attribute`
```
ToolPrepareFunc: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
    [RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")], "ToolDefinition"],
    Awaitable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable "collections.abc.Awaitable")["ToolDefinition | None"],
]

```

Definition of a function that can prepare a tool definition at call time.
See [tool docs](https://ai.pydantic.dev/tools-advanced/#tool-prepare) for more information.
Example — here `only_if_42` is valid as a `ToolPrepareFunc`:
```
from pydantic_ai import RunContext, Tool
from pydantic_ai.tools import ToolDefinition

async def only_if_42(
    ctx: RunContext[int], tool_def: ToolDefinition
) -> ToolDefinition | None:
    if ctx.deps == 42:
        return tool_def

def hitchhiker(ctx: RunContext[int], answer: str) -> str:
    return f'{ctx.deps} {answer}'

hitchhiker = Tool(hitchhiker, prepare=only_if_42)

```

Usage `ToolPrepareFunc[AgentDepsT]`.
###  ToolsPrepareFunc `module-attribute`
```
ToolsPrepareFunc: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
    [RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")], list[](https://docs.python.org/3/library/stdtypes.html#list)["ToolDefinition"]],
    Awaitable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable "collections.abc.Awaitable")["list[ToolDefinition] | None"],
]

```

Definition of a function that can prepare the tool definition of all tools for each step. This is useful if you want to customize the definition of multiple tools or you want to register a subset of tools for a given step.
Example — here `turn_on_strict_if_openai` is valid as a `ToolsPrepareFunc`:
```
from dataclasses import replace

from pydantic_ai import Agent, RunContext
from pydantic_ai.tools import ToolDefinition


async def turn_on_strict_if_openai(
    ctx: RunContext[None], tool_defs: list[ToolDefinition]
) -> list[ToolDefinition] | None:
    if ctx.model.system == 'openai':
        return [replace(tool_def, strict=True) for tool_def in tool_defs]
    return tool_defs

agent = Agent('openai:gpt-5.2', prepare_tools=turn_on_strict_if_openai)

```

Usage `ToolsPrepareFunc[AgentDepsT]`.
###  BuiltinToolFunc `module-attribute`
```
BuiltinToolFunc: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[
    [RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[AgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.AgentDepsT "AgentDepsT



      module-attribute
   \(pydantic_ai._run_context.AgentDepsT\)")]],
    Awaitable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable "collections.abc.Awaitable")[AbstractBuiltinTool[](https://ai.pydantic.dev/api/builtin_tools/#pydantic_ai.builtin_tools.AbstractBuiltinTool "AbstractBuiltinTool



      dataclass
   \(pydantic_ai.builtin_tools.AbstractBuiltinTool\)") | None]
    | AbstractBuiltinTool[](https://ai.pydantic.dev/api/builtin_tools/#pydantic_ai.builtin_tools.AbstractBuiltinTool "AbstractBuiltinTool



      dataclass
   \(pydantic_ai.builtin_tools.AbstractBuiltinTool\)")
    | None,
]

```

Definition of a function that can prepare a builtin tool at call time.
This is useful if you want to customize the builtin tool based on the run context (e.g. user dependencies), or omit it completely from a step.
###  DocstringFormat `module-attribute`
```
DocstringFormat: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Literal[](https://docs.python.org/3/library/typing.html#typing.Literal "typing.Literal")[
    "google", "numpy", "sphinx", "auto"
]

```

Supported docstring formats.
  * `'google'` — [Google-style](https://google.github.io/styleguide/pyguide.html#381-docstrings) docstrings.
  * `'numpy'` — [Numpy-style](https://numpydoc.readthedocs.io/en/latest/format.html) docstrings.
  * `'sphinx'` — [Sphinx-style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format) docstrings.
  * `'auto'` — Automatically infer the format based on the structure of the docstring.


###  DeferredToolRequests `dataclass`
Tool calls that require approval or external execution.
This can be used as an agent's `output_type` and will be used as the output of the agent run if the model called any deferred tools.
Results can be passed to the next agent run using a [`DeferredToolResults`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolResults "DeferredToolResults



      dataclass
  ") object with the same tool call IDs.
See [deferred tools docs](https://ai.pydantic.dev/deferred-tools/#deferred-tools) for more information.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
```
| ```
@dataclass(kw_only=True)
class DeferredToolRequests:
    """Tool calls that require approval or external execution.

    This can be used as an agent's `output_type` and will be used as the output of the agent run if the model called any deferred tools.

    Results can be passed to the next agent run using a [`DeferredToolResults`][pydantic_ai.tools.DeferredToolResults] object with the same tool call IDs.

    See [deferred tools docs](../deferred-tools.md#deferred-tools) for more information.
    """

    calls: list[ToolCallPart] = field(default_factory=list[ToolCallPart])
    """Tool calls that require external execution."""
    approvals: list[ToolCallPart] = field(default_factory=list[ToolCallPart])
    """Tool calls that require human-in-the-loop approval."""
    metadata: dict[str, dict[str, Any]] = field(default_factory=dict[str, dict[str, Any]])
    """Metadata for deferred tool calls, keyed by `tool_call_id`."""

```

---|---
####  calls `class-attribute` `instance-attribute`
```
calls: list[](https://docs.python.org/3/library/stdtypes.html#list)[ToolCallPart[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ToolCallPart "ToolCallPart



      dataclass
   \(pydantic_ai.messages.ToolCallPart\)")] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=list[](https://docs.python.org/3/library/stdtypes.html#list)[ToolCallPart[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ToolCallPart "ToolCallPart



      dataclass
   \(pydantic_ai.messages.ToolCallPart\)")]
)

```

Tool calls that require external execution.
####  approvals `class-attribute` `instance-attribute`
```
approvals: list[](https://docs.python.org/3/library/stdtypes.html#list)[ToolCallPart[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ToolCallPart "ToolCallPart



      dataclass
   \(pydantic_ai.messages.ToolCallPart\)")] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=list[](https://docs.python.org/3/library/stdtypes.html#list)[ToolCallPart[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ToolCallPart "ToolCallPart



      dataclass
   \(pydantic_ai.messages.ToolCallPart\)")]
)

```

Tool calls that require human-in-the-loop approval.
####  metadata `class-attribute` `instance-attribute`
```
metadata: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]]
)

```

Metadata for deferred tool calls, keyed by `tool_call_id`.
###  ToolApproved `dataclass`
Indicates that a tool call has been approved and that the tool function should be executed.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
179
180
181
182
183
184
185
186
```
| ```
@dataclass(kw_only=True)
class ToolApproved:
    """Indicates that a tool call has been approved and that the tool function should be executed."""

    override_args: dict[str, Any] | None = None
    """Optional tool call arguments to use instead of the original arguments."""

    kind: Literal['tool-approved'] = 'tool-approved'

```

---|---
####  override_args `class-attribute` `instance-attribute`
```
override_args: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None = None

```

Optional tool call arguments to use instead of the original arguments.
###  ToolDenied `dataclass`
Indicates that a tool call has been denied and that a denial message should be returned to the model.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
189
190
191
192
193
194
195
196
197
198
```
| ```
@dataclass
class ToolDenied:
    """Indicates that a tool call has been denied and that a denial message should be returned to the model."""

    message: str = 'The tool call was denied.'
    """The message to return to the model."""

    _: KW_ONLY

    kind: Literal['tool-denied'] = 'tool-denied'

```

---|---
####  message `class-attribute` `instance-attribute`
```
message: str[](https://docs.python.org/3/library/stdtypes.html#str) = 'The tool call was denied.'

```

The message to return to the model.
###  DeferredToolApprovalResult `module-attribute`
```
DeferredToolApprovalResult: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Annotated[](https://docs.python.org/3/library/typing.html#typing.Annotated "typing.Annotated")[
    ToolApproved[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolApproved "ToolApproved



      dataclass
   \(pydantic_ai.tools.ToolApproved\)") | ToolDenied[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDenied "ToolDenied



      dataclass
   \(pydantic_ai.tools.ToolDenied\)"), Discriminator[](https://docs.pydantic.dev/latest/api/types/#pydantic.types.Discriminator "pydantic.Discriminator")("kind")
]

```

Result for a tool call that required human-in-the-loop approval.
###  DeferredToolCallResult `module-attribute`
```
DeferredToolCallResult: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Annotated[](https://docs.python.org/3/library/typing.html#typing.Annotated "typing.Annotated")[
    Annotated[](https://docs.python.org/3/library/typing.html#typing.Annotated "typing.Annotated")[ToolReturn[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.ToolReturn "ToolReturn



      dataclass
   \(pydantic_ai.messages.ToolReturn\)"), Tag[](https://docs.pydantic.dev/latest/api/types/#pydantic.types.Tag "pydantic.Tag")("tool-return")]
    | Annotated[](https://docs.python.org/3/library/typing.html#typing.Annotated "typing.Annotated")[ModelRetry[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry "ModelRetry \(pydantic_ai.exceptions.ModelRetry\)"), Tag[](https://docs.pydantic.dev/latest/api/types/#pydantic.types.Tag "pydantic.Tag")("model-retry")]
    | Annotated[](https://docs.python.org/3/library/typing.html#typing.Annotated "typing.Annotated")[RetryPromptPart[](https://ai.pydantic.dev/api/messages/#pydantic_ai.messages.RetryPromptPart "RetryPromptPart



      dataclass
   \(pydantic_ai.messages.RetryPromptPart\)"), Tag[](https://docs.pydantic.dev/latest/api/types/#pydantic.types.Tag "pydantic.Tag")("retry-prompt")],
    Discriminator[](https://docs.pydantic.dev/latest/api/types/#pydantic.types.Discriminator "pydantic.Discriminator")(_deferred_tool_call_result_discriminator),
]

```

Result for a tool call that required external execution.
###  DeferredToolResult `module-attribute`
```
DeferredToolResult = (
    DeferredToolApprovalResult[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolApprovalResult "DeferredToolApprovalResult



      module-attribute
   \(pydantic_ai.tools.DeferredToolApprovalResult\)") | DeferredToolCallResult[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolCallResult "DeferredToolCallResult



      module-attribute
   \(pydantic_ai.tools.DeferredToolCallResult\)")
)

```

Result for a tool call that required approval or external execution.
###  DeferredToolResults `dataclass`
Results for deferred tool calls from a previous run that required approval or external execution.
The tool call IDs need to match those from the [`DeferredToolRequests`](https://ai.pydantic.dev/api/output/#pydantic_ai.output.DeferredToolRequests "DeferredToolRequests



      dataclass
  ") output object from the previous run.
See [deferred tools docs](https://ai.pydantic.dev/deferred-tools/#deferred-tools) for more information.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
```
| ```
@dataclass(kw_only=True)
class DeferredToolResults:
    """Results for deferred tool calls from a previous run that required approval or external execution.

    The tool call IDs need to match those from the [`DeferredToolRequests`][pydantic_ai.output.DeferredToolRequests] output object from the previous run.

    See [deferred tools docs](../deferred-tools.md#deferred-tools) for more information.
    """

    calls: dict[str, DeferredToolCallResult | Any] = field(default_factory=dict[str, DeferredToolCallResult | Any])
    """Map of tool call IDs to results for tool calls that required external execution."""
    approvals: dict[str, bool | DeferredToolApprovalResult] = field(
        default_factory=dict[str, bool | DeferredToolApprovalResult]
    )
    """Map of tool call IDs to results for tool calls that required human-in-the-loop approval."""
    metadata: dict[str, dict[str, Any]] = field(default_factory=dict[str, dict[str, Any]])
    """Metadata for deferred tool calls, keyed by `tool_call_id`. Each value will be available in the tool's RunContext as `tool_call_metadata`."""

```

---|---
####  calls `class-attribute` `instance-attribute`
```
calls: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), DeferredToolCallResult[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolCallResult "DeferredToolCallResult



      module-attribute
   \(pydantic_ai.tools.DeferredToolCallResult\)") | Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), DeferredToolCallResult[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolCallResult "DeferredToolCallResult



      module-attribute
   \(pydantic_ai.tools.DeferredToolCallResult\)") | Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]
)

```

Map of tool call IDs to results for tool calls that required external execution.
####  approvals `class-attribute` `instance-attribute`
```
approvals: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), bool[](https://docs.python.org/3/library/functions.html#bool) | DeferredToolApprovalResult[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolApprovalResult "DeferredToolApprovalResult



      module-attribute
   \(pydantic_ai.tools.DeferredToolApprovalResult\)")] = (
    field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
        default_factory=dict[](https://docs.python.org/3/library/stdtypes.html#dict)[
            str[](https://docs.python.org/3/library/stdtypes.html#str), bool[](https://docs.python.org/3/library/functions.html#bool) | DeferredToolApprovalResult[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DeferredToolApprovalResult "DeferredToolApprovalResult



      module-attribute
   \(pydantic_ai.tools.DeferredToolApprovalResult\)")
        ]
    )
)

```

Map of tool call IDs to results for tool calls that required human-in-the-loop approval.
####  metadata `class-attribute` `instance-attribute`
```
metadata: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]] = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]]
)

```

Metadata for deferred tool calls, keyed by `tool_call_id`. Each value will be available in the tool's RunContext as `tool_call_metadata`.
###  ToolAgentDepsT `module-attribute`
```
ToolAgentDepsT = TypeVar(
    "ToolAgentDepsT", default=object[](https://docs.python.org/3/library/functions.html#object), contravariant=True
)

```

Type variable for agent dependencies for a tool.
###  Tool `dataclass`
Bases: `Generic[](https://docs.python.org/3/library/typing.html#typing.Generic "typing.Generic")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)")]`
A tool function for an agent.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
```
| ```
@dataclass(init=False)
class Tool(Generic[ToolAgentDepsT]):
    """A tool function for an agent."""

    function: ToolFuncEither[ToolAgentDepsT]
    takes_ctx: bool
    max_retries: int | None
    name: str
    description: str | None
    prepare: ToolPrepareFunc[ToolAgentDepsT] | None
    args_validator: ArgsValidatorFunc[ToolAgentDepsT, ...] | None
    docstring_format: DocstringFormat
    require_parameter_descriptions: bool
    strict: bool | None
    sequential: bool
    requires_approval: bool
    metadata: dict[str, Any] | None
    timeout: float | None
    function_schema: _function_schema.FunctionSchema
    """
    The base JSON schema for the tool's parameters.

    This schema may be modified by the `prepare` function or by the Model class prior to including it in an API request.
    """

    def __init__(
        self,
        function: ToolFuncEither[ToolAgentDepsT, ToolParams],
        *,
        takes_ctx: bool | None = None,
        max_retries: int | None = None,
        name: str | None = None,
        description: str | None = None,
        prepare: ToolPrepareFunc[ToolAgentDepsT] | None = None,
        args_validator: ArgsValidatorFunc[ToolAgentDepsT, ToolParams] | None = None,
        docstring_format: DocstringFormat = 'auto',
        require_parameter_descriptions: bool = False,
        schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
        strict: bool | None = None,
        sequential: bool = False,
        requires_approval: bool = False,
        metadata: dict[str, Any] | None = None,
        timeout: float | None = None,
        function_schema: _function_schema.FunctionSchema | None = None,
    ):
        """Create a new tool instance.

        Example usage:

    ```python {noqa="I001"}
        from pydantic_ai import Agent, RunContext, Tool

        async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
            return f'{ctx.deps} {x} {y}'

        agent = Agent('test', tools=[Tool(my_tool)])
    ```

        or with a custom prepare method:

    ```python {noqa="I001"}

        from pydantic_ai import Agent, RunContext, Tool
        from pydantic_ai.tools import ToolDefinition

        async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
            return f'{ctx.deps} {x} {y}'

        async def prep_my_tool(
            ctx: RunContext[int], tool_def: ToolDefinition
        ) -> ToolDefinition | None:
            # only register the tool if `deps == 42`
            if ctx.deps == 42:
                return tool_def

        agent = Agent('test', tools=[Tool(my_tool, prepare=prep_my_tool)])
    ```


        Args:
            function: The Python function to call as the tool.
            takes_ctx: Whether the function takes a [`RunContext`][pydantic_ai.tools.RunContext] first argument,
                this is inferred if unset.
            max_retries: Maximum number of retries allowed for this tool, set to the agent default if `None`.
            name: Name of the tool, inferred from the function if `None`.
            description: Description of the tool, inferred from the function if `None`.
            prepare: custom method to prepare the tool definition for each step, return `None` to omit this
                tool from a given step. This is useful if you want to customise a tool at call time,
                or omit it completely from a step. See [`ToolPrepareFunc`][pydantic_ai.tools.ToolPrepareFunc].
            args_validator: custom method to validate tool arguments after schema validation has passed,
                before execution. The validator receives the already-validated and type-converted parameters,
                with `RunContext` as the first argument.
                Should raise [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] on validation failure,
                return `None` on success.
                See [`ArgsValidatorFunc`][pydantic_ai.tools.ArgsValidatorFunc].
            docstring_format: The format of the docstring, see [`DocstringFormat`][pydantic_ai.tools.DocstringFormat].
                Defaults to `'auto'`, such that the format is inferred from the structure of the docstring.
            require_parameter_descriptions: If True, raise an error if a parameter description is missing. Defaults to False.
            schema_generator: The JSON schema generator class to use. Defaults to `GenerateToolJsonSchema`.
            strict: Whether to enforce JSON schema compliance (only affects OpenAI).
                See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
            sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
            requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
            metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
            timeout: Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model.
                Defaults to None (no timeout).
            function_schema: The function schema to use for the tool. If not provided, it will be generated.
        """
        self.function = function
        self.function_schema = function_schema or _function_schema.function_schema(
            function,
            schema_generator,
            takes_ctx=takes_ctx,
            docstring_format=docstring_format,
            require_parameter_descriptions=require_parameter_descriptions,
        )
        self.takes_ctx = self.function_schema.takes_ctx
        self.max_retries = max_retries
        self.name = name or function.__name__
        self.description = description or self.function_schema.description
        self.prepare = prepare
        self.args_validator = args_validator
        self.docstring_format = docstring_format
        self.require_parameter_descriptions = require_parameter_descriptions
        self.strict = strict
        self.sequential = sequential
        self.requires_approval = requires_approval
        self.metadata = metadata
        self.timeout = timeout

    @classmethod
    def from_schema(
        cls,
        function: Callable[..., Any],
        name: str,
        description: str | None,
        json_schema: JsonSchemaValue,
        takes_ctx: bool = False,
        sequential: bool = False,
        args_validator: ArgsValidatorFunc[Any, ...] | None = None,
    ) -> Self:
        """Creates a Pydantic tool from a function and a JSON schema.

        Args:
            function: The function to call.
                This will be called with keywords only. Schema validation of
                the arguments is skipped, but a custom `args_validator` will
                still run if provided.
            name: The unique name of the tool that clearly communicates its purpose
            description: Used to tell the model how/when/why to use the tool.
                You can provide few-shot examples as a part of the description.
            json_schema: The schema for the function arguments
            takes_ctx: An optional boolean parameter indicating whether the function
                accepts the context object as an argument.
            sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
            args_validator: custom method to validate tool arguments after schema validation has passed,
                before execution. The validator receives the already-validated and type-converted parameters,
                with `RunContext` as the first argument.
                Should raise [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] on validation failure,
                return `None` on success.
                See [`ArgsValidatorFunc`][pydantic_ai.tools.ArgsValidatorFunc].

        Returns:
            A Pydantic tool that calls the function
        """
        function_schema = _function_schema.FunctionSchema(
            function=function,
            description=description,
            validator=SchemaValidator(schema=core_schema.any_schema()),
            json_schema=json_schema,
            takes_ctx=takes_ctx,
            is_async=_utils.is_async_callable(function),
        )

        return cls(
            function,
            takes_ctx=takes_ctx,
            name=name,
            description=description,
            function_schema=function_schema,
            sequential=sequential,
            args_validator=args_validator,
        )

    @property
    def tool_def(self):
        return ToolDefinition(
            name=self.name,
            description=self.description,
            parameters_json_schema=self.function_schema.json_schema,
            strict=self.strict,
            sequential=self.sequential,
            metadata=self.metadata,
            timeout=self.timeout,
            kind='unapproved' if self.requires_approval else 'function',
        )

    async def prepare_tool_def(self, ctx: RunContext[ToolAgentDepsT]) -> ToolDefinition | None:
        """Get the tool definition.

        By default, this method creates a tool definition, then either returns it, or calls `self.prepare`
        if it's set.

        Returns:
            return a `ToolDefinition` or `None` if the tools should not be registered for this run.
        """
        base_tool_def = self.tool_def

        if self.prepare is not None:
            return await self.prepare(ctx, base_tool_def)
        else:
            return base_tool_def

```

---|---
####  __init__
```
__init__(
    function: ToolFuncEither[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncEither "ToolFuncEither



      module-attribute
   \(pydantic_ai.tools.ToolFuncEither\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)"), ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")],
    *,
    takes_ctx: bool[](https://docs.python.org/3/library/functions.html#bool) | None = None,
    max_retries: int[](https://docs.python.org/3/library/functions.html#int) | None = None,
    name: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None,
    description: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None,
    prepare: ToolPrepareFunc[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolPrepareFunc "ToolPrepareFunc



      module-attribute
   \(pydantic_ai.tools.ToolPrepareFunc\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)")] | None = None,
    args_validator: (
        ArgsValidatorFunc[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc "ArgsValidatorFunc



      module-attribute
   \(pydantic_ai.tools.ArgsValidatorFunc\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)"), ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")] | None
    ) = None,
    docstring_format: DocstringFormat[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DocstringFormat "DocstringFormat



      module-attribute
   \(pydantic_ai.tools.DocstringFormat\)") = "auto",
    require_parameter_descriptions: bool[](https://docs.python.org/3/library/functions.html#bool) = False,
    schema_generator: type[](https://docs.python.org/3/library/functions.html#type)[
        GenerateJsonSchema[](https://docs.pydantic.dev/latest/api/json_schema/#pydantic.json_schema.GenerateJsonSchema "pydantic.json_schema.GenerateJsonSchema")
    ] = GenerateToolJsonSchema,
    strict: bool[](https://docs.python.org/3/library/functions.html#bool) | None = None,
    sequential: bool[](https://docs.python.org/3/library/functions.html#bool) = False,
    requires_approval: bool[](https://docs.python.org/3/library/functions.html#bool) = False,
    metadata: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None = None,
    timeout: float[](https://docs.python.org/3/library/functions.html#float) | None = None,
    function_schema: FunctionSchema | None = None
)

```

Create a new tool instance.
Example usage:
```
from pydantic_ai import Agent, RunContext, Tool

async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
    return f'{ctx.deps} {x} {y}'

agent = Agent('test', tools=[Tool(my_tool)])

```

or with a custom prepare method:
```
from pydantic_ai import Agent, RunContext, Tool
from pydantic_ai.tools import ToolDefinition

async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
    return f'{ctx.deps} {x} {y}'

async def prep_my_tool(
    ctx: RunContext[int], tool_def: ToolDefinition
) -> ToolDefinition | None:
    # only register the tool if `deps == 42`
    if ctx.deps == 42:
        return tool_def

agent = Agent('test', tools=[Tool(my_tool, prepare=prep_my_tool)])

```

Parameters:
Name | Type | Description | Default
---|---|---|---
`function` |  `ToolFuncEither[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolFuncEither "ToolFuncEither



      module-attribute
   \(pydantic_ai.tools.ToolFuncEither\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)"), ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")]` |  The Python function to call as the tool. |  _required_
`takes_ctx` |  `bool[](https://docs.python.org/3/library/functions.html#bool) | None` |  Whether the function takes a [`RunContext`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
  ") first argument, this is inferred if unset. |  `None`
`max_retries` |  `int[](https://docs.python.org/3/library/functions.html#int) | None` |  Maximum number of retries allowed for this tool, set to the agent default if `None`. |  `None`
`name` |  `str[](https://docs.python.org/3/library/stdtypes.html#str) | None` |  Name of the tool, inferred from the function if `None`. |  `None`
`description` |  `str[](https://docs.python.org/3/library/stdtypes.html#str) | None` |  Description of the tool, inferred from the function if `None`. |  `None`
`prepare` |  `ToolPrepareFunc[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolPrepareFunc "ToolPrepareFunc



      module-attribute
   \(pydantic_ai.tools.ToolPrepareFunc\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)")] | None` |  custom method to prepare the tool definition for each step, return `None` to omit this tool from a given step. This is useful if you want to customise a tool at call time, or omit it completely from a step. See [`ToolPrepareFunc`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolPrepareFunc "ToolPrepareFunc



      module-attribute
  "). |  `None`
`args_validator` |  `ArgsValidatorFunc[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc "ArgsValidatorFunc



      module-attribute
   \(pydantic_ai.tools.ArgsValidatorFunc\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)"), ToolParams[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolParams "ToolParams



      module-attribute
   \(pydantic_ai.tools.ToolParams\)")] | None` |  custom method to validate tool arguments after schema validation has passed, before execution. The validator receives the already-validated and type-converted parameters, with `RunContext` as the first argument. Should raise [`ModelRetry`](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry "ModelRetry") on validation failure, return `None` on success. See [`ArgsValidatorFunc`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc "ArgsValidatorFunc



      module-attribute
  "). |  `None`
`docstring_format` |  `DocstringFormat[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DocstringFormat "DocstringFormat



      module-attribute
   \(pydantic_ai.tools.DocstringFormat\)")` |  The format of the docstring, see [`DocstringFormat`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.DocstringFormat "DocstringFormat



      module-attribute
  "). Defaults to `'auto'`, such that the format is inferred from the structure of the docstring. |  `'auto'`
`require_parameter_descriptions` |  `bool[](https://docs.python.org/3/library/functions.html#bool)` |  If True, raise an error if a parameter description is missing. Defaults to False. |  `False`
`schema_generator` |  `type[](https://docs.python.org/3/library/functions.html#type)[GenerateJsonSchema[](https://docs.pydantic.dev/latest/api/json_schema/#pydantic.json_schema.GenerateJsonSchema "pydantic.json_schema.GenerateJsonSchema")]` |  The JSON schema generator class to use. Defaults to `GenerateToolJsonSchema`. |  `GenerateToolJsonSchema`
`strict` |  `bool[](https://docs.python.org/3/library/functions.html#bool) | None` |  Whether to enforce JSON schema compliance (only affects OpenAI). See [`ToolDefinition`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition "ToolDefinition



      dataclass
  ") for more info. |  `None`
`sequential` |  `bool[](https://docs.python.org/3/library/functions.html#bool)` |  Whether the function requires a sequential/serial execution environment. Defaults to False. |  `False`
`requires_approval` |  `bool[](https://docs.python.org/3/library/functions.html#bool)` |  Whether this tool requires human-in-the-loop approval. Defaults to False. See the [tools documentation](https://ai.pydantic.dev/deferred-tools/#human-in-the-loop-tool-approval) for more info. |  `False`
`metadata` |  `dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None` |  Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization. |  `None`
`timeout` |  `float[](https://docs.python.org/3/library/functions.html#float) | None` |  Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model. Defaults to None (no timeout). |  `None`
`function_schema` |  `FunctionSchema | None` |  The function schema to use for the tool. If not provided, it will be generated. |  `None`
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
```
| ```
def __init__(
    self,
    function: ToolFuncEither[ToolAgentDepsT, ToolParams],
    *,
    takes_ctx: bool | None = None,
    max_retries: int | None = None,
    name: str | None = None,
    description: str | None = None,
    prepare: ToolPrepareFunc[ToolAgentDepsT] | None = None,
    args_validator: ArgsValidatorFunc[ToolAgentDepsT, ToolParams] | None = None,
    docstring_format: DocstringFormat = 'auto',
    require_parameter_descriptions: bool = False,
    schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
    strict: bool | None = None,
    sequential: bool = False,
    requires_approval: bool = False,
    metadata: dict[str, Any] | None = None,
    timeout: float | None = None,
    function_schema: _function_schema.FunctionSchema | None = None,
):
    """Create a new tool instance.

    Example usage:

```python {noqa="I001"}
    from pydantic_ai import Agent, RunContext, Tool

    async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
        return f'{ctx.deps} {x} {y}'

    agent = Agent('test', tools=[Tool(my_tool)])
```

    or with a custom prepare method:

```python {noqa="I001"}

    from pydantic_ai import Agent, RunContext, Tool
    from pydantic_ai.tools import ToolDefinition

    async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
        return f'{ctx.deps} {x} {y}'

    async def prep_my_tool(
        ctx: RunContext[int], tool_def: ToolDefinition
    ) -> ToolDefinition | None:
        # only register the tool if `deps == 42`
        if ctx.deps == 42:
            return tool_def

    agent = Agent('test', tools=[Tool(my_tool, prepare=prep_my_tool)])
```


    Args:
        function: The Python function to call as the tool.
        takes_ctx: Whether the function takes a [`RunContext`][pydantic_ai.tools.RunContext] first argument,
            this is inferred if unset.
        max_retries: Maximum number of retries allowed for this tool, set to the agent default if `None`.
        name: Name of the tool, inferred from the function if `None`.
        description: Description of the tool, inferred from the function if `None`.
        prepare: custom method to prepare the tool definition for each step, return `None` to omit this
            tool from a given step. This is useful if you want to customise a tool at call time,
            or omit it completely from a step. See [`ToolPrepareFunc`][pydantic_ai.tools.ToolPrepareFunc].
        args_validator: custom method to validate tool arguments after schema validation has passed,
            before execution. The validator receives the already-validated and type-converted parameters,
            with `RunContext` as the first argument.
            Should raise [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] on validation failure,
            return `None` on success.
            See [`ArgsValidatorFunc`][pydantic_ai.tools.ArgsValidatorFunc].
        docstring_format: The format of the docstring, see [`DocstringFormat`][pydantic_ai.tools.DocstringFormat].
            Defaults to `'auto'`, such that the format is inferred from the structure of the docstring.
        require_parameter_descriptions: If True, raise an error if a parameter description is missing. Defaults to False.
        schema_generator: The JSON schema generator class to use. Defaults to `GenerateToolJsonSchema`.
        strict: Whether to enforce JSON schema compliance (only affects OpenAI).
            See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
        sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
        requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
            See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
        metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
        timeout: Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model.
            Defaults to None (no timeout).
        function_schema: The function schema to use for the tool. If not provided, it will be generated.
    """
    self.function = function
    self.function_schema = function_schema or _function_schema.function_schema(
        function,
        schema_generator,
        takes_ctx=takes_ctx,
        docstring_format=docstring_format,
        require_parameter_descriptions=require_parameter_descriptions,
    )
    self.takes_ctx = self.function_schema.takes_ctx
    self.max_retries = max_retries
    self.name = name or function.__name__
    self.description = description or self.function_schema.description
    self.prepare = prepare
    self.args_validator = args_validator
    self.docstring_format = docstring_format
    self.require_parameter_descriptions = require_parameter_descriptions
    self.strict = strict
    self.sequential = sequential
    self.requires_approval = requires_approval
    self.metadata = metadata
    self.timeout = timeout

```

---|---
####  function_schema `instance-attribute`
```
function_schema: FunctionSchema = (
    function_schema
    or function_schema(
        function,
        schema_generator,
        takes_ctx=takes_ctx,
        docstring_format=docstring_format,
        require_parameter_descriptions=require_parameter_descriptions,
    )
)

```

The base JSON schema for the tool's parameters.
This schema may be modified by the `prepare` function or by the Model class prior to including it in an API request.
####  from_schema `classmethod`
```
from_schema(
    function: Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[..., Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")],
    name: str[](https://docs.python.org/3/library/stdtypes.html#str),
    description: str[](https://docs.python.org/3/library/stdtypes.html#str) | None,
    json_schema: JsonSchemaValue[](https://docs.pydantic.dev/latest/api/json_schema/#pydantic.json_schema.JsonSchemaValue "pydantic.json_schema.JsonSchemaValue"),
    takes_ctx: bool[](https://docs.python.org/3/library/functions.html#bool) = False,
    sequential: bool[](https://docs.python.org/3/library/functions.html#bool) = False,
    args_validator: (
        ArgsValidatorFunc[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc "ArgsValidatorFunc



      module-attribute
   \(pydantic_ai.tools.ArgsValidatorFunc\)")[Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any"), ...] | None
    ) = None,
) -> Self[](https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Self "typing_extensions.Self")

```

Creates a Pydantic tool from a function and a JSON schema.
Parameters:
Name | Type | Description | Default
---|---|---|---
`function` |  `Callable[](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "collections.abc.Callable")[..., Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]` |  The function to call. This will be called with keywords only. Schema validation of the arguments is skipped, but a custom `args_validator` will still run if provided. |  _required_
`name` |  `str[](https://docs.python.org/3/library/stdtypes.html#str)` |  The unique name of the tool that clearly communicates its purpose |  _required_
`description` |  `str[](https://docs.python.org/3/library/stdtypes.html#str) | None` |  Used to tell the model how/when/why to use the tool. You can provide few-shot examples as a part of the description. |  _required_
`json_schema` |  `JsonSchemaValue[](https://docs.pydantic.dev/latest/api/json_schema/#pydantic.json_schema.JsonSchemaValue "pydantic.json_schema.JsonSchemaValue")` |  The schema for the function arguments |  _required_
`takes_ctx` |  `bool[](https://docs.python.org/3/library/functions.html#bool)` |  An optional boolean parameter indicating whether the function accepts the context object as an argument. |  `False`
`sequential` |  `bool[](https://docs.python.org/3/library/functions.html#bool)` |  Whether the function requires a sequential/serial execution environment. Defaults to False. |  `False`
`args_validator` |  `ArgsValidatorFunc[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc "ArgsValidatorFunc



      module-attribute
   \(pydantic_ai.tools.ArgsValidatorFunc\)")[Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any"), ...] | None` |  custom method to validate tool arguments after schema validation has passed, before execution. The validator receives the already-validated and type-converted parameters, with `RunContext` as the first argument. Should raise [`ModelRetry`](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry "ModelRetry") on validation failure, return `None` on success. See [`ArgsValidatorFunc`](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ArgsValidatorFunc "ArgsValidatorFunc



      module-attribute
  "). |  `None`
Returns:
Type | Description
---|---
`Self[](https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Self "typing_extensions.Self")` |  A Pydantic tool that calls the function
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
```
| ```
@classmethod
def from_schema(
    cls,
    function: Callable[..., Any],
    name: str,
    description: str | None,
    json_schema: JsonSchemaValue,
    takes_ctx: bool = False,
    sequential: bool = False,
    args_validator: ArgsValidatorFunc[Any, ...] | None = None,
) -> Self:
    """Creates a Pydantic tool from a function and a JSON schema.

    Args:
        function: The function to call.
            This will be called with keywords only. Schema validation of
            the arguments is skipped, but a custom `args_validator` will
            still run if provided.
        name: The unique name of the tool that clearly communicates its purpose
        description: Used to tell the model how/when/why to use the tool.
            You can provide few-shot examples as a part of the description.
        json_schema: The schema for the function arguments
        takes_ctx: An optional boolean parameter indicating whether the function
            accepts the context object as an argument.
        sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
        args_validator: custom method to validate tool arguments after schema validation has passed,
            before execution. The validator receives the already-validated and type-converted parameters,
            with `RunContext` as the first argument.
            Should raise [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] on validation failure,
            return `None` on success.
            See [`ArgsValidatorFunc`][pydantic_ai.tools.ArgsValidatorFunc].

    Returns:
        A Pydantic tool that calls the function
    """
    function_schema = _function_schema.FunctionSchema(
        function=function,
        description=description,
        validator=SchemaValidator(schema=core_schema.any_schema()),
        json_schema=json_schema,
        takes_ctx=takes_ctx,
        is_async=_utils.is_async_callable(function),
    )

    return cls(
        function,
        takes_ctx=takes_ctx,
        name=name,
        description=description,
        function_schema=function_schema,
        sequential=sequential,
        args_validator=args_validator,
    )

```

---|---
####  prepare_tool_def `async`
```
prepare_tool_def(
    ctx: RunContext[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.RunContext "RunContext



      dataclass
   \(pydantic_ai._run_context.RunContext\)")[ToolAgentDepsT[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolAgentDepsT "ToolAgentDepsT



      module-attribute
   \(pydantic_ai.tools.ToolAgentDepsT\)")],
) -> ToolDefinition[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition "ToolDefinition



      dataclass
   \(pydantic_ai.tools.ToolDefinition\)") | None

```

Get the tool definition.
By default, this method creates a tool definition, then either returns it, or calls `self.prepare` if it's set.
Returns:
Type | Description
---|---
`ToolDefinition[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition "ToolDefinition



      dataclass
   \(pydantic_ai.tools.ToolDefinition\)") | None` |  return a `ToolDefinition` or `None` if the tools should not be registered for this run.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
```
| ```
async def prepare_tool_def(self, ctx: RunContext[ToolAgentDepsT]) -> ToolDefinition | None:
    """Get the tool definition.

    By default, this method creates a tool definition, then either returns it, or calls `self.prepare`
    if it's set.

    Returns:
        return a `ToolDefinition` or `None` if the tools should not be registered for this run.
    """
    base_tool_def = self.tool_def

    if self.prepare is not None:
        return await self.prepare(ctx, base_tool_def)
    else:
        return base_tool_def

```

---|---
###  ObjectJsonSchema `module-attribute`
```
ObjectJsonSchema: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]

```

Type representing JSON schema of an object, e.g. where `"type": "object"`.
This type is used to define tools parameters (aka arguments) in [ToolDefinition](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolDefinition "ToolDefinition



      dataclass
  ").
With PEP-728 this should be a TypedDict with `type: Literal['object']`, and `extra_parts=Any`
###  ToolKind `module-attribute`
```
ToolKind: TypeAlias[](https://docs.python.org/3/library/typing.html#typing.TypeAlias "typing.TypeAlias") = Literal[](https://docs.python.org/3/library/typing.html#typing.Literal "typing.Literal")[
    "function", "output", "external", "unapproved"
]

```

Kind of tool.
###  ToolDefinition `dataclass`
Definition of a tool passed to a model.
This is used for both function tools and output tools.
Source code in `pydantic_ai_slim/pydantic_ai/tools.py`
```
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
```
| ```
@dataclass(repr=False, kw_only=True)
class ToolDefinition:
    """Definition of a tool passed to a model.

    This is used for both function tools and output tools.
    """

    name: str
    """The name of the tool."""

    parameters_json_schema: ObjectJsonSchema = field(default_factory=lambda: {'type': 'object', 'properties': {}})
    """The JSON schema for the tool's parameters."""

    description: str | None = None
    """The description of the tool."""

    outer_typed_dict_key: str | None = None
    """The key in the outer [TypedDict] that wraps an output tool.

    This will only be set for output tools which don't have an `object` JSON schema.
    """

    strict: bool | None = None
    """Whether to enforce (vendor-specific) strict JSON schema validation for tool calls.

    Setting this to `True` while using a supported model generally imposes some restrictions on the tool's JSON schema
    in exchange for guaranteeing the API responses strictly match that schema.

    When `False`, the model may be free to generate other properties or types (depending on the vendor).
    When `None` (the default), the value will be inferred based on the compatibility of the parameters_json_schema.

    Note: this is currently supported by OpenAI and Anthropic models.
    """

    sequential: bool = False
    """Whether this tool requires a sequential/serial execution environment."""

    kind: ToolKind = field(default='function')
    """The kind of tool:

    - `'function'`: a tool that will be executed by Pydantic AI during an agent run and has its result returned to the model
    - `'output'`: a tool that passes through an output value that ends the run
    - `'external'`: a tool whose result will be produced outside of the Pydantic AI agent run in which it was called, because it depends on an upstream service (or user) or could take longer to generate than it's reasonable to keep the agent process running.
        See the [tools documentation](../deferred-tools.md#deferred-tools) for more info.
    - `'unapproved'`: a tool that requires human-in-the-loop approval.
        See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
    """

    metadata: dict[str, Any] | None = None
    """Tool metadata that can be set by the toolset this tool came from. It is not sent to the model, but can be used for filtering and tool behavior customization.

    For MCP tools, this contains the `meta`, `annotations`, and `output_schema` fields from the tool definition.
    """

    timeout: float | None = None
    """Timeout in seconds for tool execution.

    If the tool takes longer than this, a retry prompt is returned to the model.
    Defaults to None (no timeout).
    """

    @property
    def defer(self) -> bool:
        """Whether calls to this tool will be deferred.

        See the [tools documentation](../deferred-tools.md#deferred-tools) for more info.
        """
        return self.kind in ('external', 'unapproved')

    __repr__ = _utils.dataclasses_no_defaults_repr

```

---|---
####  name `instance-attribute`
```
name: str[](https://docs.python.org/3/library/stdtypes.html#str)

```

The name of the tool.
####  parameters_json_schema `class-attribute` `instance-attribute`
```
parameters_json_schema: ObjectJsonSchema[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ObjectJsonSchema "ObjectJsonSchema



      module-attribute
   \(pydantic_ai.tools.ObjectJsonSchema\)") = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(
    default_factory=lambda: {
        "type": "object",
        "properties": {},
    }
)

```

The JSON schema for the tool's parameters.
####  description `class-attribute` `instance-attribute`
```
description: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None

```

The description of the tool.
####  outer_typed_dict_key `class-attribute` `instance-attribute`
```
outer_typed_dict_key: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = None

```

The key in the outer [TypedDict] that wraps an output tool.
This will only be set for output tools which don't have an `object` JSON schema.
####  strict `class-attribute` `instance-attribute`
```
strict: bool[](https://docs.python.org/3/library/functions.html#bool) | None = None

```

Whether to enforce (vendor-specific) strict JSON schema validation for tool calls.
Setting this to `True` while using a supported model generally imposes some restrictions on the tool's JSON schema in exchange for guaranteeing the API responses strictly match that schema.
When `False`, the model may be free to generate other properties or types (depending on the vendor). When `None` (the default), the value will be inferred based on the compatibility of the parameters_json_schema.
Note: this is currently supported by OpenAI and Anthropic models.
####  sequential `class-attribute` `instance-attribute`
```
sequential: bool[](https://docs.python.org/3/library/functions.html#bool) = False

```

Whether this tool requires a sequential/serial execution environment.
####  kind `class-attribute` `instance-attribute`
```
kind: ToolKind[](https://ai.pydantic.dev/api/tools/#pydantic_ai.tools.ToolKind "ToolKind



      module-attribute
   \(pydantic_ai.tools.ToolKind\)") = field[](https://docs.python.org/3/library/dataclasses.html#dataclasses.field "dataclasses.field")(default='function')

```

The kind of tool:
  * `'function'`: a tool that will be executed by Pydantic AI during an agent run and has its result returned to the model
  * `'output'`: a tool that passes through an output value that ends the run
  * `'external'`: a tool whose result will be produced outside of the Pydantic AI agent run in which it was called, because it depends on an upstream service (or user) or could take longer to generate than it's reasonable to keep the agent process running. See the [tools documentation](https://ai.pydantic.dev/deferred-tools/#deferred-tools) for more info.
  * `'unapproved'`: a tool that requires human-in-the-loop approval. See the [tools documentation](https://ai.pydantic.dev/deferred-tools/#human-in-the-loop-tool-approval) for more info.


####  metadata `class-attribute` `instance-attribute`
```
metadata: dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None = None

```

Tool metadata that can be set by the toolset this tool came from. It is not sent to the model, but can be used for filtering and tool behavior customization.
For MCP tools, this contains the `meta`, `annotations`, and `output_schema` fields from the tool definition.
####  timeout `class-attribute` `instance-attribute`
```
timeout: float[](https://docs.python.org/3/library/functions.html#float) | None = None

```

Timeout in seconds for tool execution.
If the tool takes longer than this, a retry prompt is returned to the model. Defaults to None (no timeout).
####  defer `property`
```
defer: bool[](https://docs.python.org/3/library/functions.html#bool)

```

Whether calls to this tool will be deferred.
See the [tools documentation](https://ai.pydantic.dev/deferred-tools/#deferred-tools) for more info.
© Pydantic Services Inc. 2024 to present
