{"skill":{"slug":"tavily","displayName":"Tavily AI Search","summary":"AI-optimized web search using Tavily Search API. Use when you need comprehensive web research, current events lookup, domain-specific search, or AI-generated answer summaries. Tavily is optimized for LLM consumption with clean structured results, answer generation, and raw content extraction. Best for research tasks, news queries, fact-checking, and gathering authoritative sources.","description":"---\nname: tavily\ndescription: AI-optimized web search using Tavily Search API. Use when you need comprehensive web research, current events lookup, domain-specific search, or AI-generated answer summaries. Tavily is optimized for LLM consumption with clean structured results, answer generation, and raw content extraction. Best for research tasks, news queries, fact-checking, and gathering authoritative sources.\n---\n\n# Tavily AI Search\n\n## Overview\n\nTavily is a search engine specifically optimized for Large Language Models and AI applications. Unlike traditional search APIs, Tavily provides AI-ready results with optional answer generation, clean content extraction, and domain filtering capabilities.\n\n**Key capabilities:**\n- AI-generated answer summaries from search results\n- Clean, structured results optimized for LLM processing\n- Fast (`basic`) and comprehensive (`advanced`) search modes\n- Domain filtering (include/exclude specific sources)\n- News-focused search for current events\n- Image search with relevant visual content\n- Raw content extraction for deeper analysis\n\n## Architecture\n\n```mermaid\ngraph TB\n    A[User Query] --> B{Search Mode}\n    B -->|basic| C[Fast Search<br/>1-2s response]\n    B -->|advanced| D[Comprehensive Search<br/>5-10s response]\n    \n    C --> E[Tavily API]\n    D --> E\n    \n    E --> F{Topic Filter}\n    F -->|general| G[Broad Web Search]\n    F -->|news| H[News Sources<br/>Last 7 days]\n    \n    G --> I[Domain Filtering]\n    H --> I\n    \n    I --> J{Include Domains?}\n    J -->|yes| K[Filter to Specific Domains]\n    J -->|no| L{Exclude Domains?}\n    K --> M[Search Results]\n    L -->|yes| N[Remove Unwanted Domains]\n    L -->|no| M\n    N --> M\n    \n    M --> O{Response Options}\n    O --> P[AI Answer<br/>Summary]\n    O --> Q[Structured Results<br/>Title, URL, Content, Score]\n    O --> R[Images<br/>if requested]\n    O --> S[Raw HTML Content<br/>if requested]\n    \n    P --> T[Return to Agent]\n    Q --> T\n    R --> T\n    S --> T\n    \n    style E fill:#4A90E2\n    style P fill:#7ED321\n    style Q fill:#7ED321\n    style R fill:#F5A623\n    style S fill:#F5A623\n```\n\n## Quick Start\n\n### Basic Search\n\n```bash\n# Simple query with AI answer\nscripts/tavily_search.py \"What is quantum computing?\"\n\n# Multiple results\nscripts/tavily_search.py \"Python best practices\" --max-results 10\n```\n\n### Advanced Search\n\n```bash\n# Comprehensive research mode\nscripts/tavily_search.py \"Climate change solutions\" --depth advanced\n\n# News-focused search\nscripts/tavily_search.py \"AI developments 2026\" --topic news\n```\n\n### Domain Filtering\n\n```bash\n# Search only trusted domains\nscripts/tavily_search.py \"Python tutorials\" \\\n  --include-domains python.org docs.python.org realpython.com\n\n# Exclude low-quality sources\nscripts/tavily_search.py \"How to code\" \\\n  --exclude-domains w3schools.com geeksforgeeks.org\n```\n\n### With Images\n\n```bash\n# Include relevant images\nscripts/tavily_search.py \"Eiffel Tower architecture\" --images\n```\n\n## Search Modes\n\n### Basic vs Advanced\n\n| Mode | Speed | Coverage | Use Case |\n|------|-------|----------|----------|\n| **basic** | 1-2s | Good | Quick facts, simple queries |\n| **advanced** | 5-10s | Excellent | Research, complex topics, comprehensive analysis |\n\n**Decision tree:**\n1. Need a quick fact or definition? → Use `basic`\n2. Researching a complex topic? → Use `advanced`\n3. Need multiple perspectives? → Use `advanced`\n4. Time-sensitive query? → Use `basic`\n\n### General vs News\n\n| Topic | Time Range | Sources | Use Case |\n|-------|------------|---------|----------|\n| **general** | All time | Broad web | Evergreen content, tutorials, documentation |\n| **news** | Last 7 days | News sites | Current events, recent developments, breaking news |\n\n**Decision tree:**\n1. Query contains \"latest\", \"recent\", \"current\", \"today\"? → Use `news`\n2. Looking for historical or evergreen content? → Use `general`\n3. Need up-to-date information? → Use `news`\n\n## API Key Setup\n\n### Option 1: Clawdbot Config (Recommended)\n\nAdd to your Clawdbot config:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"tavily\": {\n        \"enabled\": true,\n        \"apiKey\": \"tvly-YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\nAccess in scripts via Clawdbot's config system.\n\n### Option 2: Environment Variable\n\n```bash\nexport TAVILY_API_KEY=\"tvly-YOUR_API_KEY_HERE\"\n```\n\nAdd to `~/.clawdbot/.env` or your shell profile.\n\n### Getting an API Key\n\n1. Visit https://tavily.com\n2. Sign up for an account\n3. Navigate to your dashboard\n4. Generate an API key (starts with `tvly-`)\n5. Note your plan's rate limits and credit allocation\n\n## Common Use Cases\n\n### 1. Research & Fact-Finding\n\n```bash\n# Comprehensive research with answer\nscripts/tavily_search.py \"Explain quantum entanglement\" --depth advanced\n\n# Multiple authoritative sources\nscripts/tavily_search.py \"Best practices for REST API design\" \\\n  --max-results 10 \\\n  --include-domains github.com microsoft.com google.com\n```\n\n### 2. Current Events\n\n```bash\n# Latest news\nscripts/tavily_search.py \"AI policy updates\" --topic news\n\n# Recent developments in a field\nscripts/tavily_search.py \"quantum computing breakthroughs\" \\\n  --topic news \\\n  --depth advanced\n```\n\n### 3. Domain-Specific Research\n\n```bash\n# Academic sources only\nscripts/tavily_search.py \"machine learning algorithms\" \\\n  --include-domains arxiv.org scholar.google.com ieee.org\n\n# Technical documentation\nscripts/tavily_search.py \"React hooks guide\" \\\n  --include-domains react.dev\n```\n\n### 4. Visual Research\n\n```bash\n# Gather visual references\nscripts/tavily_search.py \"modern web design trends\" \\\n  --images \\\n  --max-results 10\n```\n\n### 5. Content Extraction\n\n```bash\n# Get raw HTML content for deeper analysis\nscripts/tavily_search.py \"Python async/await\" \\\n  --raw-content \\\n  --max-results 5\n```\n\n## Response Handling\n\n### AI Answer\n\nThe AI-generated answer provides a concise summary synthesized from search results:\n\n```python\n{\n  \"answer\": \"Quantum computing is a type of computing that uses quantum-mechanical phenomena...\"\n}\n```\n\n**Use when:**\n- Need a quick summary\n- Want synthesized information from multiple sources\n- Looking for a direct answer to a question\n\n**Skip when** (`--no-answer`):\n- Only need source URLs\n- Want to form your own synthesis\n- Conserving API credits\n\n### Structured Results\n\nEach result includes:\n- `title`: Page title\n- `url`: Source URL\n- `content`: Extracted text snippet\n- `score`: Relevance score (0-1)\n- `raw_content`: Full HTML (if `--raw-content` enabled)\n\n### Images\n\nWhen `--images` is enabled, returns URLs of relevant images found during search.\n\n## Best Practices\n\n### 1. Choose the Right Search Depth\n\n- Start with `basic` for most queries (faster, cheaper)\n- Escalate to `advanced` only when:\n  - Initial results are insufficient\n  - Topic is complex or nuanced\n  - Need comprehensive coverage\n\n### 2. Use Domain Filtering Strategically\n\n**Include domains for:**\n- Academic research (`.edu` domains)\n- Official documentation (official project sites)\n- Trusted news sources\n- Known authoritative sources\n\n**Exclude domains for:**\n- Known low-quality content farms\n- Irrelevant content types (Pinterest for non-visual queries)\n- Sites with paywalls or access restrictions\n\n### 3. Optimize for Cost\n\n- Use `basic` depth as default\n- Limit `max_results` to what you'll actually use\n- Disable `include_raw_content` unless needed\n- Cache results locally for repeated queries\n\n### 4. Handle Errors Gracefully\n\nThe script provides helpful error messages:\n\n```bash\n# Missing API key\nError: Tavily API key required\nSetup: Set TAVILY_API_KEY environment variable or pass --api-key\n\n# Package not installed\nError: tavily-python package not installed\nTo install: pip install tavily-python\n```\n\n## Integration Patterns\n\n### Programmatic Usage\n\n```python\nfrom tavily_search import search\n\nresult = search(\n    query=\"What is machine learning?\",\n    api_key=\"tvly-...\",\n    search_depth=\"advanced\",\n    max_results=10\n)\n\nif result.get(\"success\"):\n    print(result[\"answer\"])\n    for item in result[\"results\"]:\n        print(f\"{item['title']}: {item['url']}\")\n```\n\n### JSON Output for Parsing\n\n```bash\nscripts/tavily_search.py \"Python tutorials\" --json > results.json\n```\n\n### Chaining with Other Tools\n\n```bash\n# Search and extract content\nscripts/tavily_search.py \"React documentation\" --json | \\\n  jq -r '.results[].url' | \\\n  xargs -I {} curl -s {}\n```\n\n## Comparison with Other Search APIs\n\n**vs Brave Search:**\n- ✅ AI answer generation\n- ✅ Raw content extraction\n- ✅ Better domain filtering\n- ❌ Slower than Brave\n- ❌ Costs credits\n\n**vs Perplexity:**\n- ✅ More control over sources\n- ✅ Raw content available\n- ✅ Dedicated news mode\n- ≈ Similar answer quality\n- ≈ Similar speed\n\n**vs Google Custom Search:**\n- ✅ LLM-optimized results\n- ✅ Answer generation\n- ✅ Simpler API\n- ❌ Smaller index\n- ≈ Similar cost structure\n\n## Troubleshooting\n\n### Script Won't Run\n\n```bash\n# Make executable\nchmod +x scripts/tavily_search.py\n\n# Check Python version (requires 3.6+)\npython3 --version\n\n# Install dependencies\npip install tavily-python\n```\n\n### API Key Issues\n\n```bash\n# Verify API key format (should start with tvly-)\necho $TAVILY_API_KEY\n\n# Test with explicit key\nscripts/tavily_search.py \"test\" --api-key \"tvly-...\"\n```\n\n### Rate Limit Errors\n\n- Check your plan's credit allocation at https://tavily.com\n- Reduce `max_results` to conserve credits\n- Use `basic` depth instead of `advanced`\n- Implement local caching for repeated queries\n\n## Resources\n\nSee [api-reference.md](references/api-reference.md) for:\n- Complete API parameter documentation\n- Response format specifications\n- Error handling details\n- Cost and rate limit information\n- Advanced usage examples\n\n## Dependencies\n\n- Python 3.6+\n- `tavily-python` package (install: `pip install tavily-python`)\n- Valid Tavily API key\n\n## Credits & Attribution\n\n- Tavily API: https://tavily.com\n- Python SDK: https://github.com/tavily-ai/tavily-python\n- Documentation: https://docs.tavily.com\n","tags":{"ai":"1.0.0","latest":"1.0.0","search":"1.0.0","web":"1.0.0"},"stats":{"comments":0,"downloads":42275,"installsAllTime":610,"installsCurrent":609,"stars":36,"versions":1},"createdAt":1769287990264,"updatedAt":1778987032251},"latestVersion":{"version":"1.0.0","createdAt":1769287990264,"changelog":"Initial release: AI-optimized web search with basic/advanced modes, domain filtering, news search, image search, and AI answer generation.","license":null},"metadata":null,"owner":{"handle":"bert-builder","userId":"s1790dh35hvx480x9zfnvd0fjs884syg","displayName":"bert-builder","image":"https://avatars.githubusercontent.com/u/256852494?v=4"},"moderation":null}