| 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)
