Hosted tool search lets OpenAI Responses models defer large tool surfaces until runtime, so the model loads only the subset it needs for the current turn, reducing tool-schema tokens without exposing every tool up front.[1] Hosted tool search is available only with OpenAI Responses models and requires openai>=2.25.0.[1]
Searchable deferred surfaces include @function_tool(defer_loading=True), tool_namespace(name=..., description=..., tools=[...]), and HostedMCPTool(tool_config={..., "defer_loading": True}).[1] Namespaces can mix immediate and deferred tools: tools without defer_loading=True remain callable immediately, while deferred tools in the same namespace are loaded through tool search.[1]
Deferred-loading function tools must be paired with exactly one ToolSearchTool() instance on the agent.[1] Named tool_choice cannot target bare namespace names or deferred-only tools; use auto, required, or a real top-level callable tool name instead.[1] ToolSearchTool(execution="client") is for manual Responses orchestration; if the model emits a client-executed tool_search_call, the standard Runner raises instead of executing it.[1] Tool search activity appears in RunResult.new_items and in RunItemStreamEvent with dedicated item and event types — see Result and items and Streaming for those type details.[1] ToolSearchTool() is the runtime mechanism the model calls to discover and load deferred tools; without it, the agent cannot resolve any deferred surface.
Canonical hosted tool search setup using tool_namespace and ToolSearchTool:
from agents import Agent, Runner, ToolSearchTool, tool_namespace
from agents.decorators import tool
@tool(defer_loading=True)
def get_customer_profile(customer_id: Annotated[str, "The customer ID to look up."]) -> str:
"""Fetch a CRM customer profile."""
return f"profile for {customer_id}"
crm_tools = tool_namespace(
name="crm",
description="CRM tools for customer lookups.",
tools=[get_customer_profile, list_open_orders],
)
agent = Agent(
name="Operations assistant",
model="gpt-5.6-sol",
instructions="Load the crm namespace before using CRM tools.",
tools=[*crm_tools, ToolSearchTool()],
)
Sources