| name | web-search |
| description | Search the live web with LLM-optimized results via the Tavily MCP. Use when the user wants to search for, find, look up, or discover sources on a topic; says "search for", "find me", "what's the latest on", "find articles about", "Google this for me"; or needs current information beyond training-data cutoff. Returns ranked results with snippets, scores, and metadata. Supports domain filtering, time ranges, and depth tuning. For deep multi-source synthesis, use deep-research instead. For pulling content from a known URL, use extract-page. |
Web Search
Call tavily_search to find pages on a topic. Return ranked results with
titles, URLs, content snippets, and relevance scores.
When to use this skill
- The user wants pages on a topic but doesn't have URLs yet.
- The user wants recent news ("what's happening with…", "latest on…").
- You need to find the right source before extracting content.
- Quick fact-finding where a snippet is enough.
For deeper, cited reports, use deep-research. For pulling content from a
URL you already have, use extract-page.
How to call the tool
Pass these arguments to tavily_search:
| Argument | When to set it |
|---|
query | Required. Keep under 400 chars. Phrase as a search query, not a chat prompt. |
search_depth | basic (default), advanced (more thorough), fast, ultra-fast. Default to basic; bump to advanced only when precision matters. |
topic | general (default), news, finance. Set to news for current events. |
time_range | day, week, month, year. Set when the user wants recent results. |
start_date / end_date | YYYY-MM-DD for a specific window. |
max_results | 0–20, default 5. Use 10+ for survey-style searches. |
include_domains | Comma list of trusted domains to scope the search. |
exclude_domains | Comma list of domains to filter out. |
country | Boost results from a specific country. |
include_answer | basic or advanced — get an AI summary alongside results. |
include_raw_content | markdown or text — embed full page content (saves a separate extract call). |
Most searches need only query. Add filters when the user's intent is
specific.
Prompting patterns
These work well:
- Be specific:
"Anthropic Claude 3.5 pricing 2025" beats "Claude pricing".
- Split complex queries: two sub-queries usually beat one compound one.
- Recency:
time_range: "week" for "latest", "day" for breaking news.
- Trusted sources:
include_domains: "sec.gov,reuters.com" for filings or wire stories.
- Drop boilerplate: don't include "search for" or "find me" in the
query — that's the user talking to you, not to the search engine.
Returning results
Default presentation back to the user:
- Short summary of what you found (1–2 sentences).
- A bullet list of the top 3–5 results, each with title and URL.
- If
include_answer was set, lead with the AI answer and offer to dig deeper.
- End with a "Sources:" section.
If the user wants the content of a result rather than the snippet, hand
off to extract-page.
Failure modes
- Empty results: relax filters (drop domain include lists, widen time
range), try a less-specific query, or escalate to
deep-research.
- Too many irrelevant results: tighten — add
include_domains, narrow
time_range, or rephrase the query with more specific nouns.
- Slow response: switch
search_depth to fast or ultra-fast.
For the full parameter reference and edge cases, see
references/search-parameters.md.
