skill-gemini-google-search-tool

What this skill does

# 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

```bash
# 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](https://github.com/astral-sh/uv) package manager
- Google Gemini API key ([get one free](https://aistudio.google.com/app/apikey))
- `GEMINI_API_KEY` environment variable

### Quick Start

```bash
# 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:**
```bash
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:**
```bash
# 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):**
```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`):**
```markdown
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:**
```bash
gemini-google-search-tool completion {bash|zsh|fish}
```

**Arguments:**
- `SHELL`: Shell type (bash, zsh, or fish)

**Examples:**
```bash
# 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:

```python
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:**
```bash
# 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:**
```bash
# From file
cat question.txt | gemini-google-se