Choosing Between File, Web, and Tool Search in the Responses API

In the Responses API, “search” can refer to three different resources:

• file_search retrieves content from files previously uploaded to vector stores.
• web_search retrieves internet information and can return cited answers.
• tool_search discovers deferred functions, namespaces, or MCP servers so that a relevant subset becomes callable.

The practical question is: Does the model need document content, internet information, or a tool definition? These are separate documented interfaces, not parts of a universal retrieval architecture.

Decision table

They are not interchangeable: each searches a different resource and returns different artifacts.

file_search: search uploaded document collections

Use file_search when the required information resides in files already uploaded and added to a vector store. OpenAI describes it as semantic and keyword search over knowledge bases of previously uploaded files.[^1]

Before making the Responses API request, the application must:

1. Upload the files.
2. Create or select a vector store.
3. Add the files to that vector store.
4. Pass the relevant IDs through vector_store_ids.[^1]

The basic tool declaration is:

{
  "type": "file_search",
  "vector_store_ids": ["<vector_store_id>"]
}

File search is hosted by OpenAI. If the model chooses to use it, the service searches the specified vector stores and returns output; the application does not implement the underlying search.[^1]

Documented controls include:

• max_num_results to limit the number of retrieved results.
• filters to restrict results using file metadata.
• include: ["file_search_call.results"] to place the search results in the response.[^1]

For example:

{
  "type": "file_search",
  "vector_store_ids": ["<vector_store_id>"],
  "max_num_results": 2,
  "filters": {
    "type": "in",
    "key": "category",
    "value": ["blog", "announcement"]
  }
}

max_num_results is only a limit. It does not guarantee complete or relevant retrieval, and the documentation notes that reducing the result count may reduce answer quality.[^1]

web_search: search internet information

Use web_search when a response may require information from the internet. For new Responses API integrations, the documented declaration is {"type":"web_search"}.[^2]

When web search runs, the response can contain:

• A web_search_call item identifying the call and its action.
• A message containing generated text.
• Annotations identifying cited URLs.[^2]

The sources field exposes the URLs retrieved during the search. It differs from inline citations, which show references selected for the generated answer.[^2]

Documented controls include:

• search_context_size, which controls how much search-result context is available to the model.
• filters.allowed_domains and filters.blocked_domains, each supporting up to 100 domains.
• external_web_access, which controls whether the tool fetches live content or uses cached or indexed results.
• sources, for inspecting retrieved URLs.
• return_token_budget for supported GPT-5+ reasoning web-search runs.[^2]

search_context_size does not set an exact token count or guarantee a particular number of sources or citations.[^2] Citations and source lists also do not, by themselves, establish correctness, freshness, or completeness.

Declaring the tool does not prove that a search occurred. With tool_choice: "auto", web search is optional. Use tool_choice: "required" or select the specific web-search tool when the search must run.[^2]

The older web_search_preview remains available for legacy integrations, but it does not support filters or return_token_budget and ignores external_web_access. The documented Responses API web-search context is limited to 128k, even when the model has a larger context window.[^2]

tool_search: discover callable definitions

tool_search searches a tool inventory rather than document or web content. Its searchable surfaces include deferred functions, namespaces, and MCP servers.[^3]

In the Responses API, the documentation specifies GPT-5.4 or later. Requests must include tool_search; functions and MCP server definitions intended for deferred discovery require defer_loading: true.[^3]

{
  "type": "tool_search"
}

Tools that are not deferred remain immediately callable. Deferred definitions are loaded through tool search when selected.[^3]

Hosted discovery

In hosted mode, OpenAI searches the deferred tools declared in the request and returns the loaded subset in the same response. This mode fits cases where the candidate inventory is known when the request is created.[^3]

Client-executed discovery

Client mode is for inventories that the application must search. Configure tool_search with execution: "client" and a schema for the expected search arguments. The model emits a tool_search_call; the application performs the lookup and returns a matching tool_search_output.[^3]

The returned output must echo the call_id from the corresponding call. OpenAI also advises validating dynamically returned schemas and exposing only trusted tool definitions.[^3]

Tool discovery is distinct from execution. Loading a definition makes it callable; it should not be described as automatically executing the selected function.

Choose by the missing resource

• For content in an uploaded knowledge base, use file_search with vector_store_ids.
• For internet information and cited output, use web_search.
• For a relevant subset of deferred callable definitions, use tool_search with hosted or client-executed discovery.

The documentation defines request boundaries and controls. It does not establish comparative quality, latency, cost, security, ranking, or completeness guarantees.

Sources

[^1]: OpenAI, File search.
[^2]: OpenAI, Web search.
[^3]: OpenAI, Tool search.

Sources and further reading

• https://developers.openai.com/api/docs/guides/tools-file-search
• https://developers.openai.com/api/docs/guides/tools-web-search
• https://developers.openai.com/api/docs/guides/tools-tool-search