serper

Serper

Google search via Serper API. Fetches results AND reads the actual web pages to extract clean full-text content via trafilatura. Not just snippets — full article text.

How It Works

1. Serper API call — fast Google search, returns result URLs instantly

2. Concurrent page scraping — all result pages are fetched and extracted in parallel using trafilatura with a 3-second timeout per page

3. Streamed output — results print one at a time as each page finishes

Each invocation gives you 5 results (default mode) or up to 6 results (current mode), each with full page content. This is already a lot of information.

---

Query Discipline

Craft ONE good search query. That is almost always enough.

Each call returns multiple results with full page text — you get broad coverage from a single query. Do not run multiple searches to "explore" a topic. One well-chosen query with the right mode covers it.

At most two calls if the user's request genuinely spans two distinct topics (e.g. "compare X vs Y" where X and Y need separate searches, or one default + one current call for different aspects). Never more than two. Do NOT:

• -Run the same query with different wording to "get more results"
• -Run sequential searches to "dig deeper" — the full page content is already deep
• -Run one search to find something, then another to follow up — read the content you already have

---

When to Use This Skill

Use serper when:

• -Any question that needs current, factual information from the web
• -Research topics that need full article content, not just snippets
• -News and current events
• -Product info, prices, comparisons, reviews
• -Technical docs, how-to guides
• -Anything where reading the actual page matters

Do NOT use this skill for:

• -Questions you can answer from your training data
• -Pure math, code execution, creative writing
• -Greetings, chitchat

IMPORTANT: This skill already fetches and extracts full page content. Do NOT use web_fetch, WebFetch, or any other URL-fetching tool on the URLs returned by this skill. The content is already included in the output.

---

Two Search Modes

There are exactly two modes. Pick the right one based on the query:

default — General search (all-time)

• -All-time Google web search, 5 results, each enriched with full page content
• -Use for: general questions, research, how-to, evergreen topics, product info, technical docs, comparisons, tutorials, anything NOT time-sensitive

current — News and recent info

• -Past-week Google web search (3 results) + Google News (3 results), each enriched with full page content
• -Use for: news, current events, recent developments, breaking news, announcements, anything time-sensitive

#### Mode Selection Guide

| Query signals | Mode |

|---------------|------|

| "how does X work", "what is X", "explain X" | default |

| Product research, comparisons, tutorials | default |

| Technical documentation, guides | default |

| Historical topics, evergreen content | default |

| "news", "latest", "today", "this week", "recent" | current |

| "what happened", "breaking", "announced", "released" | current |

| Current events, politics, sports scores, stock prices | current |

---

Locale (REQUIRED for non-English queries)

Default is global — no country filter, English results. This ONLY works for English queries. You MUST ALWAYS set --gl and --hl when ANY of these are true:

• -The user's message is in a non-English language
• -The search query you construct is in a non-English language
• -The user mentions a specific country, city, or region
• -The user asks for local results (prices, news, stores, etc.) in a non-English context

If the user writes in German, you MUST pass --gl de --hl de. No exceptions.

| Scenario | Flags |

|----------|-------|

| English query, no country target | *(omit --gl and --hl)* |

| German query OR user writes in German OR targeting DE/AT/CH | --gl de --hl de |

| French query OR user writes in French OR targeting France | --gl fr --hl fr |

| Any other non-English language/country | --gl XX --hl XX (ISO codes) |

Rule of thumb: If the query string contains non-English words, set --gl and --hl to match that language.

---

How to Invoke

python3 scripts/search.py -q "QUERY" [--mode MODE] [--gl COUNTRY] [--hl LANG]

Examples

English, general research
python3 scripts/search.py -q "how does HTTPS work"

English, time-sensitive
python3 scripts/search.py -q "OpenAI latest announcements" --mode current

German query — set locale + current mode for news/prices
python3 scripts/search.py -q "aktuelle Preise iPhone" --mode current --gl de --hl de

German news
python3 scripts/search.py -q "Nachrichten aus Berlin" --mode current --gl de --hl de

French product research
python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr

---

Output Format

The output is a streamed JSON array — elements print one at a time as each page is scraped:

[{"query": "...", "mode": "default", "locale": {"gl": "world", "hl": "en"}, "results": [{"title": "...", "url": "...", "source": "web"}, ...]}
,{"title": "...", "url": "...", "source": "web", "content": "Full extracted page text..."}
,{"title": "...", "url": "...", "source": "news", "date": "2 hours ago", "content": "Full article text..."}
]

The first element is search metadata. Each following element contains a result with full extracted content.

Result fields:

• -title — page title
• -url — source URL
• -source — "web", "news", or "knowledge_graph"
• -content — full extracted page text (falls back to search snippet if extraction fails)
• -date — present when available (news results always, web results sometimes)

---

CLI Reference

| Flag | Description |

|------|-------------|

| -q, --query | Search query (required) |

| -m, --mode | default (all-time, 5 results) or current (past week + news, 3 each) |

| --gl | Country code (e.g. de, us, fr, at, ch) |

| --hl | Language code (e.g. en, de, fr) |