> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & MCP

> Python API reference for Tools & MCP.

Give an agent capabilities beyond conversation: define function tools it can call,
connect MCP servers to expose external tools, and handle DTMF and voicemail on
telephony calls.

## function\_tool

```python theme={null}
def function_tool(func: 'Optional[Callable]' = None, *, name: 'Optional[str]' = None, filler: 'Optional[str]' = None, filler_grace_period: 'int' = 300)
```

Decorate a callable to register it as a function tool.

Attaches a `FunctionToolInfo` to the callable, deriving the tool
description from its docstring and a JSON parameters schema from its
signature and type hints. May be used directly (`@function_tool`) or
with keyword arguments (`@function_tool(name=...)`).

<ParamField path="func" type="Optional[Callable]">
  The callable to decorate. When omitted, a decorator is returned so the function can be applied with arguments.
</ParamField>

<ParamField path="name" type="Optional[str]">
  Tool name to expose. Defaults to the callable's `__name__`.
</ParamField>

<ParamField path="filler" type="Optional[str]">
  Optional filler text associated with the tool.
</ParamField>

<ParamField path="filler_grace_period" type="int" default="300">
  Grace period, in seconds, for the filler.
</ParamField>

<ResponseField name="returns">
  The decorated callable with a `_tool_info` attribute when `func` is provided, otherwise a decorator that applies the same wrapping.
</ResponseField>

***

## is\_function\_tool

```python theme={null}
def is_function_tool(obj: 'Any') -> 'bool'
```

Check whether an object is a registered function tool.

<ParamField path="obj" type="Any" required>
  The object to inspect.
</ParamField>

<ResponseField name="returns" type="bool">
  `True` if the object has a `_tool_info` attribute that is a `FunctionToolInfo` instance, `False` otherwise.
</ResponseField>

***

## get\_tool\_info

```python theme={null}
def get_tool_info(tool: 'FunctionTool') -> 'FunctionToolInfo'
```

Return the tool metadata attached to a function tool.

<ParamField path="tool" type="FunctionTool" required>
  A function tool created with `function_tool`.
</ParamField>

<ResponseField name="returns" type="FunctionToolInfo">
  The `FunctionToolInfo` associated with the tool.
</ResponseField>

***

## FunctionTool

Protocol for callables registered as function tools.

A function tool is a callable that carries a `_tool_info` attribute
describing its metadata, allowing it to be exposed to a model for
function calling.

### Constructor

```python theme={null}
FunctionTool(*args, **kwargs)
```

***

## FunctionToolInfo

Metadata describing a function tool.

### Fields

<ParamField path="name" type="str" required>
  The tool's exposed name.
</ParamField>

<ParamField path="description" type="str | None">
  Human-readable description, typically derived from the callable's docstring.
</ParamField>

<ParamField path="parameters_schema" type="Optional[dict]">
  JSON schema describing the tool's parameters.
</ParamField>

<ParamField path="filler" type="Optional[str]">
  Optional filler text associated with the tool.
</ParamField>

<ParamField path="filler_grace_period" type="int" default="300">
  Grace period, in seconds, for the filler.
</ParamField>

***

## ToolChoice

Strategies controlling whether and how the model calls tools.

```python theme={null}
class ToolChoice(Enum):
    AUTO = 'auto'
    NONE = 'none'
    REQUIRED = 'required'
```

***

## build\_openai\_schema

```python theme={null}
def build_openai_schema(tool: 'FunctionTool') -> 'dict[str, Any]'
```

Build an OpenAI-compatible function tool schema.

<ParamField path="tool" type="FunctionTool" required>
  A function tool created with `function_tool`.
</ParamField>

<ResponseField name="returns" type="dict[str, Any]">
  A dictionary describing the tool in OpenAI's function-calling format, containing the tool name, description, and parameters schema.
</ResponseField>

***

## build\_gemini\_schema

```python theme={null}
def build_gemini_schema(tool: 'FunctionTool') -> 'dict[str, Any]'
```

Build a Gemini-compatible function tool schema.

The parameters schema is simplified to remove keys that Gemini does not
accept, such as `additionalProperties`, `title`, and definition blocks.

<ParamField path="tool" type="FunctionTool" required>
  A function tool created with `function_tool`.
</ParamField>

<ResponseField name="returns" type="dict[str, Any]">
  A dictionary describing the tool with its name, description, and a cleaned parameters schema.
</ResponseField>

***

## build\_nova\_sonic\_schema

```python theme={null}
def build_nova_sonic_schema(tool: 'FunctionTool') -> 'dict[str, Any]'
```

Build a Nova Sonic-compatible function tool schema.

Nova Sonic uses the same format as OpenAI, so this delegates to
`build_openai_schema`.

<ParamField path="tool" type="FunctionTool" required>
  A function tool created with `function_tool`.
</ParamField>

<ResponseField name="returns" type="dict[str, Any]">
  A dictionary describing the tool in OpenAI's function-calling format.
</ResponseField>

***

## MCPServerStdio

Configuration for an MCP server launched as a local subprocess.

Describes how to start a Model Context Protocol server over standard
input/output by running a command with optional arguments and environment
variables.

### Constructor

```python theme={null}
MCPServerStdio(command: 'str', args: 'List[str] | None' = None, env: 'Dict[str, str] | None' = None, **kwargs)
```

<ParamField path="command" type="str" required>
  Executable used to launch the MCP server process.
</ParamField>

<ParamField path="args" type="List[str] | None">
  Command-line arguments passed to the executable. Defaults to an empty list when not provided.
</ParamField>

<ParamField path="env" type="Dict[str, str] | None">
  Environment variables for the server process. Defaults to an empty mapping when not provided.
</ParamField>

***

## MCPServerHTTP

Configuration for an MCP server reachable over HTTP.

Describes how to connect to a Model Context Protocol server at a remote
URL, optionally sending custom request headers.

### Constructor

```python theme={null}
MCPServerHTTP(url: 'str', headers: 'Dict[str, str] | None' = None, **kwargs)
```

<ParamField path="url" type="str" required>
  Endpoint URL of the MCP server.
</ParamField>

<ParamField path="headers" type="Dict[str, str] | None">
  HTTP headers sent with each request, such as authentication credentials. Defaults to an empty mapping when not provided.
</ParamField>

***

## DTMFHandler

Registers and dispatches callbacks for received DTMF input.

Maintains handlers for individual digits and for digit sequences, invoking
the matching callback as DTMF events arrive. A rolling buffer of recent
digits is kept to detect registered sequences.

### Constructor

```python theme={null}
DTMFHandler(**kwargs: 'Any') -> 'None'
```

### on\_digit

```python theme={null}
def on_digit(self, digit: 'str', callback: 'Callable') -> 'None'
```

Register a callback invoked when a specific digit is received.

Registering a callback for a digit that already has one replaces the
previous callback. Empty digit values are ignored.

<ParamField path="digit" type="str" required>
  The single digit to listen for.
</ParamField>

<ParamField path="callback" type="Callable" required>
  Callable invoked with the received digit. May be a regular function or a coroutine function.
</ParamField>

### on\_sequence

```python theme={null}
def on_sequence(self, sequence: 'str', callback: 'Callable') -> 'None'
```

Register a callback invoked when a digit sequence is received.

The callback fires when the rolling buffer of recent digits ends with
the given sequence. Registering the same sequence again replaces the
previous callback. Empty sequences are ignored.

<ParamField path="sequence" type="str" required>
  The ordered string of digits to match.
</ParamField>

<ParamField path="callback" type="Callable" required>
  Callable invoked with the matched sequence. May be a regular function or a coroutine function.
</ParamField>

***

## VoiceMailDetector

Detects whether an outbound call reached voicemail.

Configures voicemail classification for outbound calls and tracks
detection state, optionally invoking a callback and triggering hangup when
voicemail is detected.

### Constructor

```python theme={null}
VoiceMailDetector(*, llm: 'Any' = None, callback: 'Optional[Callable[[dict], CallbackResult]]' = None, duration: 'float' = 2.0, custom_prompt: 'Optional[str]' = None, auto_hangup: 'bool' = False, detection_threshold: 'float' = 1.0, max_detection_seconds: 'Optional[int]' = None) -> 'None'
```

<ParamField path="llm" type="Any">
  Language model used to classify whether voicemail was reached.
</ParamField>

<ParamField path="callback" type="Optional[Callable[[dict], CallbackResult]]">
  Callable invoked with the detection event payload when voicemail is detected. May be a regular function or a coroutine function.
</ParamField>

<ParamField path="duration" type="float" default="2.0">
  Detection window in seconds. Defaults to `2.0`.
</ParamField>

<ParamField path="custom_prompt" type="Optional[str]">
  Optional prompt overriding the default classifier prompt. Stored as an empty string when not provided.
</ParamField>

<ParamField path="auto_hangup" type="bool" default="False">
  Whether to automatically hang up once voicemail is detected. Defaults to `False`.
</ParamField>

<ParamField path="detection_threshold" type="float" default="1.0">
  Confidence threshold for declaring a detection. Defaults to `1.0`.
</ParamField>

<ParamField path="max_detection_seconds" type="Optional[int]">
  Optional maximum detection duration in seconds. When provided, it overrides `duration`.
</ParamField>