docs(ai-gateway): recommend GA web_search tool; correct annotations note#159
Merged
Conversation
The previous note told users to prefer web_search_preview because GA web_search "returns empty annotations." That was a test artifact: under the default tool_choice:auto the model only searches when it judges a query needs it, so a well-known fact returns no citations regardless of which tool. When a search actually runs, GA web_search returns web_search_call items and url_citation annotations. - Switch the example to the GA `web_search` tool. - Replace the incorrect warning with a tip about tool_choice auto vs required. - Align the privacy callout to reference `web_search`.
anukiransolur
approved these changes
Jul 9, 2026
Contributor
Author
|
Thanks! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Corrects the OpenAI web-search guidance added earlier. The previous note recommended
web_search_previewand warned that the GAweb_searchtool "returns empty annotations." That was a test artifact, not a real limitation — GAweb_searchworks and returns citations.Why
Under the default
tool_choice: "auto", the model searches only when it judges a query needs it. For a fact it already knows, it answers directly andannotationscome back empty — regardless of which tool (web_searchorweb_search_preview). When a search actually runs (an unknowable query, ortool_choice: "required"), the GAweb_searchtool returnsweb_search_callitems and populatedurl_citationannotations. Verified end-to-end.Changes
web_searchtool.tool_choice: autovsrequired.web_search.Gemini
google_searchsection unchanged (verified correct).Notes
docs/guides/ai-gateway.md); no repo-widefmt.lintpasses (pre-existingsitemap.tswarning only).