Metadata

name: search
description: Search the web using Tavily's LLM-optimized search API. Returns relevant results with content snippets, scores, and metadata. Use when you need to find web content on any topic without writing code.

Search Skill

Search the web and get relevant results optimized for LLM consumption.

Prerequisites

Tavily API Key Required - Get your key at https://tavily.com

Add to ~/.claude/settings.json:

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

Quick Start

Using the Script

./scripts/search.sh '<json>'

Examples:

# Basic search
./scripts/search.sh '{"query": "python async patterns"}'

# With options
./scripts/search.sh '{"query": "React hooks tutorial", "max_results": 10}'

# Advanced search with filters
./scripts/search.sh '{"query": "AI news", "topic": "news", "time_range": "week", "max_results": 10}'

# Domain-filtered search
./scripts/search.sh '{"query": "machine learning", "include_domains": ["arxiv.org", "github.com"], "search_depth": "advanced"}'

Basic Search

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "latest developments in quantum computing",
    "max_results": 5
  }'

Advanced Search

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "machine learning best practices",
    "max_results": 10,
    "search_depth": "advanced",
    "include_domains": ["arxiv.org", "github.com"],
    "chunks_per_source": 3
  }'

API Reference

Endpoint

POST https://api.tavily.com/search

Headers

Header	Value
`Authorization`	`Bearer <TAVILY_API_KEY>`
`Content-Type`	`application/json`

Request Body

Field	Type	Default	Description
`query`	string	Required	Search query (keep under 400 chars)
`max_results`	integer	5	Maximum results (0-20)
`search_depth`	string	`"basic"`	`ultra-fast`, `fast`, `basic`, `advanced`
`topic`	string	`"general"`	`general`, `news`, `finance`
`chunks_per_source`	integer	3	Chunks per source (advanced/fast only)
`time_range`	string	null	`day`, `week`, `month`, `year`
`include_domains`	array	[]	Domains to include (max 300)
`exclude_domains`	array	[]	Domains to exclude (max 150)
`include_answer`	boolean	false	Include AI-generated answer
`include_raw_content`	boolean	false	Include full page content
`include_images`	boolean	false	Include image results

Response Format

{
  "query": "latest developments in quantum computing",
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com/page",
      "content": "Extracted text snippet...",
      "score": 0.85
    }
  ],
  "response_time": 1.2
}

Search Depth

Depth	Latency	Relevance	Content Type
`ultra-fast`	Lowest	Lower	NLP summary
`fast`	Low	Good	Chunks
`basic`	Medium	High	NLP summary
`advanced`	Higher	Highest	Chunks

When to use each:

ultra-fast: Real-time chat, autocomplete
fast: Need chunks but latency matters
basic: General-purpose, balanced
advanced: Precision matters (default recommendation)

Examples

News Search

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "AI news today",
    "topic": "news",
    "time_range": "day",
    "max_results": 10
  }'

Domain-Filtered Search

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "Python async best practices",
    "include_domains": ["docs.python.org", "realpython.com", "github.com"],
    "search_depth": "advanced"
  }'

Search with Full Content

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "React hooks tutorial",
    "max_results": 3,
    "include_raw_content": true
  }'

Finance Search

curl --request POST \
  --url https://api.tavily.com/search \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "AAPL earnings Q4 2024",
    "topic": "finance",
    "max_results": 10
  }'

Tips

Keep queries under 400 characters - Think search query, not prompt
Break complex queries into sub-queries - Better results than one massive query
Use include_domains to focus on trusted sources
Use time_range for recent information
Filter by score (0-1) to get highest relevance results

Search

安装技能