Hosted search tool or your own retriever in an agent framework

Agent frameworks increasingly ship search as a switch you flip. In OpenAI's Responses API, for example, you can add a hosted web search tool to a request, and the platform takes care of querying, reading results and attaching citations to the answer. The alternative is to bring your own backend: describe a search function, let the model call it, and run the search yourself against a provider or an index you choose. Both are reasonable. They differ in who controls the query and the results, what kind of citations come back, how the bill is shaped and how easily you can evaluate the system. This guide walks through those differences so you can choose deliberately, and change your mind later without a rewrite.

Two shapes of the same capability

Built-in tool. You list the hosted search tool among the request's tools. The model decides when to search; the platform runs the query through its own search integration, feeds results into the model's context and returns an answer, typically with annotations that link spans of text to source URLs. Your code never sees the raw results unless the platform exposes them.

Bring your own. You define a function tool with a name, a description and a parameter schema. When the model wants to search, the response contains a function call with arguments; your code runs the search, formats the results and sends them back as that call's output; the model then continues. A sketch of such a definition in the Responses style:

{
  "type": "function",
  "name": "search_sources",
  "description": "Search approved sources. Returns passages with ids, urls and dates.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "recency_days": {"type": "integer"}
    },
    "required": ["query"]
  }
}

A third route sits between the two: exposing your search as a tool server the framework can call, for instance over MCP where the framework supports it. Operationally this behaves like bringing your own, because the backend is still yours. Check your framework's current documentation for the tool types it accepts; this area moves quickly.

Control: who decides what gets searched and returned

With the built-in tool you trade control for convenience. Before relying on it, check what the tool lets you set and see:

• Source restrictions. Can you limit or exclude domains? Can you restrict by region or language?
• Query visibility. Can you see the queries the model actually issued? Without them, debugging a bad answer is guesswork.
• Result visibility. Can you retrieve the text the model read, or only the final answer and its links?
• Private data. A hosted web search cannot reach your intranet, ticket system or document store. Questions that need internal material need retrieval you run anyway.
• Data handling. Where are queries processed and logged, and what does the platform's data policy say about them? Queries written by an agent often contain customer names and internal context.

Bringing your own inverts the trade. You choose the provider, the index, the filters, the ranking and how many passages come back; you log every query and result; and you can enforce a source allowlist or a recency rule in code, where the model cannot talk its way around it. You also own the failure modes: timeouts, empty results, provider outages and schema drift. For picking the provider behind your function, see choosing a search tool for AI agents.

Citations: what comes back and whether you can check it

Built-in tools usually return citations as annotations: a URL, a title and the character range of the answer it supports. That is convenient to render. Ask three questions before you depend on it:

1. Does the citation point to a page, or to the passage on that page that supports the claim?
2. Can you retrieve the text the model saw, so that a reviewer or an automated check can compare claim and source?
3. Is the retrieval date available, so a reader knows how old the evidence is?

With your own backend, citation design is up to you. Give each passage a stable ID, return IDs alongside the text, ask the model to cite IDs per claim and validate that every cited ID was actually returned for this question. You can also store copies of retrieved text, which matters once the live page changes after the answer was written. The cost is engineering effort; the gain is citations you can test. Passage-level citation for chatbots covers the details.

Cost model: price the task, not the call

The two approaches bill differently, and the difference only shows once an agent starts looping.

• Built-in tool: hosted tools are commonly billed per tool call, and the retrieved content adds tokens to the context. Results the platform injects can be long, and you do not set their length directly. Check the framework's current pricing page for exactly how search calls and retrieved content are counted.
• Bring your own: you pay the search provider under its own model (per query, per result, per page fetched or through credits), plus the tokens for whatever you pass back to the model, plus the infrastructure and engineering to keep it running. Because you decide how many passages to return, you can trade context cost against answer quality on purpose.

Either way, the unit that matters is cost per completed task. An agent that refines its query several times and reads a few pages per question costs very differently from a single search. Measure it on your own workload, and cap the number of tool calls per task so a confused agent cannot keep searching indefinitely. The note on putting a ceiling on agent spend explains why a visible limit beats a surprise invoice.

Evaluation: can you tell which part failed?

When search and generation are fused inside a hosted tool, a bad answer has two possible causes and you often cannot tell them apart. Did the search return poor material, or did the model misread good material? Your own backend separates the two: you can evaluate retrieval on its own (did the right passages come back?) and generation on its own (given these passages, is the answer correct and properly cited?).

A practical evaluation for this decision:

1. Collect 30 to 50 real questions from users or agent logs, including recent events, domain jargon, non-English queries and a few with no good answer.
2. Write down what a correct answer and acceptable sources look like before running anything.
3. Run each question through both configurations with the same prompt and model, and keep full traces: queries issued, results returned, final answer, citations.
4. Grade answers blind for correctness, citation support and freshness; record cost per task and time to answer.
5. Repeat on another day. Search results move, and one run hides that.

The guides on evaluating web search on your own queries and judging recall and accuracy of AI search go deeper on grading.

A decision table

Many teams end up with both: the built-in tool for open-ended public questions and their own function for internal or restricted sources. If you go that way, make the routing explicit in the instructions and in your logs, so you know which path produced each answer.

Where GoCux fits

GoCux is not a search backend for agent frameworks and does not read the open web, so it is not an option in this table. It sits at a different point: governing the research an agent does, whatever search sits underneath. A research plan in GoCux states the question, the ordered steps and a source allowlist, and a person approves it before it runs; execution cannot reach beyond what was approved, and an allowlist left empty lets no source through. Work orders carry bounds such as wall time and the number of tool calls, and a bound of zero tool calls means none at all. Findings supported by a quotation are kept apart from questions that no source answered. See comparing search backends by the task they support and the source policy for how the allowlist works.

What to verify before you commit

• You know which tool types your framework accepts today: hosted search, function tools, external tool servers.
• You checked what the built-in tool lets you restrict and what it lets you see: queries, results, retrieval dates.
• Citations point to something a reviewer can check, ideally a passage rather than just a page.
• You priced a completed task on your own workload, with a cap on tool calls per task.
• You ran the same question set through both configurations, graded blind, more than once.
• Internal or restricted sources go through retrieval you control.
• Search sits behind an interface you can swap without rewriting the agent.