Implementation:Openai Openai python Tool Types

Knowledge Sources	Openai_Openai_python
Domains	API_Types, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete Pydantic model definitions for tool types provided by the openai-python SDK.

Description

The tool.py module defines the Pydantic BaseModel classes for all tool types available in the OpenAI Responses API. The central type is Tool, a discriminated Union (using the type field as discriminator) of 12 tool model classes.

Primary types:

Tool -- The top-level union type alias encompassing all supported tool types: FunctionTool, FileSearchTool, ComputerTool, WebSearchTool, Mcp, CodeInterpreter, ImageGeneration, LocalShell, FunctionShellTool, CustomTool, WebSearchPreviewTool, and ApplyPatchTool.

MCP tool types:

Mcp -- Model Context Protocol tool integration. Provides access to remote MCP servers via server_url or built-in connector_id values (Dropbox, Gmail, Google Calendar, Google Drive, Microsoft Teams, Outlook Calendar, Outlook Email, SharePoint). Supports allowed_tools filtering and require_approval configuration.
McpAllowedTools -- TypeAlias: Union[List[str], McpAllowedToolsMcpToolFilter, None]. Filter for which MCP tools are available.
McpAllowedToolsMcpToolFilter -- Filter with optional tool_names list and read_only flag.
McpRequireApproval -- TypeAlias: Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None]. Controls which MCP tools need human approval.
McpRequireApprovalMcpToolApprovalFilter -- Granular approval filter with always and never sub-filters.

Code interpreter types:

CodeInterpreter -- Runs Python code. Requires a container (ID string or CodeInterpreterContainerCodeInterpreterToolAuto).
CodeInterpreterContainer -- TypeAlias: Union[str, CodeInterpreterContainerCodeInterpreterToolAuto].
CodeInterpreterContainerCodeInterpreterToolAuto -- Auto-provisioned container with optional file_ids, memory_limit ("1g", "4g", "16g", "64g"), and network_policy.

Image generation types:

ImageGeneration -- Generates images using GPT image models. Supports action ("generate", "edit", "auto"), model, size, quality, output_format, background, moderation, and more.
ImageGenerationInputImageMask -- Optional mask for inpainting with file_id or image_url.

Other types:

LocalShell -- Allows the model to execute shell commands locally. Contains only a type field.

This file is auto-generated from the OpenAI API spec by the Stainless code generation toolchain.

Usage

Use these types when working with tool definitions in API responses or when type-checking tool configuration. For constructing tool parameters in requests, use the corresponding TypedDict ToolParam variants. The Tool union is the return type used when tools are included in response objects.

Code Reference

Source Location

Repository: openai-python
File: src/openai/types/responses/tool.py
Lines: 1-321

Signature

class Mcp(BaseModel):
    server_label: str
    type: Literal["mcp"]
    allowed_tools: Optional[McpAllowedTools] = None
    authorization: Optional[str] = None
    connector_id: Optional[Literal[
        "connector_dropbox", "connector_gmail", "connector_googlecalendar",
        "connector_googledrive", "connector_microsoftteams",
        "connector_outlookcalendar", "connector_outlookemail",
        "connector_sharepoint",
    ]] = None
    headers: Optional[Dict[str, str]] = None
    require_approval: Optional[McpRequireApproval] = None
    server_description: Optional[str] = None
    server_url: Optional[str] = None

McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpToolFilter, None]

McpRequireApproval: TypeAlias = Union[
    McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None
]

class CodeInterpreter(BaseModel):
    container: CodeInterpreterContainer
    type: Literal["code_interpreter"]

class ImageGeneration(BaseModel):
    type: Literal["image_generation"]
    action: Optional[Literal["generate", "edit", "auto"]] = None
    model: Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-1.5"], None] = None
    size: Optional[Literal["1024x1024", "1024x1536", "1536x1024", "auto"]] = None
    quality: Optional[Literal["low", "medium", "high", "auto"]] = None
    output_format: Optional[Literal["png", "webp", "jpeg"]] = None
    background: Optional[Literal["transparent", "opaque", "auto"]] = None

class LocalShell(BaseModel):
    type: Literal["local_shell"]

Tool: TypeAlias = Annotated[
    Union[
        FunctionTool, FileSearchTool, ComputerTool, WebSearchTool,
        Mcp, CodeInterpreter, ImageGeneration, LocalShell,
        FunctionShellTool, CustomTool, WebSearchPreviewTool, ApplyPatchTool,
    ],
    PropertyInfo(discriminator="type"),
]

Import

from openai.types.responses.tool import (
    Tool,
    Mcp,
    McpAllowedTools,
    McpRequireApproval,
    CodeInterpreter,
    ImageGeneration,
    LocalShell,
)
# Or via the top-level re-export:
from openai.types.responses import Tool

I/O Contract

Inputs

Name	Type	Required	Description
server_label	str	Yes (Mcp)	Label identifying the MCP server in tool calls
type	Literal[...]	Yes (all tools)	Discriminator field: `"mcp"`, `"code_interpreter"`, `"image_generation"`, `"local_shell"`, etc.
server_url	Optional[str]	No (Mcp)	URL of the MCP server (one of server_url or connector_id required)
connector_id	Optional[Literal[...]]	No (Mcp)	Predefined connector identifier (e.g., `"connector_gmail"`)
allowed_tools	McpAllowedTools	No (Mcp)	Filter for which MCP tools are available (list of names or filter object)
require_approval	McpRequireApproval	No (Mcp)	Which MCP tools require human approval (`"always"`, `"never"`, or filter)
authorization	Optional[str]	No (Mcp)	OAuth access token for authenticated MCP servers
headers	Optional[Dict[str, str]]	No (Mcp)	Custom HTTP headers for MCP server requests
container	CodeInterpreterContainer	Yes (CodeInterpreter)	Container ID or auto-config with file_ids, memory_limit, network_policy
action	Optional[Literal["generate", "edit", "auto"]]	No (ImageGeneration)	Whether to generate, edit, or auto-detect
model	Union[str, Literal[...], None]	No (ImageGeneration)	Image model: `"gpt-image-1"`, `"gpt-image-1-mini"`, `"gpt-image-1.5"`
size	Optional[Literal[...]]	No (ImageGeneration)	Output size: `"1024x1024"`, `"1024x1536"`, `"1536x1024"`, `"auto"`
quality	Optional[Literal[...]]	No (ImageGeneration)	Quality: `"low"`, `"medium"`, `"high"`, `"auto"`
output_format	Optional[Literal[...]]	No (ImageGeneration)	Format: `"png"`, `"webp"`, `"jpeg"`

Outputs

Name	Type	Description
Tool	TypeAlias (Annotated Union)	Discriminated union of 12 tool Pydantic models: FunctionTool, FileSearchTool, ComputerTool, WebSearchTool, Mcp, CodeInterpreter, ImageGeneration, LocalShell, FunctionShellTool, CustomTool, WebSearchPreviewTool, ApplyPatchTool
Mcp	BaseModel	MCP remote tool integration with server config, auth, and approval settings
McpAllowedTools	TypeAlias	Filter type for allowed MCP tools (list of names or filter object)
McpRequireApproval	TypeAlias	Approval requirement type: always, never, or granular filter
CodeInterpreter	BaseModel	Python code execution tool with container configuration
ImageGeneration	BaseModel	Image generation tool with model, size, quality, and format settings
LocalShell	BaseModel	Local shell execution tool

Usage Examples

Inspecting Tool Types in a Response

from openai.types.responses.tool import Tool, Mcp, CodeInterpreter, ImageGeneration

def describe_tool(tool: Tool) -> str:
    if isinstance(tool, Mcp):
        return f"MCP tool: server={tool.server_label}, url={tool.server_url}"
    elif isinstance(tool, CodeInterpreter):
        return f"Code interpreter: container={tool.container}"
    elif isinstance(tool, ImageGeneration):
        return f"Image generation: model={tool.model}, size={tool.size}"
    return f"Tool type: {tool.type}"

Configuring MCP Tool with Approval

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="Search my Google Drive for the Q4 report.",
    tools=[
        {
            "type": "mcp",
            "server_label": "gdrive",
            "connector_id": "connector_googledrive",
            "require_approval": "always",
        }
    ],
)

Using Code Interpreter Tool

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="Calculate the first 20 Fibonacci numbers and plot them.",
    tools=[
        {
            "type": "code_interpreter",
            "container": {
                "type": "auto",
                "file_ids": [],
                "memory_limit": "4g",
            },
        }
    ],
)

Using Image Generation Tool

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="Generate an image of a sunset over mountains.",
    tools=[
        {
            "type": "image_generation",
            "model": "gpt-image-1",
            "size": "1024x1024",
            "quality": "high",
            "output_format": "png",
        }
    ],
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment