tavily_search
Perform web searches optimized for AI systems to gather broad information, track recent events, and access diverse sources with customizable filters.
Instructions
Performs a web search using the Tavily Search API, optimized for LLMs. Use this for broad information gathering, recent events, or when you need diverse web sources. Supports search depth, topic selection, time range filtering, and domain inclusion/exclusion.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query. | |
| search_depth | No | The depth of the search. It can be "basic" or "advanced". | basic |
| topic | No | The category of the search. Currently: only "general" and "news" are supported. | general |
| days | No | The number of days back from the current date to include in the search results (for news topic). | |
| time_range | No | The time range back from the current date to include in the search results. Accepted values include "day","week","month","year" or "d","w","m","y". | |
| max_results | No | The maximum number of search results to return. | |
| include_images | No | Include a list of query-related images in the response. | |
| include_image_descriptions | No | When include_images is set to True, this option adds descriptive text for each image. | |
| include_answer | No | Include a short answer to original query, generated by an LLM based on Tavily's search results. | |
| include_raw_content | No | Include the cleaned and parsed HTML content of each search result. | |
| include_domains | No | A list of domains to specifically include in the search results. | |
| exclude_domains | No | A list of domains to specifically exclude from the search results. |
Implementation Reference
- src/tavily.ts:134-154 (handler)The core handler function that executes the tavily_search tool logic by making a POST request to the Tavily API with the provided arguments and returning the formatted JSON response.async function performTavilySearch(args: TavilySearchArgs) { const url = "https://api.tavily.com/search"; const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TAVILY_API_KEY}`, }, body: JSON.stringify({ ...args }), }); if (!response.ok) { throw new Error(`Tavily API error: ${response.status} ${response.statusText}\n${await response.text()}`); } const data = await response.json(); return JSON.stringify(data, null, 2); }
- src/tavily.ts:8-87 (schema)Tool definition including name, description, and detailed input JSON schema for tavily_search.const TAVILY_SEARCH_TOOL: Tool = { name: "tavily_search", description: "Performs a web search using the Tavily Search API, optimized for LLMs. " + "Use this for broad information gathering, recent events, or when you need diverse web sources. " + "Supports search depth, topic selection, time range filtering, and domain inclusion/exclusion.", inputSchema: { type: "object", properties: { query: { type: "string", description: "The search query.", }, search_depth: { type: "string", description: 'The depth of the search. It can be "basic" or "advanced".', enum: ["basic", "advanced"], default: "basic", }, topic: { type: "string", description: 'The category of the search. Currently: only "general" and "news" are supported.', enum: ["general", "news"], default: "general", }, days: { type: "number", description: "The number of days back from the current date to include in the search results (for news topic).", default: 3 }, time_range: { type: "string", description: 'The time range back from the current date to include in the search results. Accepted values include "day","week","month","year" or "d","w","m","y".', enum: ["day", "week", "month", "year", "d", "w", "m", "y"], }, max_results: { type: "number", description: "The maximum number of search results to return.", default: 5, }, include_images: { type: "boolean", description: "Include a list of query-related images in the response.", default: false, }, include_image_descriptions: { type: "boolean", description: "When include_images is set to True, this option adds descriptive text for each image.", default: false, }, include_answer: { type: "boolean", description: "Include a short answer to original query, generated by an LLM based on Tavily's search results.", default: false, }, include_raw_content: { type: "boolean", description: "Include the cleaned and parsed HTML content of each search result.", default: false, }, include_domains: { type: "array", items: { type: "string", }, description: "A list of domains to specifically include in the search results.", default: [], }, exclude_domains: { type: "array", items: { type: "string", }, description: "A list of domains to specifically exclude from the search results.", default: [], }, }, required: ["query"], }, };
- src/tavily.ts:157-159 (registration)Registers the tavily_search tool in the MCP server's listTools handler.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [TAVILY_SEARCH_TOOL], }));
- src/tavily.ts:170-179 (handler)Dispatch handler in the callTool request that validates arguments and invokes the performTavilySearch function for tavily_search.case "tavily_search": { if (!isTavilySearchArgs(args)) { throw new Error("Invalid arguments for tavily_search"); } const results = await performTavilySearch(args); return { content: [{type: "text", text: results}], isError: false, }; }
- src/tavily.ts:125-132 (helper)Type guard helper function to validate arguments for tavily_search tool.function isTavilySearchArgs(args: unknown): args is TavilySearchArgs { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" ); }