analyze_urls
Analyze and summarize content from up to 20 URLs using Google Gemini's URL Context capability, with optional custom instructions and model selection.
Instructions
Analyze and summarize the content of given URLs using Google Gemini URL Context. Provide an optional instruction and model.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes | One URL string or an array of URLs (max 20) | |
| instruction | No | Optional instruction or task description | |
| model | No | Gemini model id (e.g., gemini-2.5-flash) | |
| use_google_search | No | Enable grounding with Google Search (adds google_search tool alongside URL context) |
Implementation Reference
- src/index.ts:26-83 (handler)Core handler function that calls the Gemini API with URL context tools to analyze the provided URLs, constructs the prompt, handles responses, and appends source metadata.async function callGeminiUrlContext(params: AnalyzeUrlsParams): Promise<string> { const apiKey = process.env.GOOGLE_API_KEY; if (!apiKey) { throw new Error("GOOGLE_API_KEY is not set"); } const model = params.model ?? "gemini-2.5-flash"; const endpoint = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`; const promptText = `Guidelines:\n- Strictly use URL Context to retrieve ONLY the provided URLs\n- Do NOT perform web search or include external sources beyond these URLs\n- If a URL cannot be retrieved, note it explicitly\n\nTask:${params.instruction ? `\n${params.instruction}` : `\nProvide a concise, well-structured summary, key facts, and citations`}\n\nAnalyze these URLs:\n${params.urls.join("\n")}`; const tools: any[] = [{ url_context: {} }]; if (params.useGoogleSearch) { tools.push({ google_search: {} }); } const body = { contents: [ { parts: [{ text: promptText }], }, ], tools, } as const; const response = await fetch(endpoint + `?key=${encodeURIComponent(apiKey)}`, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(body), }); if (!response.ok) { const text = await response.text(); throw new Error(`Gemini API error ${response.status}: ${text}`); } const json = (await response.json()) as any; // Try to get the primary text output const candidate = json?.candidates?.[0]; const textOut = candidate?.content?.parts?.map((p: any) => p?.text).filter(Boolean).join("\n"); // Collect URL context metadata for transparency if present const urlMeta: Array<{ retrieved_url?: string; url_retrieval_status?: string }> | undefined = candidate?.url_context_metadata?.url_metadata; const sourcesSection = Array.isArray(urlMeta) && urlMeta.length > 0 ? "\n\nSources (URL Context):\n" + urlMeta .map((m) => `- ${m.retrieved_url ?? "(unknown)"} [${m.url_retrieval_status ?? ""}]`) .join("\n") : ""; if (textOut) { return textOut + sourcesSection; } // Fallback: return raw JSON if text not found return JSON.stringify(json, null, 2); }
- src/index.ts:169-203 (registration)Tool registration definition including name, description, and detailed inputSchema for listTools response.name: "analyze_urls", description: "Analyze and summarize the content of given URLs using Google Gemini URL Context. Provide an optional instruction and model.", inputSchema: { type: "object", properties: { urls: { description: "One URL string or an array of URLs (max 20)", oneOf: [ { type: "string" }, { type: "array", items: { type: "string" }, minItems: 1, maxItems: 20, }, ], }, instruction: { type: "string", description: "Optional instruction or task description", }, model: { type: "string", description: "Gemini model id (e.g., gemini-2.5-flash)", }, use_google_search: { type: "boolean", description: "Enable grounding with Google Search (adds google_search tool alongside URL context)", }, }, required: ["urls"], }, },
- src/index.ts:11-16 (schema)TypeScript type definition for the parameters accepted by the analyze_urls tool handler.type AnalyzeUrlsParams = { urls: string[]; instruction?: string; model?: string; useGoogleSearch?: boolean; };
- src/index.ts:233-262 (handler)Dispatcher handler within the CallToolRequestSchema that validates inputs, normalizes the urls array, and invokes the core analyze_urls handler.if (name === "analyze_urls") { const { urls: rawUrls, instruction, model, use_google_search, } = (args ?? {}) as { urls?: string | string[]; instruction?: string; model?: string; use_google_search?: boolean; }; const urls = Array.isArray(rawUrls) ? rawUrls : typeof rawUrls === "string" ? [rawUrls] : []; if (urls.length === 0) { throw new Error("'urls' must be provided as a string or a non-empty array"); } if (urls.length > 20) { throw new Error("Maximum of 20 URLs supported"); } const text = await callGeminiUrlContext({ urls, instruction, model, useGoogleSearch: Boolean(use_google_search), }); return { content: [{ type: "text", text }] };