# `vllm_mlx.mcp.tools`

Tool schema conversion utilities for MCP <-> OpenAI formats.

[View the complete module source at #L1-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L1-L174).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.mcp.tools
    options:
      members:
        - mcp_tool_to_openai
        - mcp_tools_to_openai
        - openai_call_to_mcp
        - format_tool_result
        - format_tool_results
        - merge_tools
        - extract_tool_calls
        - has_tool_calls
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.mcp_tool_to_openai" markdown="1">
<summary><code>vllm_mlx.mcp.tools.mcp_tool_to_openai</code> · function</summary>

```python
vllm_mlx.mcp.tools.mcp_tool_to_openai(tool: MCPTool) -> Dict[str, Any]
```

Convert MCP tool schema to OpenAI function calling format.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tool` | `MCPTool` | `yes` | `none` | MCPTool instance |

**Returns**

- Type: `Dict[str, Any]`
- Direct return expressions: `{'type': 'function', 'function': {'name': tool.full_name, 'description': tool.description, 'parameters': tool.input_sch…`

**Exceptions and behavior**

Function `mcp_tool_to_openai` returns `{'type': 'function', 'function': {'name': tool.full_name, 'description': tool.description, 'parameters': tool.input_sch…`.
No direct `raise` statement appears in this definition.

[View source #L12-L33](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L12-L33).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.mcp_tools_to_openai" markdown="1">
<summary><code>vllm_mlx.mcp.tools.mcp_tools_to_openai</code> · function</summary>

```python
vllm_mlx.mcp.tools.mcp_tools_to_openai(tools: List[MCPTool]) -> List[Dict[str, Any]]
```

Convert list of MCP tools to OpenAI format.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tools` | `List[MCPTool]` | `yes` | `none` | List of MCPTool instances |

**Returns**

- Type: `List[Dict[str, Any]]`
- Direct return expressions: `[mcp_tool_to_openai(tool) for tool in tools]`

**Exceptions and behavior**

Function `mcp_tools_to_openai` calls `mcp_tool_to_openai`; returns `[mcp_tool_to_openai(tool) for tool in tools]`.
No direct `raise` statement appears in this definition.

[View source #L36-L46](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L36-L46).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.openai_call_to_mcp" markdown="1">
<summary><code>vllm_mlx.mcp.tools.openai_call_to_mcp</code> · function</summary>

```python
vllm_mlx.mcp.tools.openai_call_to_mcp(tool_call: Dict[str, Any]) -> Tuple[str, str, Dict[str, Any]]
```

Parse OpenAI tool call back to MCP format.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tool_call` | `Dict[str, Any]` | `yes` | `none` | OpenAI tool call from model response |

**Returns**

- Type: `Tuple[str, str, Dict[str, Any]]`
- Direct return expressions: `(server_name, tool_name, arguments)`

**Exceptions and behavior**

Function `openai_call_to_mcp` calls `tool_call.get`, `function.get`, `isinstance`, `json.loads`; returns `(server_name, tool_name, arguments)`.
No direct `raise` statement appears in this definition.

[View source #L49-L84](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L49-L84).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.format_tool_result" markdown="1">
<summary><code>vllm_mlx.mcp.tools.format_tool_result</code> · function</summary>

```python
vllm_mlx.mcp.tools.format_tool_result(result: MCPToolResult, tool_call_id: str) -> Dict[str, Any]
```

Format tool result for inclusion in conversation messages.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `result` | `MCPToolResult` | `yes` | `none` | MCPToolResult from tool execution |
| `tool_call_id` | `str` | `yes` | `none` | ID of the tool call this is responding to |

**Returns**

- Type: `Dict[str, Any]`
- Direct return expressions: `result.to_message(tool_call_id)`

**Exceptions and behavior**

Function `format_tool_result` calls `result.to_message`; returns `result.to_message(tool_call_id)`.
No direct `raise` statement appears in this definition.

[View source #L87-L98](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L87-L98).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.format_tool_results" markdown="1">
<summary><code>vllm_mlx.mcp.tools.format_tool_results</code> · function</summary>

```python
vllm_mlx.mcp.tools.format_tool_results(results: List[Tuple[MCPToolResult, str]]) -> List[Dict[str, Any]]
```

Format multiple tool results as messages.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `results` | `List[Tuple[MCPToolResult, str]]` | `yes` | `none` | List of (MCPToolResult, tool_call_id) tuples |

**Returns**

- Type: `List[Dict[str, Any]]`
- Direct return expressions: `[format_tool_result(result, call_id) for result, call_id in results]`

**Exceptions and behavior**

Function `format_tool_results` calls `format_tool_result`; returns `[format_tool_result(result, call_id) for result, call_id in results]`.
No direct `raise` statement appears in this definition.

[View source #L101-L113](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L101-L113).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.merge_tools" markdown="1">
<summary><code>vllm_mlx.mcp.tools.merge_tools</code> · function</summary>

```python
vllm_mlx.mcp.tools.merge_tools(mcp_tools: List[MCPTool], user_tools: Optional[List[Dict[str, Any]]] = None) -> List[Dict[str, Any]]
```

Merge MCP tools with user-provided tools.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mcp_tools` | `List[MCPTool]` | `yes` | `none` | Tools discovered from MCP servers |
| `user_tools` | `Optional[List[Dict[str, Any]]]` | `no` | `None` | User-provided tools in OpenAI format |

**Returns**

- Type: `List[Dict[str, Any]]`
- Direct return expressions: `list(all_tools.values())`

**Exceptions and behavior**

Function `merge_tools` calls `mcp_tool_to_openai`, `tool.get`, `func.get`, `list`; returns `list(all_tools.values())`.
No direct `raise` statement appears in this definition.

[View source #L116-L143](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L116-L143).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.extract_tool_calls" markdown="1">
<summary><code>vllm_mlx.mcp.tools.extract_tool_calls</code> · function</summary>

```python
vllm_mlx.mcp.tools.extract_tool_calls(response: Dict[str, Any]) -> List[Dict[str, Any]]
```

Extract tool calls from model response.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `response` | `Dict[str, Any]` | `yes` | `none` | OpenAI-format model response |

**Returns**

- Type: `List[Dict[str, Any]]`
- Direct return expressions: `[]`; `message.get('tool_calls', [])`

**Exceptions and behavior**

Function `extract_tool_calls` calls `response.get`, `choices[0].get`, `message.get`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L146-L161](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L146-L161).

</details>

<details class="api-contract" id="contract-vllm_mlx.mcp.tools.has_tool_calls" markdown="1">
<summary><code>vllm_mlx.mcp.tools.has_tool_calls</code> · function</summary>

```python
vllm_mlx.mcp.tools.has_tool_calls(response: Dict[str, Any]) -> bool
```

Check if response contains tool calls.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `response` | `Dict[str, Any]` | `yes` | `none` | OpenAI-format model response |

**Returns**

- Type: `bool`
- Direct return expressions: `len(extract_tool_calls(response)) > 0`

**Exceptions and behavior**

Function `has_tool_calls` calls `len`, `extract_tool_calls`; returns `len(extract_tool_calls(response)) > 0`.
No direct `raise` statement appears in this definition.

[View source #L164-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L164-L174).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`mcp_tool_to_openai`](#contract-vllm_mlx.mcp.tools.mcp_tool_to_openai) | function | `mcp_tool_to_openai(tool: MCPTool) -> Dict[str, Any]` | Convert MCP tool schema to OpenAI function calling format. | [#L12-L33](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L12-L33) |
| [`mcp_tools_to_openai`](#contract-vllm_mlx.mcp.tools.mcp_tools_to_openai) | function | `mcp_tools_to_openai(tools: List[MCPTool]) -> List[Dict[str, Any]]` | Convert list of MCP tools to OpenAI format. | [#L36-L46](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L36-L46) |
| [`openai_call_to_mcp`](#contract-vllm_mlx.mcp.tools.openai_call_to_mcp) | function | `openai_call_to_mcp(tool_call: Dict[str, Any]) -> Tuple[str, str, Dict[str, Any]]` | Parse OpenAI tool call back to MCP format. | [#L49-L84](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L49-L84) |
| [`format_tool_result`](#contract-vllm_mlx.mcp.tools.format_tool_result) | function | `format_tool_result(result: MCPToolResult, tool_call_id: str) -> Dict[str, Any]` | Format tool result for inclusion in conversation messages. | [#L87-L98](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L87-L98) |
| [`format_tool_results`](#contract-vllm_mlx.mcp.tools.format_tool_results) | function | `format_tool_results(results: List[Tuple[MCPToolResult, str]]) -> List[Dict[str, Any]]` | Format multiple tool results as messages. | [#L101-L113](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L101-L113) |
| [`merge_tools`](#contract-vllm_mlx.mcp.tools.merge_tools) | function | `merge_tools(mcp_tools: List[MCPTool], user_tools: Optional[List[Dict[str, Any]]] = None) -> List[Dict[str, Any]]` | Merge MCP tools with user-provided tools. | [#L116-L143](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L116-L143) |
| [`extract_tool_calls`](#contract-vllm_mlx.mcp.tools.extract_tool_calls) | function | `extract_tool_calls(response: Dict[str, Any]) -> List[Dict[str, Any]]` | Extract tool calls from model response. | [#L146-L161](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L146-L161) |
| [`has_tool_calls`](#contract-vllm_mlx.mcp.tools.has_tool_calls) | function | `has_tool_calls(response: Dict[str, Any]) -> bool` | Check if response contains tool calls. | [#L164-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/mcp/tools.py#L164-L174) |