The Inner Workings of GPT’s file_search Tool

The file_search tool enables GPT models to extract specific information directly from documents uploaded by users. This feature is essential when user queries require precise answers based explicitly on the contents of these documents.

The exact hidden system instruction is as follows:

{
  "Purpose": "Use `file_search.msearch` to answer user questions based on uploaded files.",

  "Structure": {
    "Format": {
      "queries": [
        "first query",
        "second query",
        "... up to five queries"
      ]
    },
    "Requirements": [
      "One query must match the user's original question, rewritten only to resolve ambiguity or complete missing context.",
      "Avoid overly broad or short queries that return noise."
    ]
  },

  "Examples": {
    "User Question": "What was Kevin's age?",
    "Queries": [
      "What was Kevin's age?",
      "Kevin age",
      "How old is Kevin?",
      "Kevin birth year",
      "Kevin date of birth"
    ]
  },

  "Citing Results": {
    "Format": " ",
    "Explanation": {
      "3": "Tool message index",
      "13": "Query result index",
      "Filename": "Source document title (no extension)"
    }
  }
}

How the Tool Functions

Upon receiving a file from a user, such as PDFs, CSVs, or plain text documents, the GPT model uses the method file_search.msearch to query document contents. The queries submitted to the tool are structured as JSON objects, containing up to five distinct queries, each carefully crafted to retrieve the exact information requested.

Query Format

Queries must adhere to the following JSON structure:

{
  "queries": [
    "User's exact original question (mandatory)",
    "Alternative phrasing or synonyms (optional)",
    "... additional related queries (up to five total)"
  ]
}

The first query should exactly match or closely reflect the user’s original request. Additional queries refine or broaden the scope as needed.

Example

If a user asks:

“What is the employee turnover rate for 2024?”

The GPT model would send the following structured request:

{
  "queries": [
    "What is the employee turnover rate for 2024?",
    "2024 employee turnover rate",
    "Employee attrition statistics 2024",
    "Staff turnover figures 2024"
  ]
}

Result Citation

Answers retrieved by the file_search tool include structured citations formatted as follows:

• 4: Index of the response message from the file_search tool.
• 7: Specific result number within that response.
• HR_Report: The name of the original document source (without file extension).

This citation format facilitates direct verification of information by referencing the source document.

Applications and Advantages

The GPT model uses file_search when:

• User questions require exact data points or direct quotes from uploaded files.
• Responses need factual accuracy grounded explicitly in provided documentation.
• Source transparency is crucial for user validation.

By integrating this tool, the GPT model significantly improves the precision, transparency, and reliability of its responses.

Limitations and Best Practices

• Queries must be specific; overly general or ambiguous queries yield irrelevant results.
• The tool strictly retrieves existing data; it does not summarize or interpret content broadly.
• Adherence to the prescribed citation format is essential for clarity and source traceability.

In summary, file_search is a practical retrieval mechanism that allows GPT models to precisely extract and present factual information from user-uploaded documents, ensuring responses are accurate and clearly sourced.