Tool search (type: "tool_search") and deferred tools (defer_loading)
Status: DOCUMENTED · LIVE_VERIFIED (2026-09-18, hosted mode on gpt-5.4-mini; gpt-5.4-nano does not list tool_search on its model page and was not used)
Sources: https://developers.openai.com/api/docs/guides/tools-tool-search · https://developers.openai.com/api/docs/guides/function-calling#namespaces · openapi-master.yaml ToolSearchToolParam, ToolSearchCall, ToolSearchOutput, NamespaceToolParam, AdditionalTools
Last verified: 2026-09-18
Definition
| Field | Type / enum | Notes |
|---|---|---|
type |
tool_search |
|
execution |
server (hosted, default) | client |
client: your app performs the lookup and returns tool_search_output |
description |
string | null | shown to the model in client mode |
parameters |
object | null | client-mode search arguments schema |
Deferred tools: defer_loading: true on function, custom (inside or outside a namespace) and mcp tools. The model initially sees only names/descriptions of namespaces/servers; loaded definitions are appended at the end of context to preserve the prompt cache. additional_tools input item adds tools mid-conversation. tool_choice applies to the currently loaded tools. Responses API: gpt-5.4 and later only; Agents API loads eagerly unless {type: tool_search} is added.
Items (live shapes)
{"id":"tsc_…","type":"tool_search_call","status":"completed","call_id":null,"execution":"server","arguments":{"paths":["weather"]}}
{"id":"tso_…","type":"tool_search_output","status":"completed","call_id":null,"execution":"server","tools":[{"type":"namespace","name":"weather",…}]}
{"id":"fc_…","type":"function_call","namespace":"weather","name":"get_weather","arguments":"{\"city\":\"Paris\"}","call_id":"call_…"}Client mode: the first turn stops at tool_search_call; you return {"type":"tool_search_output","call_id":…,"execution":"client","tools":[<tool definitions>]} (may include tools not declared in tools).
Live evidence
gpt-5.4-mini, tools: [{type: tool_search}, {type: namespace, name: weather, description, tools: [get_weather with defer_loading: true]}], prompt "Weather in Paris? Find and use a tool." → reasoning, tool_search_call, tool_search_output (loaded the whole weather namespace), function_call with namespace: "weather"; usage ≈ $0.0007.
Examples: examples/openai/tools/tool-search/ (sh/py/ts). Test (expensive): test_tool_search_hosted.