File Search

The file_search tool is a built-in tool for searching through your uploaded documents. Unlike internet_search (live web) and url_content (public URLs), this tool searches your private uploaded files stored in a File Search Store. It uses Google Gemini 2.5 Flash with native fileSearch grounding to retrieve and answer from document content.

How It Works

1. You (or your system) upload documents to a File Search Store (via a separate upload API)

2. You pass the store name(s) in the file_search_store_names field of your request

3. The LLM receives the store names via an injected system message and calls the file_search tool automatically

4. Gemini 2.5 Flash searches the store using semantic/vector search and returns grounded answers with citations

5. The answer is returned as a standard chat completion

Key Difference from Other Tools

Tool	Trigger	Source
internet_search	Auto (from prompt)	Live public web via Perplexity
url_content	Auto (URL in message)	Specific public URL via Gemini
file_search	Auto + file_search_store_names in request	Your private uploaded documents

Use Cases & Examples

1. Summarize an Uploaded Document

{
  "model": "google/gemini-2.5-flash",
  "file_search_store_names": ["fileSearchStores/defaultstore-31ihhh9rmyef"],
  "messages": [
    { "role": "user", "content": "Summarize the uploaded document" }
  ]
}

2. Ask a Specific Question from Documents

{
  "model": "google/gemini-2.5-flash",
  "file_search_store_names": ["fileSearchStores/defaultstore-31ihhh9rmyef"],
  "messages": [
    { "role": "user", "content": "What is the definition of molarity and how is it calculated?" }
  ]
}

3. Search Multiple Stores Simultaneously

{
  "model": "google/gemini-2.5-flash",
  "file_search_store_names": [
    "fileSearchStores/q1-reports",
    "fileSearchStores/q2-reports"
  ],
  "messages": [
    { "role": "user", "content": "Compare Q1 and Q2 revenue figures from the reports" }
  ]
}

4. Contract / Legal Document Analysis

{
  "model": "google/gemini-2.5-flash",
  "file_search_store_names": ["fileSearchStores/contracts-store"],
  "messages": [
    { "role": "user", "content": "What are the termination clauses in the uploaded contract?" }
  ]
}

5. With a System Prompt

{
  "model": "google/gemini-2.5-flash",
  "file_search_store_names": ["fileSearchStores/support-docs"],
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful support agent. Only answer based on the uploaded documentation."
    },
    { "role": "user", "content": "How do I upgrade my plan?" }
  ]
}

Tips & Best Practices

Tip	Details
Always pass store names	file_search_store_names must be in every request — the tool won't activate without it
Pass on every turn	In multi-turn conversations, include the field on each request
Multiple stores	Pass an array to search across multiple document collections at once
Any model works	Store names are injected as a system message — model-agnostic
Be specific	"What is the refund policy?" retrieves more precisely than "Tell me about the document"
Combine with system prompt	Use a system prompt to constrain the model to only answer from the documents

---

Limitations

• Requires pre-uploaded documents — you must upload files to a store before querying (separate upload flow)

• Store names are static — if a store is deleted or renamed, queries will fail gracefully (returns an error message without crashing)

• No raw chunk retrieval — you get a synthesized answer, not a list of raw document excerpts

• No filtering by file — all files in the store are searched together; you can't target a specific file within a store

• file_search_store_names is not a standard OpenAI field — OpenAI SDK clients must use extra_body (Python) or // @ts-ignore (TypeScript) to pass it