google-search

cuba6112's avatarfrom cuba6112

Integration patterns for web search grounding, including query operator usage, API-based search orchestration, and citation metadata mapping. Triggers: google-search, grounding, search-api, citations, search-operators, web-search.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 26, 2025
[Web Research]

When & Why to Use This Skill

This Claude skill facilitates the integration of Google Search grounding into AI workflows, enabling LLMs to access real-time web data, perform precise fact-checking, and provide verifiable citations. It covers both native tool-use and custom API implementations to bridge the gap between static model knowledge and the live web, significantly reducing hallucinations and increasing user trust.

Use Cases

  • Real-time Fact-Checking: Verifying recent news, sports results, or current events that occurred after the model's training cutoff to ensure factual accuracy.
  • Verifiable Source Attribution: Automatically mapping grounding metadata to specific text segments to provide clickable, direct links to information sources for every claim.
  • Targeted Domain Research: Utilizing advanced search operators like 'site:' to restrict information gathering to specific trusted websites, government databases, or technical documentation.
  • Custom Search Orchestration: Building specialized search tools using the Google Custom Search API for tailored information retrieval workflows in enterprise environments.
namegoogle-search
descriptionIntegration patterns for web search grounding, including query operator usage, API-based search orchestration, and citation metadata mapping. Triggers: google-search, grounding, search-api, citations, search-operators, web-search.

Google Search Grounding

Overview

Google Search grounding allows LLM applications to access real-time information and provide verifiable citations. This skill covers both direct tool integration (like Gemini's google_search) and custom API implementations.

When to Use

  • Fact-Checking: When the LLM needs to confirm recent events (e.g., Euro 2024 results).
  • Source Attribution: When user trust requires seeing direct links to the information source.
  • Niche Research: Using operators like site: to restrict information to specific domains.

Decision Tree

  1. Does the model support built-in grounding (e.g., Gemini)?
    • YES: Enable google_search tool.
    • NO: Use Custom Search API.
  2. Do you need to restrict search to specific sites?
    • YES: Use site:example.com operator (no spaces).
  3. Do you need to exclude terms?
    • YES: Use -term operator.

Workflows

1. Implementing Search Grounding (Tool-based)

  1. Enable the google_search tool in the model configuration.
  2. Send a user prompt to the API and receive the response containing groundingMetadata.
  3. Extract webSearchQueries for debugging and groundingChunks for source links.
  4. Render the response with citations by mapping groundingSupports indices to the source URLs.

2. Precise Source Targeting

  1. Use the site: operator to restrict searches to trusted domains (e.g., site:nytimes.com).
  2. Combine multiple operators (e.g., site:github.com "error 404") for specific technical queries.
  3. Exclude irrelevant results using the - operator (e.g., jaguar speed -car).

3. Custom Search API Integration

  1. Create a Programmable Search Engine ID in the Google control panel.
  2. Generate an API key for Custom Search.
  3. Perform GET requests to the API with the q parameter and parse the resulting JSON search results.

Non-Obvious Insights

  • Strict Operators: Search operators like site: must NOT have spaces between the colon and the value (e.g., site:nytimes.com works, site: nytimes.com fails).
  • Citations Metadata: Grounding metadata uses groundingSupports to map specific text segments to source indices, allowing for precise, multi-source citations in a single sentence.
  • Synthesis Loop: The Gemini tool doesn't just return links; it analyzes the prompt, generates multiple refined queries, and synthesizes a grounded answer.

Evidence

Scripts

  • scripts/google-search_tool.py: Implementation of Custom Search API requests.
  • scripts/google-search_tool.js: Example of parsing grounding metadata for citations.

Dependencies

  • google-api-python-client (for Custom Search API)
  • google-generativeai (for Gemini Tool-use)

References