# pydantic\_ai.tools

### RunContext

**Bases:** `Generic[RunContextAgentDepsT]`

Information about the current call.

#### Attributes

##### deps

Dependencies for the agent.

**Type:** `RunContextAgentDepsT`

##### model

The model used in this run.

**Type:** `Model`

##### usage

LLM usage associated with the run.

**Type:** [`RunUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RunUsage)

##### agent

The agent running this context, or `None` if not set.

**Type:** [`Agent`](/docs/ai/api/pydantic-ai/agent/#pydantic_ai.agent.Agent)\[`RunContextAgentDepsT`, [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `field(default=None, repr=False)`

##### prompt

The original user prompt passed to the run.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\[`_messages.UserContent`\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### messages

Messages exchanged in the conversation so far.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[`_messages.ModelMessage`\] **Default:** `field(default_factory=(list[_messages.ModelMessage]))`

##### validation\_context

Pydantic [validation context](https://docs.pydantic.dev/latest/concepts/validators/#validation-context) for tool args and run outputs.

**Type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) **Default:** `None`

##### tracer

The tracer to use for tracing the run.

**Type:** `Tracer` **Default:** `field(default_factory=NoOpTracer)`

##### trace\_include\_content

Whether to include the content of the messages in the trace.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) **Default:** `False`

##### instrumentation\_version

Instrumentation settings version, if instrumentation is enabled.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `DEFAULT_INSTRUMENTATION_VERSION`

##### retries

Number of retries for each tool so far.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`int`](https://docs.python.org/3/library/functions.html#int)\] **Default:** `field(default_factory=(dict[str, int]))`

##### tool\_call\_id

The ID of the tool call.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### tool\_name

Name of the tool being called.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### retry

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.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0`

##### max\_retries

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.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0`

##### run\_step

The current step in the run.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0`

##### tool\_call\_approved

Whether a tool call that required approval has now been approved.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) **Default:** `False`

##### tool\_call\_metadata

Metadata from `DeferredToolResults.metadata[tool_call_id]`, available when `tool_call_approved=True`.

**Type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) **Default:** `None`

##### partial\_output

Whether the output passed to an output validator is partial.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) **Default:** `False`

##### run\_id

"Unique identifier for the agent run.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### conversation\_id

Unique identifier for the conversation this run belongs to.

A conversation spans potentially multiple agent runs that share message history. Resolved at the start of `Agent.run` (etc.) from the explicit `conversation_id` argument, the most recent `conversation_id` on `message_history`, or a fresh UUID7.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### metadata

Metadata associated with this agent run, if configured.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### model\_settings

The resolved model settings for the current run step.

Populated before each model request, after all model settings layers (model defaults, agent-level, capability, and run-level) have been merged. Available in model request hooks (`before_model_request`, `wrap_model_request`, `after_model_request`). Currently `None` in tool hooks, output validators, and during agent construction.

**Type:** [`ModelSettings`](/docs/ai/api/pydantic-ai/settings/#pydantic_ai.settings.ModelSettings) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### pending\_messages

Internal: queue read and mutated by `PendingMessageDrainCapability`.

Set to the run's live queue during an agent run; `None` in synthetic contexts that aren't backed by a running agent (e.g. the `RunContext` built by `Agent.system_prompt_parts`), where [`enqueue`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.enqueue) would have nowhere to drain to and so raises. Use [`enqueue`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.enqueue) to add messages -- don't append directly.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[`PendingMessage`\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `field(default=None, repr=False)`

##### tool\_manager

The tool manager for the current run step.

Provides access to tool validation and execution, including tracing and capability hooks. Useful for toolsets that need to dispatch tool calls programmatically (e.g. code execution sandboxes).

Not available in `TemporalRunContext` -- it is not serializable across Temporal activity boundaries.

**Type:** `ToolManager`\[`RunContextAgentDepsT`\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### capabilities

All capabilities registered for the current run, including deferred ones.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), `AbstractCapability`\[`RunContextAgentDepsT`\]\] **Default:** `field(default_factory=(lambda: {}))`

##### loaded\_capability\_ids

IDs of the deferred capabilities the model has explicitly loaded via the `load_capability` tool.

The capability-side mirror of `discovered_tool_names`: the runtime-revealed subset. Seeded during run preparation from message history (`parse_loaded_capabilities`); the `load_capability` tool body adds to it for in-step loads. Use `available_capability_ids` for the full set of currently-active capabilities (auto/always-on plus these).

**Type:** [`set`](https://docs.python.org/3/reference/expressions.html#set)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)\] **Default:** `field(default_factory=(set[str]))`

##### capability\_loaded

Whether the capability whose hook or callback is currently running is loaded.

This is `None` outside capability dispatch, where there is no current capability.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### discovered\_tool\_names

Names of deferred tools revealed via tool-search return parts in the message history.

The tool-side mirror of `loaded_capability_ids`: the runtime-revealed subset that `ToolSearchToolset.get_tools` reads to decide which deferred tools to make visible this turn. Populated during run preparation from message history. Use `available_tool_names` for the full set of currently-callable tools (always-visible plus these).

**Type:** [`set`](https://docs.python.org/3/reference/expressions.html#set)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)\] **Default:** `field(default_factory=(set[str]))`

##### last\_attempt

Whether this is the last attempt at running this tool before an error is raised.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

##### available\_capability\_ids

IDs of the capabilities whose contributions are live to the model right now.

The capability-side mirror of `available_tool_names`: `available = auto/always ∪ runtime-revealed`. Here that's the non-deferred capabilities (`defer_loading` not `True`) plus the deferred ones the model has loaded (`loaded_capability_ids`), so `available_capability_ids - loaded_capability_ids` is the auto/always-on subset.

Distinct from `capabilities`, the full registry (including deferred ones not yet loaded). See `loaded_capability_ids` for the runtime-revealed subset.

Reliable from `before_run` onwards: the `capabilities` registry is seeded once at run start, and `loaded_capability_ids` is refreshed from history before each model request, so the loaded subset grows across steps as the model loads capabilities. Because it grows step by step, where you read it in the [hook order](/docs/ai/core-concepts/hooks#hook-ordering) determines what you see -- e.g. a capability loaded during one step is not reflected until the next step's hooks.

**Type:** [`set`](https://docs.python.org/3/reference/expressions.html#set)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)\]

##### available\_tool\_names

Names of function tools the model can call on the current turn.

The visible subset of [`tools`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.tools): always-visible tools, tools revealed via [tool search](/docs/ai/tools-toolsets/tools-advanced#tool-search), and tools owned by loaded deferred capabilities.

Only fully populated once the turn's tools have been resolved during model-request preparation, so it is reliable in model-request hooks (`before_model_request`, `wrap_model_request`, `after_model_request`) and tool hooks. In earlier hooks like `before_run` it falls back to `discovered_tool_names` (reconstructed from history). See [hook ordering](/docs/ai/core-concepts/hooks#hook-ordering) for how timing affects what you see.

**Type:** [`set`](https://docs.python.org/3/reference/expressions.html#set)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)\]

##### tools

All tool definitions present this turn, keyed by name (includes still-deferred ones). Index `available_tool_names` into this for the callable subset.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`ToolDefinition`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition)\]

#### Methods

##### enqueue

```python
def enqueue(
    content: EnqueueContent = (),
    priority: PendingMessagePriority = 'asap',
) -> None
```

Enqueue content to be injected into the conversation.

Safe to call from anywhere a `RunContext` is available -- async tools, sync tools (auto-wrapped in a thread executor by Pydantic AI), and capability hooks. The drain only iterates the queue between graph nodes (in `before_model_request` and `after_node_run`), never concurrently with the tool body, so `list.append` from a worker thread doesn't race the drain.

###### Returns

[`None`](https://docs.python.org/3/library/constants.html#None)

###### Parameters

**`*content`** : `EnqueueContent` _Default:_ `()`

One or more `EnqueueContent` items. Adjacent `UserContent` (a `str` or multi-modal content like an [`ImageUrl`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ImageUrl)) is gathered into one [`UserPromptPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.UserPromptPart), and each [`ModelRequestPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelRequestPart) (e.g. a [`SystemPromptPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.SystemPromptPart)) is coalesced with adjacent part-style items into one [`ModelRequest`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelRequest); a complete [`ModelRequest`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelRequest) or [`ModelResponse`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ModelResponse) is kept as its own message. The assembled sequence must end in a request. Calling with no positional args is a no-op.

**`priority`** : `PendingMessagePriority` _Default:_ `'asap'`

When to deliver: `'asap'` (default) -- at the earliest opportunity (next model request, or a redirect if the agent would otherwise end). `'when_idle'` -- only when the agent would otherwise end, after `'asap'` messages.

###### Raises

-   `UserError` -- If this `RunContext` isn't backed by a running agent's queue (e.g. the synthetic context from `Agent.system_prompt_parts`), since there'd be nowhere to deliver the message.

### 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`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.DeferredToolResults) object with the same tool call IDs.

See [deferred tools docs](/docs/ai/tools-toolsets/deferred-tools#deferred-tools) for more information.

#### Attributes

##### calls

Tool calls that require external execution.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart)\] **Default:** `field(default_factory=(list[ToolCallPart]))`

##### approvals

Tool calls that require human-in-the-loop approval.

**Type:** [`list`](https://docs.python.org/3/glossary.html#term-list)\[[`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart)\] **Default:** `field(default_factory=(list[ToolCallPart]))`

##### metadata

Metadata for deferred tool calls, keyed by `tool_call_id`.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\]\] **Default:** `field(default_factory=(dict[str, dict[str, Any]]))`

#### Methods

##### build\_results

```python
def build_results(
    approvals: dict[str, bool | DeferredToolApprovalResult] | None = None,
    calls: dict[str, DeferredToolCallResult | Any] | None = None,
    metadata: dict[str, dict[str, Any]] | None = None,
    approve_all: bool = False,
) -> DeferredToolResults
```

Create a [`DeferredToolResults`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.DeferredToolResults) for these requests.

###### Returns

[`DeferredToolResults`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.DeferredToolResults)

###### Parameters

**`approvals`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`bool`](https://docs.python.org/3/library/functions.html#bool) | `DeferredToolApprovalResult`\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Results for tool calls that required approval. Keys must match `tool_call_id`s in `self.approvals`.

**`calls`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), `DeferredToolCallResult` | [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Results for tool calls that required external execution. Keys must match `tool_call_id`s in `self.calls`.

**`metadata`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\]\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Per-call metadata, keyed by `tool_call_id`.

**`approve_all`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

If `True`, every approval-requesting call not already listed in `approvals` is approved (with default `ToolApproved()`).

###### Raises

-   `ValueError` -- If a key in `approvals`/`calls` doesn't match a pending request of the appropriate kind.

##### remaining

```python
def remaining(results: DeferredToolResults) -> DeferredToolRequests | None
```

Return unresolved requests after applying results, or `None` if all resolved.

###### Returns

[`DeferredToolRequests`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.DeferredToolRequests) | [`None`](https://docs.python.org/3/library/constants.html#None)

### ToolApproved

Indicates that a tool call has been approved and that the tool function should be executed.

#### Attributes

##### override\_args

Optional tool call arguments to use instead of the original arguments.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

### ToolDenied

Indicates that a tool call has been denied and that a denial message should be returned to the model.

#### Attributes

##### message

The message to return to the model.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `'The tool call was denied.'`

### 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`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.DeferredToolRequests) output object from the previous run.

See [deferred tools docs](/docs/ai/tools-toolsets/deferred-tools#deferred-tools) for more information.

#### Attributes

##### calls

Map of tool call IDs to results for tool calls that required external execution.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), `DeferredToolCallResult` | [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] **Default:** `field(default_factory=(dict[str, DeferredToolCallResult | Any]))`

##### approvals

Map of tool call IDs to results for tool calls that required human-in-the-loop approval.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`bool`](https://docs.python.org/3/library/functions.html#bool) | `DeferredToolApprovalResult`\] **Default:** `field(default_factory=(dict[str, bool | DeferredToolApprovalResult]))`

##### metadata

Metadata for deferred tool calls, keyed by `tool_call_id`. Each value will be available in the tool's RunContext as `tool_call_metadata`.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\]\] **Default:** `field(default_factory=(dict[str, dict[str, Any]]))`

#### Methods

##### update

```python
def update(other: DeferredToolResults) -> None
```

Update this `DeferredToolResults` with entries from another, in-place.

###### Returns

[`None`](https://docs.python.org/3/library/constants.html#None)

##### to\_tool\_call\_results

```python
def to_tool_call_results() -> dict[str, DeferredToolResult]
```

Convert results into the internal per-call format used by the tool-execution pipeline.

Normalizes `True`/`False` approvals to `ToolApproved`/`ToolDenied`, and wraps plain external-call values in `ToolReturn`.

###### Returns

[`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), `DeferredToolResult`\]

### Tool

**Bases:** `Generic[ToolAgentDepsT]`

A tool function for an agent.

#### Attributes

##### function\_schema

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.

**Type:** `_function_schema.FunctionSchema` **Default:** `function_schema or _function_schema.function_schema(function, schema_generator, tool_name=(self.name), takes_ctx=takes_ctx, docstring_format=docstring_format, require_parameter_descriptions=require_parameter_descriptions)`

#### Methods

##### \_\_init\_\_

```python
def __init__(
    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,
    defer_loading: bool = False,
    include_return_schema: bool | None = None,
    function_schema: _function_schema.FunctionSchema | None = None,
)
```

Create a new tool instance.

Example usage:

```python
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

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

**`function`** : `ToolFuncEither`\[`ToolAgentDepsT`, `ToolParams`\]

The Python function to call as the tool.

**`takes_ctx`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Whether the function takes a [`RunContext`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext) first argument, this is inferred if unset.

**`max_retries`** : [`int`](https://docs.python.org/3/library/functions.html#int) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Maximum number of retries allowed for this tool, set to the agent default if `None`.

**`name`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Name of the tool, inferred from the function if `None`.

**`description`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Description of the tool, inferred from the function if `None`.

**`prepare`** : `ToolPrepareFunc`\[`ToolAgentDepsT`\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `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`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolPrepareFunc).

**`args_validator`** : `ArgsValidatorFunc`\[`ToolAgentDepsT`, `ToolParams`\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `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`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.ModelRetry) on validation failure, return `None` on success. See [`ArgsValidatorFunc`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ArgsValidatorFunc).

**`docstring_format`** : `DocstringFormat` _Default:_ `'auto'`

The format of the docstring, see [`DocstringFormat`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.DocstringFormat). Defaults to `'auto'`, such that the format is inferred from the structure of the docstring.

**`require_parameter_descriptions`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

If True, raise an error if a parameter description is missing. Defaults to False.

**`schema_generator`** : [`type`](https://docs.python.org/3/glossary.html#term-type)\[`GenerateJsonSchema`\] _Default:_ `GenerateToolJsonSchema`

The JSON schema generator class to use. Defaults to `GenerateToolJsonSchema`.

**`strict`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Whether to enforce JSON schema compliance (only affects OpenAI). See [`ToolDefinition`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition) for more info.

**`sequential`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

Whether the function requires a sequential/serial execution environment. Defaults to False.

**`requires_approval`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

Whether this tool requires human-in-the-loop approval. Defaults to False. See the [tools documentation](/docs/ai/tools-toolsets/deferred-tools#human-in-the-loop-tool-approval) for more info.

**`metadata`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.

**`timeout`** : [`float`](https://docs.python.org/3/library/functions.html#float) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `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).

**`defer_loading`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

Whether to hide this tool until it's discovered via tool search. Defaults to False. See [Tool Search](/docs/ai/tools-toolsets/tools-advanced#tool-search) for more info.

**`include_return_schema`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

Whether to include the return schema in the tool definition sent to the model. If `None`, defaults to `False` unless the [`IncludeToolReturnSchemas`](/docs/ai/api/pydantic-ai/capabilities/#pydantic_ai.capabilities.IncludeToolReturnSchemas) capability is used.

**`function_schema`** : `_function_schema.FunctionSchema` | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None`

The function schema to use for the tool. If not provided, it will be generated.

##### from\_schema

`@classmethod`

```python
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.

###### Returns

[`Self`](https://docs.python.org/3/library/typing.html#typing.Self) -- A Pydantic tool that calls the function

###### Parameters

**`function`** : [`Callable`](https://docs.python.org/3/library/typing.html#typing.Callable)\[..., [`Any`](https://docs.python.org/3/library/typing.html#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.

**`name`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str)

The unique name of the tool that clearly communicates its purpose

**`description`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#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.

**`json_schema`** : `JsonSchemaValue`

The schema for the function arguments

**`takes_ctx`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

An optional boolean parameter indicating whether the function accepts the context object as an argument.

**`sequential`** : [`bool`](https://docs.python.org/3/library/functions.html#bool) _Default:_ `False`

Whether the function requires a sequential/serial execution environment. Defaults to False.

**`args_validator`** : `ArgsValidatorFunc`\[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any), ...\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `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`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.ModelRetry) on validation failure, return `None` on success. See [`ArgsValidatorFunc`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ArgsValidatorFunc).

##### prepare\_tool\_def

`@async`

```python
def prepare_tool_def(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

[`ToolDefinition`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition) | [`None`](https://docs.python.org/3/library/constants.html#None) -- return a `ToolDefinition` or `None` if the tools should not be registered for this run.

### ToolDefinition

Definition of a tool passed to a model.

This is used for both function tools and output tools.

#### Attributes

##### name

The name of the tool.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str)

##### parameters\_json\_schema

The JSON schema for the tool's parameters.

**Type:** `ObjectJsonSchema` **Default:** `field(default_factory=(lambda: {'type': 'object', 'properties': {}}))`

##### description

The description of the tool.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### outer\_typed\_dict\_key

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.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### strict

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.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### sequential

Whether this tool requires a sequential/serial execution environment.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) **Default:** `False`

##### kind

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](/docs/ai/tools-toolsets/deferred-tools#deferred-tools) for more info.
-   `'unapproved'`: a tool that requires human-in-the-loop approval. See the [tools documentation](/docs/ai/tools-toolsets/deferred-tools#human-in-the-loop-tool-approval) for more info.

**Type:** `ToolKind` **Default:** `field(default='function')`

##### metadata

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` and `annotations` fields from the tool definition, as well as a `task` flag indicating whether the server declares support for task-augmented execution.

**Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### timeout

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

**Type:** [`float`](https://docs.python.org/3/library/functions.html#float) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### defer\_loading

Whether this tool should be hidden from the model until something explicitly surfaces it.

Carries two meanings depending on where in the pipeline you observe it:

1.  **User-input intent** -- set on `Tool(defer_loading=True)` (or via a custom toolset) to opt this tool into deferred loading. This is what `prepare_tools` hooks and other pre-toolset-wrapping consumers see, and is the value users persist on `ToolDefinition`.
2.  **Current visibility state** -- after a toolset like `ToolSearchToolset` processes the corpus, it flips this field to `False` for tools whose discovery shows up in message history, so downstream `Model.prepare_request` filtering and adapter wire formatting can read "should this be on the wire?" off a single boolean.

The dual meaning is acknowledged tech debt: a future `RunContext.loaded_tools` / equivalent will surface (2) as a derived view so this field cleanly stays a user-input flag. Until then, the toolset-set value flows through agent-graph plumbing on a per-step `ToolDefinition` instance built via `replace(...)`; user-persisted definitions are not mutated.

See [Tool Search](/docs/ai/tools-toolsets/tools-advanced#tool-search) for more info.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) **Default:** `False`

##### unless\_native

If set, this tool is dropped from the wire when the named native tool is supported by the model.

Generic version of the old `prefer_builtin` flag: a function tool carrying `unless_native='web_search'` is treated as a local fallback for the [`WebSearchTool`](/docs/ai/api/pydantic-ai/native_tools/#pydantic_ai.native_tools.WebSearchTool) native tool and silently removed from the request whenever the model handles `WebSearchTool` natively. It stays in the request when the native tool isn't supported.

**Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None), `Field`(`validation_alias`\=(`AliasChoices`(`unless_native`, `prefer_native`, `prefer_builtin`)))\] **Default:** `None`

##### with\_native

If set, this tool is kept on the wire when the named native tool is supported, with the native tool's adapter applying any wire-format adjustments (e.g. setting `defer_loading=True` on the request param for the framework-managed tool-search native tool).

Symmetric pair with `unless_native`:

-   `unless_native='X'` -- drop me from the wire when X is supported (local fallback).
-   `with_native='X'` -- keep me on the wire when X is supported, formatted via X's adapter (corpus member managed by the native tool).

When the named native tool is unsupported, a tool with `with_native` and `defer_loading=True` is dropped (the corpus member is currently undiscovered, so the model can't call it on this provider); otherwise it's kept as a regular function tool.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### tool\_kind

Discriminator for a cross-provider typed call/return shape (e.g. `'tool-search'`).

Set by the framework when a tool emits parts that should be promoted to a typed subclass (such as `ToolSearchCallPart` and `ToolSearchReturnPart`). Leave as `None` for user-defined function tools -- they go through the standard [`ToolCallPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolCallPart) / [`ToolReturnPart`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.ToolReturnPart) shapes.

To detect a tool-search part regardless of execution path (native server-side vs. local fallback), check `part.tool_kind == 'tool-search'` -- this works across both call/return and both server/local variants.

Distinct from [`kind`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition.kind), which is about invocation semantics (`'function'` / `'output'` / `'external'` / `'unapproved'`).

**Type:** `ToolPartKind` | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### return\_schema

The JSON schema for the tool's return value.

For models that natively support return schemas (e.g. Google Gemini), this is passed as a structured field in the API request. For other models, it is injected into the tool's description as JSON text. Only included when `include_return_schema` resolves to `True`.

**Type:** `ObjectJsonSchema` | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### include\_return\_schema

Whether to include the return schema in the tool definition sent to the model.

When `True`, the `return_schema` will be preserved and sent to the model. When `False`, the `return_schema` will be cleared before sending. When `None` (default), defaults to `False` unless the [`IncludeToolReturnSchemas`](/docs/ai/api/pydantic-ai/capabilities/#pydantic_ai.capabilities.IncludeToolReturnSchemas) capability is used.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### capability\_id

The id of the capability that contributed this tool, or `None` if the tool is not owned by a capability.

Assigned once when the run's capabilities are set up and then carried on the `ToolDefinition` for the rest of that run -- it does not change or reset between steps. For a tool owned by a deferred capability it gates visibility: the tool is revealed once that capability's id appears in [`RunContext.loaded_capability_ids`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.loaded_capability_ids).

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `None`

##### function\_signature

The function signature shape for this tool.

Lazily computed from `parameters_json_schema` and `return_schema` on first access. Name and description are not stored on the signature -- pass them at render time via `sig.render(body, name=td.name, description=td.description)`.

**Type:** `FunctionSignature`

##### defer

Whether calls to this tool will be deferred.

See the [tools documentation](/docs/ai/tools-toolsets/deferred-tools#deferred-tools) for more info.

**Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool)

#### Methods

##### render\_signature

```python
def render_signature(body: str, kwargs: Any = {}) -> str
```

Render the function signature with this tool's name and description.

Convenience wrapper around `self.function_signature.render()` that supplies `name` and `description` from this tool definition.

###### Returns

[`str`](https://docs.python.org/3/library/stdtypes.html#str)

### matches\_tool\_selector

`@async`

```python
def matches_tool_selector(
    selector: ToolSelector[AgentDepsT],
    ctx: RunContext[AgentDepsT],
    tool_def: ToolDefinition,
) -> bool
```

Check whether a tool definition matches a [`ToolSelector`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolSelector).

#### Returns

[`bool`](https://docs.python.org/3/library/functions.html#bool) -- `True` if the tool matches the selector.

#### Parameters

**`selector`** : `ToolSelector`\[`AgentDepsT`\]

The selector to check against.

**`ctx`** : [`RunContext`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext)\[`AgentDepsT`\]

The current run context.

**`tool_def`** : [`ToolDefinition`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition)

The tool definition to test.

### AgentDepsT

Type variable for agent dependencies.

**Default:** `TypeVar('AgentDepsT', default=None, contravariant=True)`

### ToolParams

Retrieval function param spec.

**Default:** `ParamSpec('ToolParams', default=...)`

### SystemPromptFunc

A function that may or may 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]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[[RunContext[AgentDepsT]], str | None] | Callable[[RunContext[AgentDepsT]], Awaitable[str | None]] | Callable[[], str | None] | Callable[[], Awaitable[str | None]]`

### ToolFuncContext

A tool function that takes `RunContext` as the first argument.

Usage `ToolContextFunc[AgentDepsT, ToolParams]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[Concatenate[RunContext[AgentDepsT], ToolParams], Any]`

### ToolFuncPlain

A tool function that does not take `RunContext` as the first argument.

Usage `ToolPlainFunc[ToolParams]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[ToolParams, Any]`

### ToolFuncEither

Either kind of tool function.

This is just a union of [`ToolFuncContext`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolFuncContext) and [`ToolFuncPlain`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolFuncPlain).

Usage `ToolFuncEither[AgentDepsT, ToolParams]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `ToolFuncContext[AgentDepsT, ToolParams] | ToolFuncPlain[ToolParams]`

### ArgsValidatorFunc

A function that validates tool arguments before execution.

The validator receives the same typed parameters as the tool function, with [`RunContext`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext) as the first argument for dependency access.

Should raise [`ModelRetry`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.ModelRetry) on validation failure.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[Concatenate[RunContext[AgentDepsT], ToolParams], Awaitable[None]] | Callable[Concatenate[RunContext[AgentDepsT], ToolParams], None]`

### ToolPrepareFunc

Definition of a function that can prepare a tool definition at call time. Both sync and async functions are accepted.

See [tool docs](/docs/ai/tools-toolsets/tools-advanced#tool-prepare) for more information.

Example -- here `only_if_42` is valid as a `ToolPrepareFunc`:

```python
from pydantic_ai import RunContext, Tool
from pydantic_ai.tools import ToolDefinition

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]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[[RunContext[AgentDepsT], 'ToolDefinition'], Union[Awaitable['ToolDefinition | None'], 'ToolDefinition', None]]`

### ToolsPrepareFunc

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. Both sync and async functions are accepted.

Example -- here `turn_on_strict_if_openai` is valid as a `ToolsPrepareFunc`:

```python
from dataclasses import replace

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


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', capabilities=[PrepareTools(turn_on_strict_if_openai)])
```

Usage `ToolsPrepareFunc[AgentDepsT]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[[RunContext[AgentDepsT], list['ToolDefinition']], Awaitable['list[ToolDefinition] | None'] | list['ToolDefinition'] | None]`

### ToolSelectorFunc

A callable that decides whether a tool matches a selection criterion.

Receives the run context and a tool definition, returns `True` if the tool is selected. Both sync and async functions are accepted.

Usage `ToolSelectorFunc[AgentDepsT]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[[RunContext[AgentDepsT], 'ToolDefinition'], bool | Awaitable[bool]]`

### ToolSelector

Specifies which tools a capability or toolset wrapper should apply to.

-   `'all'`: matches every tool (default for most capabilities).
-   `Sequence[str]`: matches tools whose names are in the sequence.
-   `dict[str, Any]`: matches tools whose [`metadata`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition.metadata) contains all the specified key-value pairs (deep inclusion check -- nested dicts are compared recursively, and the tool's metadata may have additional keys).
-   `Callable[[RunContext, ToolDefinition], bool | Awaitable[bool]]`: custom sync or async predicate.

The first three forms are serializable for use in agent specs (YAML/JSON).

Usage `ToolSelector[AgentDepsT]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['all'] | Sequence[str] | dict[str, Any] | ToolSelectorFunc[AgentDepsT]`

### NativeToolFunc

Definition of a function that can prepare a native tool at call time.

This is useful if you want to customize the native tool based on the run context (e.g. user dependencies), or omit it completely from a step.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Callable[[RunContext[AgentDepsT]], Awaitable[AbstractNativeTool | None] | AbstractNativeTool | None]`

### AgentNativeTool

A native tool or a function that dynamically produces one.

This is a convenience alias for `AbstractNativeTool | NativeToolFunc[AgentDepsT]`.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `AbstractNativeTool | NativeToolFunc[AgentDepsT]`

### DocstringFormat

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.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['google', 'numpy', 'sphinx', 'auto']`

### DeferredToolApprovalResult

Result for a tool call that required human-in-the-loop approval.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Annotated[ToolApproved | ToolDenied, Discriminator('kind')]`

### DeferredToolCallResult

Result for a tool call that required external execution.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Annotated[Annotated[ToolReturn, Tag('tool-return')] | Annotated[ModelRetry, Tag('model-retry')] | Annotated[RetryPromptPart, Tag('retry-prompt')], Discriminator(_deferred_tool_call_result_discriminator)]`

### DeferredToolResult

Result for a tool call that required approval or external execution.

**Default:** `DeferredToolApprovalResult | DeferredToolCallResult`

### ToolAgentDepsT

Type variable for agent dependencies for a tool.

**Default:** `TypeVar('ToolAgentDepsT', default=object, contravariant=True)`

### ObjectJsonSchema

Type representing JSON schema of an object, e.g. where `"type": "object"`.

This type is used to define tools parameters (aka arguments) in [ToolDefinition](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.ToolDefinition).

With PEP-728 this should be a TypedDict with `type: Literal['object']`, and `extra_parts=Any`

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `dict[str, Any]`

### ToolKind

Kind of tool.

**Type:** [`TypeAlias`](https://docs.python.org/3/library/typing.html#typing.TypeAlias) **Default:** `Literal['function', 'output', 'external', 'unapproved']`