zhongwei/gh-dnvriend-gemini-google-search-tool-plugins-gemini-google-search-tool

Files

Zhongwei Li 611a646dde Initial commit

2025-11-29 18:23:20 +08:00

12 KiB

Raw Permalink Blame History

name, description

name	description
skill-gemini-google-search-tool	Query Gemini with Google Search grounding

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

📖 Core Commands (Click to expand)

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.

⚙️ Advanced Features (Click to expand)

Google Search Grounding

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

Automatic Search Decision: Gemini determines if a search would improve the answer
Query Generation: Generates appropriate search queries automatically
Result Processing: Processes search results and synthesizes information
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

🔧 Troubleshooting (Click to expand)

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:

Get an API key from Google AI Studio
Set environment variable: export GEMINI_API_KEY='your-key'
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:

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

Issue: Rate Limiting

Error: Query failed: Rate limit exceeded

Solution:

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

Issue: Module Import Error (Library Usage)

ImportError: No module named 'gemini_google_search_tool'

Solution:

Install package: uv tool install .
Or use in development: uv sync then uv run python script.py
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

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

Use Flash Model by Default: The gemini-2.5-flash model is fast and cost-effective for most queries
Add Citations for Verification: Use --add-citations when you need inline source links
Pipeline Integration: Pipe JSON output through jq for structured data processing
Verbosity for Debugging: Use -vv when troubleshooting, -vvv for HTTP-level details
Environment Variables: Store API key securely in shell profile, not in scripts
Error Handling: Always check exit codes when using in scripts or automation
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

12 KiB Raw Permalink Blame History

When to use

Gemini Google Search Tool Skill

Purpose

When to Use This Skill

CLI Tool: gemini-google-search-tool

Installation

Prerequisites

Quick Start

Progressive Disclosure

query - Query Gemini with Google Search Grounding

completion - Generate Shell Completion Scripts

Google Search Grounding

Model Selection

Verbosity Levels

Library Usage

Pipeline Integration

Common Issues

Getting Help

Debug Mode

Exit Codes

Output Formats

Best Practices

Resources

12 KiB

Raw Permalink Blame History