# 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)

```json
{"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`.