The tool catalog organizes five tool categories—hosted OpenAI tools (web search, file search, code interpreter), local/runtime tools (ComputerTool, ShellTool), FunctionTool instances, agents as tools, and experimental tools—each with distinct availability, configuration, and output requirements. Tool outputs are validated through Pydantic models (ToolOutputText, ToolOutputImage, ToolOutputFileContent), and tools track their runtime origin (FUNCTION, MCP, AGENT_AS_TOOL) via serializable ToolOrigin metadata.
docs/tools.md catalogs five tool categories: hosted OpenAI tools (web search, file search, code interpreter, hosted MCP, image generation), local/runtime tools (ComputerTool, ApplyPatchTool, ShellTool), FunctionTool instances, agents as tools, and an experimental Codex tool.[1] Hosted tools (WebSearchTool, FileSearchTool, CodeInterpreterTool, HostedMCPTool, ImageGenerationTool, ToolSearchTool, ProgrammaticToolCallingTool) are available only when using OpenAIResponsesModel.[1]
WebSearchTool supports filters, user_location, and search_context_size options.[1] FileSearchTool supports filters, ranking_options, include_search_results, vector_store_ids, and max_num_results; max_num_results accepts integers 1–50, and None or zero uses the provider default.[1]
Canonical usage of WebSearchTool and FileSearchTool with an Agent:
from agents import Agent, FileSearchTool, Runner, WebSearchTool
agent = Agent(
name="Assistant",
tools=[
WebSearchTool(),
FileSearchTool(
max_num_results=3,
vector_store_ids=["VECTOR_STORE_ID"],
),
],
)
async def main():
result = await Runner.run(agent, "Which coffee shop should I go to, taking into account my preferences and the weather today in SF?")
print(result.final_output)
src/agents/tool.py defines three tool function signatures: ToolFunctionWithoutContext (no context), ToolFunctionWithContext (first arg is RunContextWrapper), and ToolFunctionWithToolContext (first arg is ToolContext), all unified as ToolFunction.[2] ToolCaller in src/agents/tool.py is a Literal type with values "direct" and "programmatic", distinguishing calls made directly by the model from those made via Programmatic Tool Calling — see Programmatic tool calling.[2]
ValidToolOutputPydanticModels in src/agents/tool.py is the union ToolOutputText | ToolOutputImage | ToolOutputFileContent, and a pre-built TypeAdapter named ValidToolOutputPydanticModelsTypeAdapter handles efficient Pydantic validation of tool outputs.[2] ToolOutputImage in src/agents/tool.py requires at least one of image_url or file_id; providing neither raises a ValueError via a Pydantic model_validator.[2] ToolOutputImage.detail accepts "low", "high", or "auto" to control vision detail level, and is optional (defaults to None).[2] ToolOutputFileContent in src/agents/tool.py requires at least one of file_data (base64), file_url, or file_id; providing none raises a ValueError via a Pydantic model_validator.[2]
ToolOriginType in src/agents/tool.py is a str Enum with three values — FUNCTION, MCP, and AGENT_AS_TOOL — indicating the runtime source of a function-tool-backed run item.[2] ToolOrigin in src/agents/tool.py is a frozen dataclass carrying serializable metadata (type, optional MCP server name, agent name, agent tool name) about where a function-tool-backed item originated, and round-trips via to_json_dict() / from_json_dict().[2] ToolOrigin.from_json_dict() returns None (rather than raising) when the input is not a Mapping, lacks a "type" key, or contains an unrecognized ToolOriginType value.[2]
DEFAULT_APPROVAL_REJECTION_MESSAGE in src/agents/tool.py is "Tool execution was not approved." — the default message returned to the model when a tool call is rejected by the approval flow.[2] ToolTimeoutBehavior in src/agents/tool.py is a Literal type with two values: "error_as_result" (return the error as the tool result) or "raise_exception" (propagate the ToolTimeoutError).[2]
FunctionToolCustomDataContext, CustomToolCustomDataContext, ComputerToolCustomDataContext, and ApplyPatchToolCustomDataContext in src/agents/tool.py are frozen dataclasses passed to custom data extractor callbacks, each carrying the invocation context, the tool object, the model-visible output, and the raw replay item.[2]
Sources