When to use

• When you need real-time web information beyond the model's training cutoff
• When you need verifiable sources and citations for AI responses
• When you want to reduce hallucinations with Google Search grounding
• When building AI workflows that require up-to-date information

Gemini Google Search Tool Skill

Purpose

The gemini-google-search-tool is a Python CLI tool and library that connects Gemini AI models to real-time web content through Google Search grounding. It automatically determines when a search would improve answers, executes appropriate queries, and returns grounded responses with verifiable sources.

When to Use This Skill

Use this skill when:

• You need to query Gemini with real-time web information
• You want automatic citations and source attribution
• You're building AI agents that need current information
• You need to verify AI responses against web sources
• You want to integrate Google Search grounding into workflows

Do NOT use this skill for:

• Static knowledge queries that don't need real-time data
• Tasks that don't require source attribution
• Offline-only environments (requires internet and API key)

CLI Tool: gemini-google-search-tool

A professional CLI-first tool for querying Gemini with Google Search grounding, providing real-time web content with automatic citations.

Installation

# Install from source
git clone https://github.com/dnvriend/gemini-google-search-tool.git
cd gemini-google-search-tool
uv tool install .

# Verify installation
gemini-google-search-tool --version

Prerequisites

• Python 3.14 or higher
• uv package manager
• Google Gemini API key (get one free)
• GEMINI_API_KEY environment variable

Quick Start

# Set API key
export GEMINI_API_KEY='your-api-key-here'

# Basic query
gemini-google-search-tool query "Who won euro 2024?"

# With inline citations
gemini-google-search-tool query "Latest AI news" --add-citations

# Using pro model
gemini-google-search-tool query "Complex analysis" --pro

Progressive Disclosure

<details> <summary><strong>📖 Core Commands (Click to expand)</strong></summary>

query - Query Gemini with Google Search Grounding

Query Gemini models with automatic Google Search grounding for real-time web information.

Usage:

gemini-google-search-tool query "PROMPT" [OPTIONS]

Arguments:

• PROMPT: The query prompt (positional, required unless --stdin is used)
• --stdin / -s: Read prompt from stdin (overrides PROMPT)
• --add-citations: Add inline citation links to response text
• --pro: Use gemini-2.5-pro model (default: gemini-2.5-flash)
• --text / -t: Output markdown format instead of JSON
• -v/-vv/-vvv: Verbosity levels (INFO/DEBUG/TRACE)

Examples:

# Basic query with JSON output
gemini-google-search-tool query "Who won euro 2024?"

# Query with inline citations
gemini-google-search-tool query "Latest AI developments" --add-citations

# Read from stdin
echo "Climate change updates" | gemini-google-search-tool query --stdin

# Markdown output
gemini-google-search-tool query "Quantum computing news" --text

# Pro model with verbose output
gemini-google-search-tool query "Complex analysis" --pro -vv

# Trace mode (shows HTTP requests)
gemini-google-search-tool query "Test" -vvv

Output (JSON):

{
  "response_text": "AI-generated response with grounding...",
  "citations": [
    {"index": 1, "uri": "https://...", "title": "Source Title"},
    {"index": 2, "uri": "https://...", "title": "Another Source"}
  ],
  "grounding_metadata": {
    "web_search_queries": ["query1", "query2"],
    "grounding_chunks": [...],
    "grounding_supports": [...]
  }
}

Output (Markdown with --text):

AI-generated response with grounding...

## Citations

1. [Source Title](https://...)
2. [Another Source](https://...)

---

completion - Generate Shell Completion Scripts

Generate shell completion scripts for bash, zsh, or fish.

Usage:

gemini-google-search-tool completion {bash|zsh|fish}

Arguments:

• SHELL: Shell type (bash, zsh, or fish)

Examples:

# Generate and install bash completion
eval "$(gemini-google-search-tool completion bash)"

# Generate and install zsh completion
eval "$(gemini-google-search-tool completion zsh)"

# Install fish completion
mkdir -p ~/.config/fish/completions
gemini-google-search-tool completion fish > ~/.config/fish/completions/gemini-google-search-tool.fish

# Persistent installation (add to ~/.bashrc or ~/.zshrc)
echo 'eval "$(gemini-google-search-tool completion bash)"' >> ~/.bashrc
echo 'eval "$(gemini-google-search-tool completion zsh)"' >> ~/.zshrc

Output: Shell-specific completion script to stdout.

</details> <details> <summary><strong>⚙️ Advanced Features (Click to expand)</strong></summary>

Google Search Grounding

The tool uses Google Search grounding to connect Gemini to real-time web content:

1. Automatic Search Decision: Gemini determines if a search would improve the answer
2. Query Generation: Generates appropriate search queries automatically
3. Result Processing: Processes search results and synthesizes information
4. Citation Generation: Returns grounded responses with verifiable sources

Benefits:

• Reduces hallucinations by grounding responses in web content
• Provides up-to-date information beyond training cutoff
• Includes automatic citation links for verification
• Supports multi-query search for comprehensive coverage

Model Selection

gemini-2.5-flash (default):

• Fast response times
• Cost-effective for high-volume queries
• Good for straightforward questions
• Recommended for most use cases

gemini-2.5-pro (--pro flag):

• More powerful reasoning capabilities
• Better for complex analysis
• Higher quality responses
• More expensive per query

Verbosity Levels

No flag (WARNING):

• Only errors and warnings
• Clean JSON/text output

-v (INFO):

[INFO] Starting query command
[INFO] GeminiClient initialized successfully
[INFO] Querying with model 'gemini-2.5-flash' and Google Search grounding
[INFO] Query completed successfully

-vv (DEBUG):

[DEBUG] Validated prompt: Who won euro 2024?...
[DEBUG] Initializing GeminiClient
[DEBUG] Calling Gemini API: model=gemini-2.5-flash
[DEBUG] Extracted 7 citations
[DEBUG] Web search queries: ['who won euro 2024', 'Euro 2024 winner']

-vvv (TRACE):

[DEBUG] connect_tcp.started host='generativelanguage.googleapis.com' port=443
[DEBUG] start_tls.started ssl_context=<ssl.SSLContext...>
[DEBUG] send_request_headers.started request=<Request [b'POST']>

Library Usage

The tool can also be used as a Python library:

from gemini_google_search_tool import (
    GeminiClient,
    query_with_grounding,
    add_inline_citations,
)

# Initialize client
client = GeminiClient()  # Reads GEMINI_API_KEY from environment

# Query with grounding
response = query_with_grounding(
    client=client,
    prompt="Who won euro 2024?",
    model="gemini-2.5-flash",
)

# Access response
print(response.response_text)
print(f"Citations: {len(response.citations)}")

# Add inline citations
if response.grounding_segments:
    text_with_citations = add_inline_citations(
        response.response_text,
        response.grounding_segments,
        response.citations,
    )
    print(text_with_citations)

Pipeline Integration

The tool follows CLI-first design principles for pipeline integration:

JSON to stdout, logs to stderr:

# Parse JSON output
gemini-google-search-tool query "test" | jq '.response_text'

# Filter citations
gemini-google-search-tool query "test" | jq '.citations[]'

# Check exit code
gemini-google-search-tool query "test" && echo "Success"

Stdin support:

# From file
cat question.txt | gemini-google-search-tool query --stdin

# From command output
echo "Who won euro 2024?" | gemini-google-search-tool query --stdin

</details> <details> <summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>

Common Issues

Issue: Missing API Key

Error: GEMINI_API_KEY environment variable is required.
Set it with: export GEMINI_API_KEY='your-api-key'

Solution:

1. Get an API key from Google AI Studio
2. Set environment variable: export GEMINI_API_KEY='your-key'
3. Or add to shell profile: echo 'export GEMINI_API_KEY="your-key"' >> ~/.bashrc

---

Issue: Empty or Invalid Response

Error: Query failed: Invalid response format

Solution:

1. Check API key is valid
2. Verify internet connection
3. Try with verbose mode: -vv to see detailed error
4. Check Gemini API status page

---

Issue: Rate Limiting

Error: Query failed: Rate limit exceeded

Solution:

1. Wait and retry
2. Check API quota in Google AI Studio
3. Consider upgrading API tier for higher limits

---

Issue: Module Import Error (Library Usage)

ImportError: No module named 'gemini_google_search_tool'

Solution:

1. Install package: uv tool install .
2. Or use in development: uv sync then uv run python script.py
3. Verify installation: python -c "import gemini_google_search_tool"

Getting Help

# General help
gemini-google-search-tool --help

# Command-specific help
gemini-google-search-tool query --help
gemini-google-search-tool completion --help

# Version info
gemini-google-search-tool --version

Debug Mode

Use -vv or -vvv for detailed debugging:

# Debug API calls and response processing
gemini-google-search-tool query "test" -vv

# Trace HTTP requests (shows full request/response)
gemini-google-search-tool query "test" -vvv

</details>

Exit Codes

• 0: Success - query completed successfully
• 1: Error - client error, invalid arguments, or query failure

Output Formats

JSON (default):

• Structured output with response_text and citations
• Machine-parseable for pipeline integration
• Always includes citations array
• Optional grounding_metadata with -vv or -vvv

Markdown (--text):

• Human-readable format
• Response text followed by citations section
• Good for direct reading or documentation

Verbosity (stderr):

• Logs and verbose output go to stderr
• Keeps stdout clean for JSON parsing
• Use -v/-vv/-vvv for progressively more detail

Best Practices

1. Use Flash Model by Default: The gemini-2.5-flash model is fast and cost-effective for most queries
2. Add Citations for Verification: Use --add-citations when you need inline source links
3. Pipeline Integration: Pipe JSON output through jq for structured data processing
4. Verbosity for Debugging: Use -vv when troubleshooting, -vvv for HTTP-level details
5. Environment Variables: Store API key securely in shell profile, not in scripts
6. Error Handling: Always check exit codes when using in scripts or automation
7. Model Selection: Use --pro for complex analysis requiring deeper reasoning

Resources

• GitHub Repository: https://github.com/dnvriend/gemini-google-search-tool
• Google Search Grounding Docs: https://ai.google.dev/gemini-api/docs/grounding
• Gemini API Documentation: https://ai.google.dev/gemini-api/docs
• Get API Key: https://aistudio.google.com/app/apikey
• Python Package: Installable via uv tool install
• Developer Guide: See CLAUDE.md in repository