brave_web_search
Search the web for general queries, news, articles, and online content using Brave Search API. Gather broad information, find recent events, and access diverse web sources with pagination and filtering options.
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 |
|---|---|---|---|
| query | Yes | Search query (max 400 chars, 50 words) | |
| count | No | Number of results (1-20, default 10) | |
| offset | No | Pagination offset (max 9, default 0) |
Implementation Reference
- src/brave-search/index.ts:180-211 (handler)Core handler function that performs the Brave web search API call, processes the response, and formats results for the brave_web_search tool.
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'); } - src/brave-search/index.ts:324-334 (handler)Entry point handler in the CallToolRequestSchema switch statement that validates arguments and invokes the performWebSearch function 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, }; } - src/brave-search/index.ts:11-38 (schema)Tool definition including name, description, and inputSchema for brave_web_search (used for registration and schema validation).
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"], }, }; - src/brave-search/index.ts:162-169 (schema)Runtime type guard for validating input arguments to 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" ); } - src/brave-search/index.ts:311-313 (registration)Registers the brave_web_search tool (via WEB_SEARCH_TOOL) in the ListToolsRequestHandler.
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [WEB_SEARCH_TOOL, LOCAL_SEARCH_TOOL], }));