Built-in Tools: Web Search, File Search, Code Interpreter

The Eight Built-in Tools

The Responses API ships with eight hosted tools you can enable per request — no external infrastructure required. Which tools are available depends on your plan tier and how the request is configured.

This lesson covers the three tools most commonly needed in applications: web search, file search, and code interpreter. Hosted shell and apply patch are covered in Lesson 12 when we build a coding agent. MCP gets its own treatment in Lesson 14.

Web Search: Live Data on Demand

Web search is the simplest built-in tool to enable: add a tool object to your request and the model decides when to call it. You don't write a handler — the search is executed by the API, and results are injected into the model's context before it generates a response.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{"type": "web_search"}],
    input="What open-source AI projects went viral this week?"
)
print(response.output_text)

That's the entire integration. The model decides whether to search based on the query — if the answer is clearly in training data, it may skip the search to save latency. You can't force a search on every call, but framing makes intent clear: "Find current information about..." reliably triggers search behavior.

What web search handles well: recent news and events, current software release notes, live documentation, and anything that changed after the April 30, 2026 knowledge cutoff. If your users are asking about the world as it is today, web search is the right tool.

When not to use web search: don't enable it on requests where you already have the context you need. Every search round-trip adds latency and token cost. For questions about your own codebase, a document you've already loaded into the prompt, or well-established knowledge within the training window, adding web search increases cost without improving accuracy. Enable it deliberately, not as a default.

For comparison, here's a request without web search — for a task that doesn't need current data:

# No web_search needed: explaining a concept from training data
response = client.responses.create(
    model="gpt-6-astra",
    input="Explain the difference between supervised and unsupervised learning.",
    reasoning={"effort": "low"}
)
print(response.output_text)

File Search with Vector Stores: RAG Without Infrastructure

File search lets you run semantic retrieval over your own documents. The API handles chunking, embedding, indexing, and retrieval — you provide the files and ask questions against them. The result is a retrieval-augmented generation pipeline without a separate vector database, embedding service, or retrieval layer.

The setup has three steps: create a vector store, upload files into it, then attach the vector store to a request.

Step 1: Create the vector store.

from openai import OpenAI

client = OpenAI()

vector_store = client.vector_stores.create(name="Product Docs")
print(vector_store.id)  # vs_xxxxxxxxxxxxxxxxxx

Step 2: Upload files and add them to the store. Use create_and_poll to wait until the files are fully indexed before querying — querying a store whose files are still processing will return incomplete results.

with open("user-guide.pdf", "rb") as f:
    file = client.files.create(file=f, purpose="assistants")

batch = client.vector_stores.file_batches.create_and_poll(
    vector_store_id=vector_store.id,
    file_ids=[file.id]
)
# batch.status == "completed" when ready

Step 3: Attach the vector store to a Responses API request.

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }],
    input="What are the installation requirements?"
)
print(response.output_text)

Under the hood, your files are split into overlapping chunks, each chunk is embedded into a vector, and the vectors are stored in a managed index. When a request comes in with file search enabled, the model's query is embedded and matched against that index — the top-scoring chunks are retrieved and injected into context before the model generates its answer. You don't touch any of this; it happens automatically.

File search vs. loading documents directly into context. For a single short document, putting it directly in the prompt is simpler and has no indexing overhead. File search pays off when: your corpus is too large to fit in one context window; you have many documents and don't know which is relevant at request time; or you want retrieval to persist across many requests without re-uploading. For a 10-page PDF you always need, use the context window. For a 5,000-document knowledge base, use file search.

Code Interpreter: Python in a Hosted Sandbox

Code interpreter runs Python in a fully isolated virtual machine managed by OpenAI. The model writes the code, the sandbox executes it, and the output — text, data, or generated files — comes back in the response. You don't provision the environment, install packages, or manage execution state.

To use code interpreter, create a container first, then reference it in your request:

from openai import OpenAI

client = OpenAI()

# Create a sandboxed execution environment
container = client.containers.create(
    name="data-analysis",
    expires_after={"anchor": "last_active_at", "minutes": 60}
)

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    input="Generate a summary of this dataset.",
    tool_choice="required"
)

To pass a CSV file for analysis, upload it with the Files API and reference it in the input array:

with open("customers.csv", "rb") as f:
    upload = client.files.create(file=f, purpose="assistants")

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{"type": "code_interpreter", "container": container.id}],
    input=[
        {
            "type": "text",
            "text": "Summarize the data and generate a histogram of the age column."
        },
        {
            "type": "input_file",
            "file_id": upload.id
        }
    ]
)

Retrieving generated images. When the model generates a plot, it's returned as an output item with type image inside a code_interpreter_call. Retrieve it by file ID:

for item in response.output:
    if item.type == "code_interpreter_call":
        for out in item.outputs:
            if out.type == "image":
                image_data = client.files.content(out.file_id)
                with open("histogram.png", "wb") as img:
                    img.write(image_data.read())

What the sandbox can do: run arbitrary Python, install packages with pip, read and write files, generate matplotlib or seaborn plots, and perform numerical computation with numpy and pandas. What it cannot do: make outbound HTTP requests or persist state across separate container sessions. If you need state to persist across multiple calls, reuse the same container ID — it stays active until the expires_after window closes with no activity.

Choosing the Right Built-in Tool

The eight tools address distinct needs. For the three covered in this lesson, the decision is usually straightforward once you frame the question correctly.

Use web search when: the question requires information after April 30, 2026 — current events, recent releases, live prices. Web search has latency and cost; don't enable it speculatively on requests that don't need current data.

Use file search when: you have your own documents that need semantic retrieval. The corpus is too large for a context window, varies by user or session, or needs to be reused across many requests without re-uploading each time.

Use code interpreter when: the task involves computation, data transformation, or generating a derived artifact — a chart, a cleaned dataset, a formatted report. Tasks that require Python execution rather than just reasoning about data belong here.

The broader principle: built-in tools reduce the infrastructure you have to manage, but they're not free. Each tool you enable adds potential latency and token cost to every request. Enable tools selectively — the right tool for the right request, not all tools by default.