Web Search Plus

Multi-provider web search with Intelligent Auto-Routing: Serper (Google), Tavily (Research), Exa (Neural).

NEW in v2.1.0: Intelligent multi-signal analysis with confidence scoring!

---

🧠 Intelligent Auto-Routing

No need to choose a provider — just search! The skill uses multi-signal analysis to understand your query intent:

# These queries are intelligently routed with confidence scoring:
python3 scripts/search.py -q "how much does iPhone 16 cost"     # → Serper (68% MEDIUM)
python3 scripts/search.py -q "how does quantum entanglement work"  # → Tavily (86% HIGH)
python3 scripts/search.py -q "startups similar to Notion"       # → Exa (76% HIGH)
python3 scripts/search.py -q "MacBook Pro M3 specs review"      # → Serper (70% HIGH)
python3 scripts/search.py -q "explain pros and cons of React"   # → Tavily (85% HIGH)
python3 scripts/search.py -q "companies like stripe.com"        # → Exa (100% HIGH)

How It Works

The routing engine analyzes multiple signals:

🛒 Shopping Intent → Serper

Signal Type	Examples	Weight
Price patterns	"how much", "price of", "cost of"	HIGH
Purchase intent	"buy", "purchase", "order", "where to buy"	HIGH
Deal signals	"deal", "discount", "cheap", "best price"	MEDIUM
Product + Brand	"iPhone 16", "Sony headphones" + specs/review	HIGH
Local business	"near me", "restaurants", "hotels"	HIGH

📚 Research Intent → Tavily

Signal Type	Examples	Weight
Explanation	"how does", "why does", "explain", "what is"	HIGH
Analysis	"compare", "pros and cons", "difference between"	HIGH
Learning	"tutorial", "guide", "understand", "learn"	MEDIUM
Depth	"in-depth", "comprehensive", "detailed"	MEDIUM
Complex queries	Long, multi-clause questions	BONUS

🔍 Discovery Intent → Exa

Signal Type	Examples	Weight
Similarity	"similar to", "alternatives to", "competitors"	VERY HIGH
Company discovery	"companies like", "startups doing", "who else"	HIGH
URL detection	Any URL or domain (stripe.com)	VERY HIGH
Academic	"arxiv", "research papers", "github projects"	HIGH
Funding	"Series A", "YC", "funded startup"	HIGH

Confidence Scoring

Every routing decision includes a confidence level:

Confidence	Level	Meaning
70-100%	HIGH	Strong signal match, very reliable
40-69%	MEDIUM	Good match, should work well
0-39%	LOW	Ambiguous query, using fallback

Debug Routing Decisions

See the full analysis:

python3 scripts/search.py --explain-routing -q "how much does iPhone 16 Pro cost"

Output:

{
  "query": "how much does iPhone 16 Pro cost",
  "routing_decision": {
    "provider": "serper",
    "confidence": 0.68,
    "confidence_level": "medium",
    "reason": "moderate_confidence_match"
  },
  "scores": {"serper": 7.0, "tavily": 0.0, "exa": 0.0},
  "top_signals": [
    {"matched": "how much", "weight": 4.0},
    {"matched": "brand + product detected", "weight": 3.0}
  ],
  "query_analysis": {
    "word_count": 7,
    "is_complex": false,
    "has_url": null,
    "recency_focused": false
  }
}

---

🔍 When to Use This Skill vs Built-in Brave Search

Use Built-in Brave Search when:

• ✅ General web searches (news, info, questions)
• ✅ Privacy is important
• ✅ Quick lookups without specific requirements

Use web-search-plus when:

→ Serper (Google results):

• 🛍️ Product specs, prices, shopping - "Compare iPhone 16 vs Samsung S24"
• 📍 Local businesses, places - "Best pizza in Vienna"
• 🎯 "Google it" - Explicitly wants Google results
• 📰 Shopping/images/news - --type shopping/images/news
• 🏆 Knowledge Graph - Structured info (prices, ratings, etc.)

→ Tavily (AI-optimized research):

• 📚 Research questions - "How does quantum computing work?"
• 🔬 Deep dives - Complex multi-part questions
• 📄 Full page content - Not just snippets (--raw-content)
• 🎓 Academic research - Synthesized answers
• 🔒 Domain filtering - --include-domains for trusted sources

→ Exa (Neural semantic search):

• 🔗 Similar pages - "Sites like OpenAI.com" (--similar-url)
• 🏢 Company discovery - "AI companies like Anthropic"
• 📝 Research papers - --category "research paper"
• 💻 GitHub projects - --category github
• 📅 Date-specific - --start-date / --end-date

---

Provider Comparison

Feature	Serper	Tavily	Exa
Speed	⚡⚡⚡	⚡⚡	⚡⚡
Factual Accuracy	⭐⭐⭐	⭐⭐⭐	⭐⭐
Semantic Understanding	⭐	⭐⭐	⭐⭐⭐
Research Quality	⭐⭐	⭐⭐⭐	⭐⭐
Full Page Content	✗	✓	✓
Shopping/Local	✓	✗	✗
Similar Pages	✗	✗	✓
Knowledge Graph	✓	✗	✗

---

Usage Examples

Auto-Routed (Recommended)

python3 scripts/search.py -q "iPhone 16 Pro Max price"          # → Serper
python3 scripts/search.py -q "how does HTTPS encryption work"   # → Tavily
python3 scripts/search.py -q "startups similar to Notion"       # → Exa

Explicit Provider

python3 scripts/search.py -p serper -q "weather Vienna" --type weather
python3 scripts/search.py -p tavily -q "quantum computing" --depth advanced
python3 scripts/search.py -p exa --similar-url "https://stripe.com" --category company

---

Configuration

config.json

{
  "auto_routing": {
    "enabled": true,
    "fallback_provider": "serper",
    "confidence_threshold": 0.3,
    "disabled_providers": []
  },
  "serper": {"country": "us", "language": "en"},
  "tavily": {"depth": "basic"},
  "exa": {"type": "neural"}
}

---

Output Format

{
  "provider": "serper",
  "query": "iPhone 16 price",
  "results": [{"title": "...", "url": "...", "snippet": "...", "score": 0.95}],
  "answer": "Synthesized answer...",
  "routing": {
    "auto_routed": true,
    "provider": "serper",
    "confidence": 0.78,
    "confidence_level": "high",
    "reason": "high_confidence_match",
    "top_signals": [{"matched": "price", "weight": 3.0}]
  }
}

---

Environment Setup

# In your .env file (use 'export' prefix!):
export SERPER_API_KEY="your-key"   # https://serper.dev
export TAVILY_API_KEY="your-key"   # https://tavily.com  
export EXA_API_KEY="your-key"      # https://exa.ai

# Then load with: source .env

---

FAQ

General

Q: How does auto-routing decide which provider to use?

Multi-signal analysis scores each provider based on: price patterns, explanation phrases, similarity keywords, URLs, product+brand combos, and query complexity. Highest score wins. Use --explain-routing to see the decision breakdown.

Q: What if it picks the wrong provider?

Override with -p serper/tavily/exa. Check --explain-routing to understand why it chose differently.

Q: What does "low confidence" mean?

Query is ambiguous (e.g., "Tesla" could be cars, stock, or company). Falls back to Serper. Results may vary.

Q: Can I disable a provider?

Yes! In config.json: "disabled_providers": ["exa"]

API Keys

Q: Which API keys do I need?

At minimum ONE key. You can use just Serper, just Tavily, or all three. Missing keys = that provider is skipped.

Q: Where do I get API keys?

• Serper: https://serper.dev (100 free searches/month)
• Tavily: https://tavily.com (1000 free searches/month)
• Exa: https://exa.ai (limited free tier)

Q: How do I set API keys?

Create .env in your workspace:

export SERPER_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
export EXA_API_KEY="your-key"

Then source .env or add to your shell profile.

Routing Details

Q: How do I know which provider handled my search?

Check routing.provider in JSON output, or [🔍 Searched with: Provider] in chat responses.

Q: Why does it sometimes choose Serper for research questions?

If the query has brand/product signals (e.g., "how does Tesla FSD work"), shopping intent may outweigh research intent. Override with -p tavily.

Q: What's the confidence threshold?

Default: 0.3 (30%). Below this = low confidence, uses fallback. Adjustable in config.json.

Troubleshooting

Q: "No API key found" error?

Make sure keys are exported (not just set): export SERPER_API_KEY="..." and sourced.

Q: Getting empty results?

1. Check API key is valid
2. Try a different provider with -p
3. Some queries have no results (very niche topics)

Q: Rate limited?

Each provider has limits. Spread queries across providers or wait. Serper: 100/month free, Tavily: 1000/month free.

For Clawdbot Users

Q: How do I use this in chat?

Just ask! Clawdbot auto-detects search intent. Or explicitly: "search with web-search-plus for..."

Q: Does it replace built-in Brave Search?

No, it's complementary. Use Brave for quick lookups, web-search-plus for research/shopping/discovery.

Q: Can I see which provider was used?

Yes! SOUL.md can include attribution: [🔍 Searched with: Serper/Tavily/Exa]