giggle-official/tavily

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.