brave_web_search
Access current web information using Brave Search to enhance answers with up-to-date facts, news, or technical details when accuracy or freshness is required.
Instructions
Retrieves up-to-date information from the web using Brave Search. You should proactively use this tool whenever you need current information beyond your knowledge cutoff, when answering questions about recent events, when asked about specific facts you're uncertain about, or when providing comprehensive answers. Search automatically when you suspect information might be outdated or when greater detail would improve your response. Use this for news, technical information, current events, product details, or any topic where fresh, accurate data would enhance your answer quality.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of results (1-20, default 10) | |
| offset | No | Pagination offset (max 9, default 0) | |
| query | Yes | Search query (max 400 chars, 50 words) |
Implementation Reference
- src/brave-search.ts:354-376 (handler)Handler function registered with MCP server for executing brave_web_search tool. Validates arguments, calls performWebSearch, and returns formatted text results or error response.
async (args) => { try { if (!isBraveWebSearchArgs(args)) { throw new Error("Invalid arguments for brave_web_search"); } const { query, count = 10 } = args; const results = await performWebSearch(query, count); return { content: [{ type: "text", text: results }], isError: false, }; } catch (error) { return { content: [ { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } }, - src/brave-search.ts:349-353 (schema)Zod-based input schema defining parameters for brave_web_search: required query string and optional count/offset numbers.
{ query: z.string().describe("Search query (max 400 chars, 50 words)"), count: z.number().optional().describe("Number of results (1-20, default 10)"), offset: z.number().optional().describe("Pagination offset (max 9, default 0)"), }, - src/brave-search.ts:346-348 (registration)Registration of the brave_web_search tool with the MCP server, specifying the tool name and description.
server.tool( "brave_web_search", "Keyword-based web search returning a list of search results. Each result includes title, description, and URL. Best for quickly scanning multiple web pages or when you need to see diverse sources. Returns up to 20 search results as a list, not synthesized answers.", - src/brave-search.ts:165-198 (helper)Core helper function that executes the Brave Search web API request, processes the response, and formats search results as text.
async function performWebSearch(query: string, count: number = 10, offset: number = 0) { checkRateLimit(); const url = new URL("https://api.search.brave.com/res/v1/web/search"); url.searchParams.set("q", query); url.searchParams.set("count", Math.min(count, 20).toString()); // API limit url.searchParams.set("offset", offset.toString()); const response = await fetch(url, { headers: { Accept: "application/json", "Accept-Encoding": "gzip", "X-Subscription-Token": BRAVE_API_KEY, }, }); if (!response.ok) { throw new Error( `Brave API error: ${response.status} ${response.statusText}\n${await response.text()}`, ); } const data = (await response.json()) as BraveWeb; // ウェブ検索結果のみを抽出 const results = (data.web?.results || []).map((result) => ({ title: result.title || "", description: result.description || "", url: result.url || "", })); return results .map((r) => `Title: ${r.title}\nDescription: ${r.description}\nURL: ${r.url}`) .join("\n\n"); } - src/brave-search.ts:134-141 (helper)Type guard helper function to validate the input arguments structure for brave_web_search.
function isBraveWebSearchArgs(args: unknown): args is { query: string; count?: number } { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" ); }