Why the Default Search Behavior Is Not Always Enough

Lesson 2 covered enabling web search with the simplest possible configuration: tools=[{"type": "web_search"}]. That default is reasonable for a general-purpose assistant, but real applications usually have narrower, more specific needs. A financial application might need results restricted to reputable financial sources. A customer support bot for a company's own product might need to bias results toward that company's official documentation domain. A news summarizer might need very recent results and nothing older.

Treating web search as a single on/off switch ignores that different applications have fundamentally different tolerances for source quality, recency, and scope. The Responses API's web search tool accepts additional configuration precisely so you can shape these tradeoffs instead of accepting whatever the default search behavior happens to return. This lesson covers the configuration knobs that matter most for production use and, just as importantly, the reasoning for when to use each one.

Restricting Search to Specific Domains

One of the most practical configuration options is domain filtering — telling the tool to only consider results from a specific set of websites, or to explicitly exclude certain domains. This matters because the open web contains a huge range of source quality, and for many applications, an answer sourced from an unreliable blog is worse than no answer at all.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "allowed_domains": [
                    "docs.python.org",
                    "peps.python.org",
                ]
            },
        }
    ],
    input="What does PEP 8 recommend for maximum line length, and has that guidance changed recently?",
)

print(response.output_text)

The filters object with an allowed_domains list restricts the search tool to results originating from those domains only. For a documentation assistant built around a specific ecosystem — in this case Python's own official documentation and PEP archive — this dramatically reduces the chance of pulling in an outdated or inaccurate third-party tutorial when an authoritative primary source exists.

This works because it operates as a filter over search results, not a change to the query itself. The model still forms its own search query internally; the filter simply narrows the pool of pages the search step can pull from. If none of the allowed domains have relevant content for a given query, the tool will return few or no results, which is a feature, not a bug — you generally want your application to admit it lacks a good source rather than fall back to an unrestricted, potentially unreliable result.

Note: The exact filter key (allowed_domains here) and its expected format — for example, whether it accepts full URLs, bare domains, or wildcard patterns — is a version-sensitive API detail. Confirm the current field name and accepted values against the official Responses API documentation before relying on it in production.

Choosing Between Broad and Narrow Search Scope

Beyond domain restriction, you often need to think about how broad a search should be in terms of freshness and quantity of sources consulted. A request like "summarize today's top technology news" needs a fundamentally different search strategy than "what year was Python 3.0 released" — the first needs many current sources synthesized together, while the second needs one authoritative, stable answer.

While the web search tool's own internal search strategy is mostly opaque to you as the caller (you cannot micromanage exactly how many pages it fetches), you influence this behavior indirectly through:

1. Prompt specificity. A vague prompt ("tell me about electric cars") invites a broad, shallow search. A specific prompt ("what is the current EPA-estimated range of the base trim of the most recent model year of a specific electric vehicle") invites a narrower, more targeted one.
2. Domain and recency filters, which reduce the candidate pool the tool draws from, indirectly narrowing scope.
3. Explicit instructions about depth, such as asking the model to consult multiple sources and note disagreement, versus asking for a single quick fact.

from openai import OpenAI

client = OpenAI()

def ask_with_scope(question: str, allowed_domains: list[str] | None = None) -> str:
    tool_config = {"type": "web_search"}
    if allowed_domains:
        tool_config["filters"] = {"allowed_domains": allowed_domains}

    response = client.responses.create(
        model="gpt-5.6-terra",
        tools=[tool_config],
        input=question,
    )
    return response.output_text


broad_answer = ask_with_scope(
    "What are the major themes in renewable energy policy discussions this year?"
)
narrow_answer = ask_with_scope(
    "What is the current U.S. federal solar investment tax credit percentage?",
    allowed_domains=["energy.gov", "irs.gov"],
)

print("Broad:", broad_answer[:200])
print("Narrow:", narrow_answer[:200])

This example wraps the tool configuration in a small helper function, ask_with_scope, that conditionally adds a domain filter only when one is supplied. This kind of wrapper is worth building early in any application that uses web search in more than one place, because it centralizes your tool configuration logic instead of repeating the same dictionary construction at every call site. Notice the function builds tool_config as a plain dictionary and only inserts the filters key when allowed_domains is truthy — this avoids sending an empty or malformed filter object when no restriction is needed, which keeps the unrestricted case behaving exactly like Lesson 2's minimal example.

Configuring for Recency-Sensitive Queries

Some applications, such as a "what's happening right now" feed or a price checker, specifically need very recent information and should treat older results as actively unhelpful, not just less ideal. While the fine-grained ability to specify "results from the last N hours" depends on what the current API surface supports, you can approach this today primarily through prompt design combined with output validation.

from openai import OpenAI
from datetime import date

client = OpenAI()

today = date.today().isoformat()

response = client.responses.create(
    model="gpt-5.6-terra",
    tools=[{"type": "web_search"}],
    input=(
        f"Today's date is {today}. Search for the most recent news about "
        "quarterly earnings from major cloud computing providers. "
        "Only report information from sources published within the last two weeks, "
        "and explicitly state the publication date of each source you use."
    ),
)

print(response.output_text)

Passing the current date explicitly into the prompt is a small but important technique. The model itself has no innate sense of "today" beyond what you tell it — its internal clock, so to speak, is frozen at training time. Without this, a phrase like "the last two weeks" is ambiguous to the model relative to an unknown reference point. By interpolating date.today() into the input text, you give the model a concrete anchor to reason against when it evaluates whether a search result counts as recent enough.

This also sets up the pattern used more rigorously in Lesson 9, which covers testing freshness-sensitive answers — part of that testing strategy depends on being able to control and verify the reference date used in a request.

Comparing Configuration Approaches

Common Mistakes

Assuming domain filters guarantee a result exists, which causes unhandled empty or vague responses. If none of the allowed domains have relevant content, the tool may return little to work with, and the model may either say so plainly or, worse, fall back to its own unsearched knowledge while still sounding grounded. Always instruct the model explicitly to say when it cannot find a supporting source within the allowed set, and check the response for that signal.

Over-restricting domains for exploratory or broad questions, which happens when a developer applies the same tight allowed_domains list used for a narrow, high-stakes lookup to a general-purpose chat feature. This starves the model of legitimate, useful sources for questions the restriction was never designed to handle. Match the restriction to the specific use case, not the whole application.

Forgetting to pass the current date for recency-sensitive prompts, which causes the model to misjudge whether search results are "recent" relative to an implicit and incorrect assumption about today's date. Always interpolate an explicit date when phrases like "recent," "latest," or "this week" appear in your prompt.

Best Practices

Build a small configuration wrapper function, like ask_with_scope above, rather than hand-writing tool dictionaries at every call site. This keeps domain lists and other filters consistent and makes future API changes easier to apply in one place.

Match search scope to the stakes of the answer. A casual, exploratory feature can tolerate a broad, unrestricted search. A feature that drives a user decision — pricing, health, legal, financial — should use domain restriction and explicit recency requirements, and should be willing to return "no reliable source found" rather than a low-quality answer.

Always pass an explicit reference date in recency-sensitive prompts, since the model has no built-in notion of "now" beyond what you provide in the request.