brave_web_search
Perform web searches using the Brave Search API to gather diverse online content, news, or articles. Supports pagination, content filtering, and freshness controls for precise results.
Instructions
Performs a web search using the Brave Search API, ideal for general queries, news, articles, and online content. Use this for broad information gathering, recent events, or when you need diverse web sources. Supports pagination, content filtering, and freshness controls. Maximum 20 results per request, with offset for pagination.
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
- index.ts:180-211 (handler)Core implementation of the brave_web_search tool: makes API call to Brave Search, handles response, extracts and formats web search results.
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; // Extract just web results 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'); } - index.ts:11-38 (schema)Tool schema definition for brave_web_search including name, description, and input schema.
const WEB_SEARCH_TOOL: Tool = { name: "brave_web_search", description: "Performs a web search using the Brave Search API, ideal for general queries, news, articles, and online content. " + "Use this for broad information gathering, recent events, or when you need diverse web sources. " + "Supports pagination, content filtering, and freshness controls. " + "Maximum 20 results per request, with offset for pagination. ", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query (max 400 chars, 50 words)" }, count: { type: "number", description: "Number of results (1-20, default 10)", default: 10 }, offset: { type: "number", description: "Pagination offset (max 9, default 0)", default: 0 }, }, required: ["query"], }, }; - index.ts:311-313 (registration)Registers the brave_web_search tool by including WEB_SEARCH_TOOL in the tools list for ListToolsRequest.
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [WEB_SEARCH_TOOL, LOCAL_SEARCH_TOOL], })); - index.ts:324-334 (handler)Dispatch handler in CallToolRequestSchema that validates arguments and invokes performWebSearch for brave_web_search.
case "brave_web_search": { 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, }; } - index.ts:162-169 (schema)Type guard for validating input arguments to brave_web_search tool.
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" ); }