---
name: web-search
description: Search the web using a configured search provider. Use when the user explicitly asks to search, look up current information, or needs real-time data such as news, prices, or recent events.
metadata:
  { "mmclaw": { "emoji": "🔍", "os": ["linux", "darwin", "win32"], "requires": { "bins": ["python3"] } } }
---
# Web Search Skill

Use this skill when the user explicitly asks to search the web or needs real-time information. Trigger phrases: "search", "look up", "latest", "current", "today", "find online", "what's the news on".

Do NOT trigger this skill proactively. Only search when the user clearly requests it or the question cannot be answered from existing knowledge.

**Note**: "provider" here refers to the **search provider** (Tavily, Serper, SerpApi, Brave), not the LLM provider configured elsewhere in your setup. These are independent settings.

**IMPORTANT — provider lock-in**: Only use the search provider set in the config. Do NOT fall back to another provider silently. If the configured provider fails or has no key, inform the user and stop.

## CLI Tool

All operations use:
```
python $MMCLAW_WORKSPACE/skills/web-search/web_search.py <command> [args]
```

## Preconditions

Run `status` first. Handle output codes:

| Output | Action |
|--------|--------|
| `NOT_CONFIGURED` | No config file — show provider list below, ask user to choose, then run setup |
| `INVALID_CONFIG` | Config file is corrupt — ask user to re-run setup |
| `NO_PROVIDER` | Config exists but no provider set — ask user to choose a provider |
| `NO_API_KEY:<provider>` | Provider set but key missing — ask user for their API key |
| JSON with `"configured": true` | Ready — proceed with search |

```
python $MMCLAW_WORKSPACE/skills/web-search/web_search.py status
```

---

## Commands

### Check Status
```
python $MMCLAW_WORKSPACE/skills/web-search/web_search.py status
```

### Search
```
python $MMCLAW_WORKSPACE/skills/web-search/web_search.py search "<query>" [--count N] [--depth <depth>] [--topic <topic>] [--time-range <range>] [--include-domains <domains>] [--exclude-domains <domains>] [--raw-content]
```
Returns a JSON array of `{title, url, snippet}` objects (Tavily also includes `score` and optionally `raw_content`). Default count: 5.

**Tavily-only options** (ignored by other providers):

| Option | Values | Default | Description |
|--------|--------|---------|-------------|
| `--depth` | `ultra-fast`, `fast`, `basic`, `advanced` | `basic` | Search depth / relevance trade-off |
| `--topic` | `general`, `news` | `general` | Topic filter |
| `--time-range` | `day`, `week`, `month`, `year` | — | Restrict to recent results |
| `--include-domains` | comma-separated | — | Only return results from these domains |
| `--exclude-domains` | comma-separated | — | Exclude results from these domains |
| `--raw-content` | flag | false | Include full page content in results |

**Tips for Tavily:**
- Keep queries under 400 characters — write search terms, not prompts
- Use `--depth advanced` when precision matters (research); `--depth fast` when latency matters
- Use `--include-domains` to focus on trusted sources
- Use `--topic news` + `--time-range week` for current events

**IMPORTANT — always report results verbatim**: Present Title, URL, and key points from the results directly in your reply. If a result contains a specific version number, date, or fact, quote it exactly — do NOT paraphrase with vague terms like "recent" or "the latest version". Do NOT tell the user to check the output themselves.

### Setup (save provider + API key)
```
python $MMCLAW_WORKSPACE/skills/web-search/web_search.py setup <provider> <api_key>
```
`provider` must be one of: `tavily`, `serper`, `serpapi`, `brave`.

---

## Provider Setup Flow

If not configured, show this list and ask the user to choose. Translate descriptions into the language the user has been writing in.

**⭐ 1. Tavily** (recommended) — https://tavily.com
- Free: 1,000 queries/month, no credit card required
- Pro: LLM-optimized results with relevance scores, depth control, topic/time filters, raw page content

**2. Serper** — https://serper.dev
- Free: 2,500 queries lifetime (one-time, does not reset), no credit card required
- Pro: Fast, Google results, easiest to get started
- Con: Fewer advanced filtering options

**3. SerpApi** — https://serpapi.com
- Free: 250 queries/month, no credit card required
- Pro: Supports Google, Bing, DuckDuckGo and more
- Con: Free tier is very limited (250/month)

**4. Brave** — https://brave.com/search/api/
- Free: None, paid only
- Pro: Independent search index, not reliant on Google
- Con: Requires credit card, no free tier

Once the user chooses a provider and shares their API key, run:
```
python $MMCLAW_WORKSPACE/skills/web-search/web_search.py setup <provider> <api_key>
```

---

## Error Handling

| Error | Action |
|-------|--------|
| `NOT_CONFIGURED` | Show provider list, ask user to choose, then run setup |
| `NO_PROVIDER` | Ask user to set a provider — do NOT default to any |
| `HTTP 401` | API key is invalid — ask the user to re-enter it and re-run setup |
| `HTTP 429` | Monthly quota exhausted — inform the user, suggest upgrading or switching provider |
| `TIMEOUT` | Inform the user, answer from existing knowledge, note it may not be current |

On any error, do NOT retry automatically and do NOT switch providers silently.

---

## Notes

- To switch providers, re-run `setup` with the new provider and key
- Multiple API keys can coexist in the config — only the active provider is used
- Tavily and SerpApi free tiers reset monthly; Serper's free quota is a one-time lifetime allocation (does not reset)
