# tavily

## Summary

Tavily Tools provides three complementary capabilities for web search and content extraction: `web_search`, `tavily_search`, and `tavily_extract`. Use `web_search` for fast, straightforward queries (specify query and result count). Use `tavily_search` for in-depth research with fine-grained controls — choose `search_depth` (basic or advanced), `topic` (general, news, finance), `max_results` (1–20), `include_answer` (AI-generated summary), `time_range` (day, week, month, year), and `include_domains/exclude_domains` to restrict sources. `tavily_extract` pulls full content from specified URLs for scraping, summarization, or downstream analysis. Typical use cases include quick lookups, investigative research with domain/time filters, real-time news/finance monitoring, and extracting source material for summarization or NLP pipelines. Core advantages are configurable relevance depth, domain/time filtering, optional AI summaries, and an extraction endpoint for reliable content ingestion.

## Tavily Tools

### When to use which tool

| Need | Tool | When |
| --- | --- | --- |
| Quick web search | `web_search` | Basic queries, no special options needed |
| Search with advanced options | `tavily_search` | Need depth, topic, domain filters, time ranges, or AI answers |
| Extract content from URLs | `tavily_extract` | Have specific URLs, need their content |

### web_search

Tavily powers this automatically when selected as the search provider. Use for straightforward queries where you don't need Tavily-specific options.

| Parameter | Description |
| --- | --- |
| `query` | Search query string |
| `count` | Number of results (1-20) |

### tavily_search

Use when you need fine-grained control over search behavior.

| Parameter | Description |
| --- | --- |
| `query` | Search query string (keep under 400 characters) |
| `search_depth` | `basic` (default, balanced) or `advanced` (highest relevance, slower) |
| `topic` | `general` (default), `news` (real-time updates), or `finance` |
| `max_results` | Number of results, 1-20 (default: 5) |
| `include_answer` | Include an AI-generated answer summary (default: false) |
| `time_range` | Filter by recency: `day`, `week`, `month`, or `year` |
| `include_domains` | Array of domains to restrict results to |
| `exclude_domains` | Array of domains to exclude from results |

### Search depth

| Depth | Speed | Relevance | Best for |
| --- | --- | --- | --- |
| `basic` | Faster | High | General-purpose queries (default) |
| `advanced` | Slower | Highest | Precision, specific facts, detailed research |

### Tips

- **Keep queries under 400 characters** — think search query, not prompt.
- **Break complex queries into sub-queries** for better results.
- **Use `include_domains`** to focus on trusted sources.
- **Use `time_range`** for recent information (news, current events).
- **Use `include_answer`** when you need a quick synthesized answer.

### tavily_extract

Use when you have specific URLs and need their content. Handles JavaScript-rendered pages and returns clean markdown. Supports query-focused chunking for targeted extraction.

| Parameter | Description |
| --- | --- |
| `urls` | Array of URLs to extract (1-20 per request) |
| `query` | Rerank extracted chunks by relevance to this query |
| `extract_depth` | `basic` (default, fast) or `advanced` (for JS-heavy pages, tables) |
| `chunks_per_source` | Chunks per URL, 1-5 (requires `query`) |
| `include_images` | Include image URLs in results (default: false) |

### Extract depth

| Depth | When to use |
| --- | --- |
| `basic` | Simple pages — try this first |
| `advanced` | JS-rendered SPAs, dynamic content, tables, embedded content |

### Tips

- **Max 20 URLs per request** — batch larger lists into multiple calls.
- **Use `query` + `chunks_per_source`** to get only relevant content instead of full pages.
- **Try `basic` first**, fall back to `advanced` if content is missing or incomplete.
- If `tavily_search` results already contain the snippets you need, skip the extract step.

### Choosing the right workflow

Follow this escalation pattern — start simple, escalate only when needed:

1. **`web_search`** — Quick lookup, no special options needed.
2. **`tavily_search`** — Need depth control, topic filtering, domain filters, time ranges, or AI answers.
3. **`tavily_extract`** — Have specific URLs, need their full content or targeted chunks.

Combine search + extract when you need to find pages first, then get their full content.