google_web_search
Perform web searches using the Google Custom Search API to gather diverse information, news, articles, or online content. Supports pagination and filtering by site or type for targeted results.
Instructions
Performs a web search using the Google Custom 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 and filtering by site or type. Maximum 10 results per request, with start index for pagination.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of results (1-10, default 5) | |
| query | Yes | Search query | |
| site | No | Optional: Limit search to specific site (e.g., 'site:example.com') | |
| start | No | Pagination start index (default 1) |
Implementation Reference
- src/index.ts:204-244 (handler)Core handler function that performs the Google Custom Search web search, handles parameters like site restriction, rate limiting, API call, error handling, and formats results into a readable text response.async function performWebSearch(query: string, count: number = 5, start: number = 1, site: string = "") { checkRateLimit(); let searchQuery = query; // If site is provided, append it to the query if (site && !query.includes("site:")) { searchQuery = `${query} site:${site}`; } const url = new URL('https://www.googleapis.com/customsearch/v1'); url.searchParams.set('key', GOOGLE_API_KEY); url.searchParams.set('cx', GOOGLE_CSE_ID); url.searchParams.set('q', searchQuery); url.searchParams.set('num', Math.min(count, 10).toString()); // API limit is 10 url.searchParams.set('start', start.toString()); const response = await fetch(url, { headers: { 'Accept': 'application/json', } }); if (!response.ok) { throw new Error(`Google API error: ${response.status} ${response.statusText}\n${await response.text()}`); } const data = await response.json() as GoogleSearchResult; if (data.error) { throw new Error(`Google API error: ${data.error.code} ${data.error.message}`); } if (!data.items || data.items.length === 0) { return "No results found for your query."; } // Format the results return data.items.map((item, index) => `[${index + 1}] Title: ${item.title}\nDescription: ${item.snippet}\nURL: ${item.link}` ).join('\n\n'); }
- src/index.ts:186-193 (schema)Type guard function for validating input arguments to the google_web_search tool.function isGoogleWebSearchArgs(args: unknown): args is { query: string; count?: number; start?: number; site?: string } { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" ); }
- src/index.ts:11-43 (registration)Tool registration object defining the name, description, and input schema for google_web_search, used in listTools response.const WEB_SEARCH_TOOL: Tool = { name: "google_web_search", description: "Performs a web search using the Google Custom 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 and filtering by site or type. " + "Maximum 10 results per request, with start index for pagination. ", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query" }, count: { type: "number", description: "Number of results (1-10, default 5)", default: 5 }, start: { type: "number", description: "Pagination start index (default 1)", default: 1 }, site: { type: "string", description: "Optional: Limit search to specific site (e.g., 'site:example.com')", default: "" }, }, required: ["query"], }, };
- src/index.ts:297-307 (handler)Dispatch handler case within CallToolRequestSchema that validates arguments and invokes the performWebSearch function for google_web_search.case "google_web_search": { if (!isGoogleWebSearchArgs(args)) { throw new Error("Invalid arguments for google_web_search"); } const { query, count = 5, start = 1, site = "" } = args; const results = await performWebSearch(query, count, start, site); return { content: [{ type: "text", text: results }], isError: false, }; }
- src/index.ts:285-286 (registration)Server request handler for ListToolsRequestSchema that registers and exposes the google_web_search tool.tools: [WEB_SEARCH_TOOL, IMAGE_SEARCH_TOOL], }));