mcp-scraper 0.2.19 → 0.2.20

package/dist/bin/mcp-scraper-combined-stdio-server.cjs

@@ -23,6 +23,27 @@ function harvestTimeoutBudget(maxQuestions, serpOnly = false) {
 }
 
 // src/mcp/http-mcp-tool-executor.ts
+function youtubeVideoIdFromUrl(url) {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname.replace(/^www\./, "").replace(/^m\./, "");
+    if (host === "youtu.be") {
+      const id = parsed.pathname.split("/").filter(Boolean)[0];
+      return id || null;
+    }
+    if (host === "youtube.com" || host === "music.youtube.com") {
+      const watchId = parsed.searchParams.get("v");
+      if (watchId) return watchId;
+      const parts = parsed.pathname.split("/").filter(Boolean);
+      const markerIndex = parts.findIndex((part) => ["shorts", "embed", "live"].includes(part));
+      if (markerIndex >= 0 && parts[markerIndex + 1]) return parts[markerIndex + 1];
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
 var HttpMcpToolExecutor = class {
   baseUrl;
   apiKey;
@@ -148,7 +169,21 @@ var HttpMcpToolExecutor = class {
     return this.call("/youtube/harvest", input);
   }
   youtubeTranscribe(input) {
-    return this.call("/youtube/transcribe", input);
+    const videoId = input.videoId?.trim() || youtubeVideoIdFromUrl(input.url);
+    if (!videoId) {
+      return Promise.resolve({
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            error_code: "youtube_video_id_required",
+            error: "Pass videoId from youtube_harvest or a YouTube url that contains a video id.",
+            retryable: false
+          })
+        }],
+        isError: true
+      });
+    }
+    return this.call("/youtube/transcribe", { videoId });
   }
   facebookPageIntel(input) {
     return this.call("/facebook/page-intel", input);
@@ -185,6 +220,10 @@ var HttpMcpToolExecutor = class {
       webhookUrl: input.webhookUrl
     }, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 9e5);
   }
+  workflowStep(input) {
+    const timeoutMs = this.httpTimeoutOverrideMs ?? Number(process.env.MCP_SCRAPER_WORKFLOW_TIMEOUT_MS ?? 9e5);
+    return this.call(`/workflows/runs/${encodeURIComponent(input.runId)}/step`, {}, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 9e5);
+  }
   workflowStatus(input) {
     return this.getJson(`/workflows/runs/${encodeURIComponent(input.runId)}`);
   }
@@ -212,10 +251,22 @@ var import_node_os2 = require("os");
 var import_node_path2 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.19";
+var PACKAGE_VERSION = "0.2.20";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
+var NullableString = import_zod.z.string().nullable();
+var BrowserRawObject = import_zod.z.record(import_zod.z.unknown());
+var BrowserElementOutput = import_zod.z.record(import_zod.z.unknown());
+var BrowserBaseOutput = {
+  ok: import_zod.z.boolean().describe("Whether the browser-agent action succeeded."),
+  tool: import_zod.z.string().describe("Browser Agent MCP tool that produced this response."),
+  session_id: NullableString.describe("Browser session id when the response is scoped to a session.")
+};
+var BrowserReplayBaseOutput = {
+  ...BrowserBaseOutput,
+  replay_id: NullableString.describe("Replay id when the response is scoped to a replay.")
+};
 var BrowserOpenInputSchema = {
   label: import_zod.z.string().optional().describe("Optional human label for this session, shown in the watch console."),
   url: import_zod.z.string().url().optional().describe("Optional URL to navigate to immediately after opening."),
@@ -223,7 +274,7 @@ var BrowserOpenInputSchema = {
   timeout_seconds: import_zod.z.number().int().min(60).max(259200).optional().describe("How long the session may live before auto-termination. Defaults to 600. The browser idles into a zero-cost standby between actions, so a longer timeout is cheap.")
 };
 var BrowserSessionInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open.")
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself.")
 };
 var BrowserLocateTargetSchema = import_zod.z.object({
   name: import_zod.z.string().optional().describe("Optional label for this target, echoed in the result."),
@@ -235,43 +286,43 @@ var BrowserLocateTargetSchema = import_zod.z.object({
   message: "target requires selector or text"
 });
 var BrowserLocateInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   targets: import_zod.z.array(BrowserLocateTargetSchema).min(1).max(20).describe("DOM targets to locate in the current viewport. Use selectors for exact elements, or text for visible text ranges.")
 };
 var BrowserGotoInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   url: import_zod.z.string().url().describe("URL to navigate the browser to.")
 };
 var BrowserClickInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  x: import_zod.z.number().describe("X coordinate to click, in screenshot pixels. Use the x of an element from the latest screenshot."),
-  y: import_zod.z.number().describe("Y coordinate to click, in screenshot pixels."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  x: import_zod.z.number().describe("X coordinate to click, in screenshot pixels. Use only coordinates from the latest browser_screenshot, browser_read, or browser_locate result; do not guess."),
+  y: import_zod.z.number().describe("Y coordinate to click, in screenshot pixels. Use only coordinates from the latest browser_screenshot, browser_read, or browser_locate result; do not guess."),
   button: import_zod.z.enum(["left", "right", "middle"]).default("left").describe("Mouse button."),
   num_clicks: import_zod.z.number().int().min(1).max(3).optional().describe("Number of clicks, e.g. 2 for double-click.")
 };
 var BrowserTypeInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   text: import_zod.z.string().describe("Text to type at the current focus. Click a field first to focus it."),
   delay: import_zod.z.number().int().min(0).max(500).optional().describe("Optional per-keystroke delay in ms for human-like typing.")
 };
 var BrowserScrollInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   delta_y: import_zod.z.number().default(5).describe("Vertical scroll in wheel units. Positive scrolls down, negative up."),
   delta_x: import_zod.z.number().default(0).describe("Horizontal scroll in wheel units."),
   x: import_zod.z.number().optional().describe("X position to scroll at. Defaults to screen center."),
   y: import_zod.z.number().optional().describe("Y position to scroll at. Defaults to screen center.")
 };
 var BrowserPressInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   keys: import_zod.z.array(import_zod.z.string()).min(1).describe('Keys or combinations to press, e.g. ["Return"], ["Ctrl+a"], ["Ctrl+Shift+Tab"].')
 };
 var BrowserReplayStopInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start.")
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself.")
 };
 var BrowserReplayDownloadInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself."),
   filename: import_zod.z.string().optional().describe("Optional local MP4 filename. Defaults to a timestamped replay filename.")
 };
 var BrowserReplayAnnotationSchema = import_zod.z.object({
@@ -293,7 +344,7 @@ var BrowserReplayAnnotationSchema = import_zod.z.object({
   thickness: import_zod.z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5.")
 });
 var BrowserReplayMarkInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open. A replay must already be recording."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself. A replay must already be recording."),
   target: BrowserLocateTargetSchema.describe("The exact DOM element or text range to mark in the current viewport."),
   type: import_zod.z.enum(["box", "circle", "underline", "arrow"]).default("box").describe("Annotation style to generate. Labels are included on the returned annotation when label is provided."),
   label: import_zod.z.string().max(120).optional().describe("Optional callout text to render near the target."),
@@ -304,8 +355,8 @@ var BrowserReplayMarkInputSchema = {
   duration_seconds: import_zod.z.number().min(0.5).max(30).default(4).describe("How long the generated annotation should remain visible.")
 };
 var BrowserReplayAnnotateInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself."),
   annotations: import_zod.z.array(BrowserReplayAnnotationSchema).min(1).max(50).describe("Timed overlay annotations to render on the replay. Prefer annotations returned by browser_replay_mark; otherwise use exact DOM bounds from browser_locate/browser_screenshot/browser_read."),
   filename: import_zod.z.string().optional().describe("Optional output MP4 filename. Defaults to a timestamped annotated replay filename."),
   source_width: import_zod.z.number().positive().optional().describe("Width of the screenshot coordinate space used for annotations. Defaults to the replay video width."),
@@ -316,6 +367,113 @@ var BrowserReplayAnnotateInputSchema = {
 var BrowserListInputSchema = {
   include_closed: import_zod.z.boolean().default(false).describe("Include closed sessions in the list.")
 };
+var BrowserOpenOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_open"),
+  session_id: import_zod.z.string().describe("Session id returned by browser_open. Use only this exact value in later browser_* calls; do not construct one yourself."),
+  watch_url: import_zod.z.string().describe("Human watch/takeover URL for this browser session."),
+  live_view_url: NullableString.describe("Raw live-view URL from the browser service when available."),
+  url: NullableString.describe("Initial URL requested by the caller, when provided."),
+  hint: import_zod.z.string(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserScreenshotOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_screenshot"),
+  url: NullableString,
+  title: NullableString,
+  text: import_zod.z.string(),
+  elements: import_zod.z.array(BrowserElementOutput),
+  screenshot: import_zod.z.object({
+    mime_type: import_zod.z.string(),
+    inline: import_zod.z.boolean()
+  }).nullable()
+};
+var BrowserReadOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_read"),
+  url: NullableString,
+  title: NullableString,
+  text: import_zod.z.string(),
+  elements: import_zod.z.array(BrowserElementOutput),
+  raw: BrowserRawObject.optional()
+};
+var BrowserLocateOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_locate"),
+  url: NullableString,
+  title: NullableString,
+  viewport: BrowserRawObject.nullable(),
+  replay: BrowserRawObject.nullable(),
+  targets: import_zod.z.array(BrowserRawObject),
+  raw: BrowserRawObject.optional()
+};
+var BrowserActionOutputSchema = {
+  ...BrowserBaseOutput,
+  result: BrowserRawObject.describe("Provider action result. Check ok and follow with browser_screenshot/browser_read when page state matters."),
+  nextRecommendedTool: import_zod.z.string().nullable()
+};
+var BrowserReplayStartOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_start"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserReplayStopOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_stop"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserListReplaysOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_list_replays"),
+  replays: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0)
+};
+var BrowserReplayDownloadOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_download"),
+  file_path: NullableString,
+  bytes: import_zod.z.number().int().min(0).nullable(),
+  mime_type: NullableString,
+  download_url: NullableString
+};
+var BrowserReplayMarkOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_mark"),
+  annotation: BrowserRawObject,
+  source_width: import_zod.z.number().nullable(),
+  source_height: import_zod.z.number().nullable(),
+  target: BrowserRawObject.nullable(),
+  hint: import_zod.z.string()
+};
+var BrowserReplayAnnotateOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_annotate"),
+  source_file_path: NullableString,
+  annotated_file_path: NullableString,
+  bytes: import_zod.z.number().int().min(0).nullable(),
+  width: import_zod.z.number().int().min(0).nullable(),
+  height: import_zod.z.number().int().min(0).nullable(),
+  annotation_count: import_zod.z.number().int().min(0).nullable(),
+  mime_type: NullableString
+};
+var BrowserCloseOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_close"),
+  closed: import_zod.z.boolean(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserListSessionsOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_list_sessions"),
+  session_id: import_zod.z.null(),
+  sessions: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0)
+};
 
 // src/mcp/replay-annotator.ts
 var import_node_child_process = require("child_process");
@@ -578,8 +736,40 @@ async function annotateReplayVideo(inputFilePath, outputFilePath, options) {
 }
 
 // src/mcp/browser-agent-mcp-server.ts
-function textResult(value, isError = false) {
-  return { content: [{ type: "text", text: JSON.stringify(value) }], isError };
+function structuredResult(value, isError = false) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    structuredContent: value,
+    isError
+  };
+}
+function errorMessage(value) {
+  if (value && typeof value === "object") {
+    const data = value;
+    if (typeof data.error === "string") return data.error;
+    if (typeof data.message === "string") return data.message;
+  }
+  return typeof value === "string" ? value : "Browser Agent request failed";
+}
+function errorResult(tool, value, sessionId = null, replayId = null) {
+  return structuredResult({
+    ok: false,
+    tool,
+    session_id: sessionId,
+    ...replayId !== null ? { replay_id: replayId } : {},
+    error: errorMessage(value),
+    raw: value && typeof value === "object" ? value : { value }
+  }, true);
+}
+function actionResult(tool, sessionId, ok, data, nextRecommendedTool = "browser_screenshot") {
+  if (!ok) return errorResult(tool, data, sessionId);
+  return structuredResult({
+    ok: true,
+    tool,
+    session_id: sessionId,
+    result: data && typeof data === "object" ? data : { value: data },
+    nextRecommendedTool
+  });
 }
 function outputBaseDir() {
   return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), "Downloads", "mcp-scraper");
@@ -679,6 +869,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Open Browser Session",
       description: "Open a fresh cloud browser you can drive. Returns a session_id used by all other browser_* tools, and a watch_url where a human can watch live or take over. Anti-bot stealth and automatic CAPTCHA/Cloudflare solving are on by default: if a Cloudflare or CAPTCHA challenge appears, do NOT click it \u2014 wait a few seconds and call browser_screenshot again; it is solved automatically. Billing: metered per second of active browser work at ~4 credits per minute; idle and standby time are free. Call browser_close when done to stop the meter. After opening, call browser_screenshot to see the page.",
       inputSchema: BrowserOpenInputSchema,
+      outputSchema: BrowserOpenOutputSchema,
       annotations: annotations("Open Browser Session")
     },
     async (input) => {
@@ -687,16 +878,20 @@ function registerBrowserAgentMcpTools(server2, opts) {
         profile: input.profile,
         timeout_seconds: input.timeout_seconds
       });
-      if (!open.ok) return textResult(open.data, true);
+      if (!open.ok) return errorResult("browser_open", open.data);
       const session = open.data;
       if (input.url) {
         await req("POST", `/agent/sessions/${session.session_id}/goto`, { url: input.url });
       }
-      return textResult({
+      return structuredResult({
+        ok: true,
+        tool: "browser_open",
         session_id: session.session_id,
         watch_url: `${consoleBase}/console/${session.session_id}`,
         live_view_url: session.live_view_url ?? null,
-        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot."
+        url: input.url ?? null,
+        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot.",
+        raw: session
       });
     }
   );
@@ -706,19 +901,30 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "See Page (Screenshot + Elements)",
       description: "Capture what the browser currently shows. Returns a screenshot image PLUS a text snapshot listing interactive elements with their center x,y coordinates, the page url and title, and visible text. This is your primary way to perceive the page. Click elements by their listed x,y. If a Cloudflare/CAPTCHA challenge is visible, wait and screenshot again rather than clicking it.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserScreenshotOutputSchema,
       annotations: annotations("See Page", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/screenshot`);
-      if (!res.ok) return textResult(res.data, true);
+      if (!res.ok) return errorResult("browser_screenshot", res.data, input.session_id);
       const { image_base64, mime_type, url, title, elements, text } = res.data;
       const content = [];
       if (image_base64) content.push({ type: "image", data: image_base64, mimeType: mime_type ?? "image/png" });
+      const structured = {
+        ok: true,
+        tool: "browser_screenshot",
+        session_id: input.session_id,
+        url: url ?? null,
+        title: title ?? null,
+        text: typeof text === "string" ? text : "",
+        elements: Array.isArray(elements) ? elements : [],
+        screenshot: image_base64 ? { mime_type: mime_type ?? "image/png", inline: true } : null
+      };
       content.push({
         type: "text",
-        text: JSON.stringify({ url, title, elements, text })
+        text: JSON.stringify(structured)
       });
-      return { content };
+      return { content, structuredContent: structured };
     }
   );
   server2.registerTool(
@@ -727,11 +933,22 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Read Page Text + Elements",
       description: "Return the page url, title, visible text, and the list of interactive elements (with x,y) without an image. Cheaper than browser_screenshot when you only need to read content or find a target element to click.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserReadOutputSchema,
       annotations: annotations("Read Page", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/read`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_read", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_read",
+        session_id: input.session_id,
+        url: res.data?.url ?? null,
+        title: res.data?.title ?? null,
+        text: typeof res.data?.text === "string" ? res.data.text : "",
+        elements: Array.isArray(res.data?.elements) ? res.data.elements : [],
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
@@ -740,32 +957,46 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Locate DOM Targets",
       description: "Locate exact visible DOM elements or text ranges in the current browser viewport and return left/top/width/height bounds in screenshot pixels. Use this before drawing annotations or when a callout must literally circle, box, underline, or point to a real element. Prefer CSS selectors for exact UI elements; use text when selector is unknown. When a replay is actively recording, the result includes replay_elapsed_seconds for timing.",
       inputSchema: BrowserLocateInputSchema,
+      outputSchema: BrowserLocateOutputSchema,
       annotations: annotations("Locate DOM Targets", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: input.targets });
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_locate", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_locate",
+        session_id: input.session_id,
+        url: res.data?.url ?? null,
+        title: res.data?.title ?? null,
+        viewport: res.data?.viewport ?? null,
+        replay: res.data?.replay ?? null,
+        targets: Array.isArray(res.data?.targets) ? res.data.targets : [],
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
     "browser_goto",
     {
       title: "Navigate To URL",
-      description: "Navigate the browser to a URL. Follow with browser_screenshot to see the result.",
+      description: "Navigate an existing browser session to a URL when the user asks you to go to another page or continue browsing in the same session. Use browser_open first if no session exists. Follow with browser_screenshot to see redirects, login walls, CAPTCHA/Cloudflare state, or the loaded page.",
       inputSchema: BrowserGotoInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Navigate To URL")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/goto`, { url: input.url });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_goto", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_click",
     {
       title: "Click",
-      description: "Click at x,y (screenshot pixel coordinates). Use the x,y of a target element from the latest browser_screenshot or browser_read.",
+      description: "Click a visible page target using screenshot pixel coordinates. Use this when the user asks you to press a button, open a menu, choose a result, or activate a visible UI element. Use x/y only from the latest browser_screenshot, browser_read, or browser_locate result; do not guess coordinates. Follow with browser_screenshot when the click may change the page.",
       inputSchema: BrowserClickInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Click")
     },
     async (input) => {
@@ -775,28 +1006,30 @@ function registerBrowserAgentMcpTools(server2, opts) {
         button: input.button,
         num_clicks: input.num_clicks
       });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_click", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_type",
     {
       title: "Type Text",
-      description: 'Type text at the current focus. Click an input field first to focus it. Use browser_press with ["Return"] to submit.',
+      description: 'Type text into the currently focused browser field. Use this when the user asks you to fill a search box, form field, login field, or editable text area. Click or Tab to the field first if focus is uncertain. Use browser_press with ["Return"] to submit, and browser_screenshot afterward when page state matters.',
       inputSchema: BrowserTypeInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Type Text")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/type`, { text: input.text, delay: input.delay });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_type", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_scroll",
     {
       title: "Scroll",
-      description: "Scroll the page. Positive delta_y scrolls down. Follow with browser_screenshot to see newly revealed content.",
+      description: "Scroll the page to reveal more content before reading, clicking, or locating elements. Positive delta_y scrolls down; negative delta_y scrolls up. Follow with browser_screenshot or browser_read to inspect newly revealed content.",
       inputSchema: BrowserScrollInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Scroll")
     },
     async (input) => {
@@ -806,20 +1039,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
         x: input.x,
         y: input.y
       });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_scroll", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_press",
     {
       title: "Press Keys",
-      description: 'Press keys or combinations, e.g. ["Return"] to submit, ["Ctrl+a"] to select all, ["Ctrl+Shift+Tab"] to switch tabs.',
+      description: 'Press keyboard keys or combinations in the active browser session. Use this for submit, Escape, Tab navigation, select-all, or keyboard shortcuts. Examples: ["Return"], ["Escape"], ["Tab"], ["Ctrl+a"], ["Ctrl+Shift+Tab"]. Use browser_type for text entry and browser_screenshot after keypresses that may change the page.',
       inputSchema: BrowserPressInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Press Keys")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/press`, { keys: input.keys });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_press", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
@@ -828,11 +1062,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Start Recording",
       description: "Start recording an MP4 replay of the session. Returns replay_id, view_url when available, and a download_url. Use to capture a task for later review; stop with browser_replay_stop.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserReplayStartOutputSchema,
       annotations: annotations("Start Recording")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/replay/start`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_replay_start", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_start",
+        session_id: input.session_id,
+        replay_id: res.data?.replay_id ?? res.data?.replayId ?? null,
+        view_url: res.data?.view_url ?? res.data?.viewUrl ?? null,
+        download_url: res.data?.download_url ?? res.data?.downloadUrl ?? null,
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
@@ -841,11 +1085,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Stop Recording",
       description: "Stop a replay recording and expose the final view_url and download_url. Use browser_replay_download to save the MP4 locally.",
       inputSchema: BrowserReplayStopInputSchema,
+      outputSchema: BrowserReplayStopOutputSchema,
       annotations: annotations("Stop Recording")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/replay/stop`, { replay_id: input.replay_id });
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_replay_stop", res.data, input.session_id, input.replay_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_stop",
+        session_id: input.session_id,
+        replay_id: res.data?.replay_id ?? res.data?.replayId ?? input.replay_id,
+        view_url: res.data?.view_url ?? res.data?.viewUrl ?? null,
+        download_url: res.data?.download_url ?? res.data?.downloadUrl ?? null,
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
@@ -854,11 +1108,20 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "List Replay Videos",
       description: "List replay recordings for a browser session, including final view_url and authenticated download_url values when available.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserListReplaysOutputSchema,
       annotations: annotations("List Replay Videos", true)
     },
     async (input) => {
       const res = await req("GET", `/agent/sessions/${input.session_id}/replays`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_list_replays", res.data, input.session_id);
+      const replays = Array.isArray(res.data?.replays) ? res.data.replays : [];
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_replays",
+        session_id: input.session_id,
+        replays,
+        count: replays.length
+      });
     }
   );
   server2.registerTool(
@@ -867,11 +1130,22 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Download Replay MP4",
       description: "Download a replay recording through MCP Scraper and save the MP4 locally under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
       inputSchema: BrowserReplayDownloadInputSchema,
-      annotations: annotations("Download Replay MP4", true)
+      outputSchema: BrowserReplayDownloadOutputSchema,
+      annotations: annotations("Download Replay MP4")
     },
     async (input) => {
       const res = await downloadReplay(input.session_id, input.replay_id, input.filename);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_replay_download", res.data, input.session_id, input.replay_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_download",
+        session_id: input.session_id,
+        replay_id: input.replay_id,
+        file_path: res.data?.file_path ?? null,
+        bytes: typeof res.data?.bytes === "number" ? res.data.bytes : null,
+        mime_type: res.data?.mime_type ?? null,
+        download_url: res.data?.download_url ?? null
+      });
     }
   );
   server2.registerTool(
@@ -880,19 +1154,20 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Mark Replay Annotation",
       description: "While a replay is actively recording, locate one exact DOM target and return a ready-to-use annotation object with DOM bounds and replay-relative timing. Use this instead of guessing start_seconds or drawing rough rectangles. Workflow: start browser_replay_start, navigate until the target is visible and stable, call browser_replay_mark for each callout, then stop the replay and pass the returned annotations to browser_replay_annotate.",
       inputSchema: BrowserReplayMarkInputSchema,
+      outputSchema: BrowserReplayMarkOutputSchema,
       annotations: annotations("Mark Replay Annotation", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: [input.target] });
-      if (!res.ok) return textResult(res.data, true);
+      if (!res.ok) return errorResult("browser_replay_mark", res.data, input.session_id);
       const target = res.data?.targets?.[0];
       const element = target?.element;
       const elapsed = res.data?.replay?.replay_elapsed_seconds;
       if (!target?.found || !element) {
-        return textResult({ error: target?.error ?? "target not found in current viewport", target }, true);
+        return errorResult("browser_replay_mark", { error: target?.error ?? "target not found in current viewport", target }, input.session_id);
       }
       if (!finiteNumber2(elapsed)) {
-        return textResult({ error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, true);
+        return errorResult("browser_replay_mark", { error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, input.session_id);
       }
       const padded = expandElementBounds(element, res.data?.viewport, input.padding ?? 8);
       const start = Math.max(0, elapsed + (input.start_offset_seconds ?? -0.25));
@@ -909,7 +1184,11 @@ function registerBrowserAgentMcpTools(server2, opts) {
         ...input.color ? { color: input.color } : {},
         ...input.thickness ? { thickness: input.thickness } : {}
       };
-      return textResult({
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_mark",
+        session_id: input.session_id,
+        replay_id: res.data?.replay?.replay_id ?? res.data?.replay?.replayId ?? null,
         annotation,
         source_width: padded.sourceWidth,
         source_height: padded.sourceHeight,
@@ -925,12 +1204,13 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Annotate Replay MP4",
       description: "Download a browser replay MP4, render visual annotations over it, and save a new annotated MP4 locally. Use this after browser_replay_stop when the user wants proof videos with circles, boxes, arrows, underlines, or labels. For accurate timing and placement, prefer annotations returned by browser_replay_mark while the replay is recording; otherwise use exact left/top/width/height bounds from browser_locate. If the replay video size differs from the screenshot coordinate space, pass source_width and source_height.",
       inputSchema: BrowserReplayAnnotateInputSchema,
-      annotations: annotations("Annotate Replay MP4", true)
+      outputSchema: BrowserReplayAnnotateOutputSchema,
+      annotations: annotations("Annotate Replay MP4")
     },
     async (input) => {
       const sourceName = input.filename ? `${input.filename}-source` : void 0;
       const downloaded = await downloadReplay(input.session_id, input.replay_id, sourceName);
-      if (!downloaded.ok) return textResult(downloaded.data, true);
+      if (!downloaded.ok) return errorResult("browser_replay_annotate", downloaded.data, input.session_id, input.replay_id);
       try {
         const sourcePath = String(downloaded.data.file_path);
         const outputPath = annotatedReplayFilePath(input.session_id, input.replay_id, input.filename);
@@ -942,7 +1222,10 @@ function registerBrowserAgentMcpTools(server2, opts) {
           sourceLeftOffset: input.source_left_offset,
           sourceTopOffset: input.source_top_offset
         });
-        return textResult({
+        return structuredResult({
+          ok: true,
+          tool: "browser_replay_annotate",
+          session_id: input.session_id,
           replay_id: input.replay_id,
           source_file_path: sourcePath,
           annotated_file_path: result.filePath,
@@ -953,7 +1236,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
           mime_type: "video/mp4"
         });
       } catch (err) {
-        return textResult({ error: err instanceof Error ? err.message : String(err) }, true);
+        return errorResult("browser_replay_annotate", { error: err instanceof Error ? err.message : String(err) }, input.session_id, input.replay_id);
       }
     }
   );
@@ -961,28 +1244,43 @@ function registerBrowserAgentMcpTools(server2, opts) {
     "browser_close",
     {
       title: "Close Browser Session",
-      description: "Close and release the browser session when the task is done.",
+      description: "Close and release a browser session when the task is done, when the user asks to stop the browser, or when active browser billing should end. Use browser_list_sessions first if you need to recover the session_id.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserCloseOutputSchema,
       annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
     async (input) => {
       const res = await req("DELETE", `/agent/sessions/${input.session_id}`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_close", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_close",
+        session_id: input.session_id,
+        closed: true,
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
     "browser_list_sessions",
     {
       title: "List Browser Sessions",
-      description: "List your browser sessions and their status, with a watch_url for each.",
+      description: "List browser sessions and their status, with a watch_url for each. Use this to recover a session_id, find an active browser, or decide which session to close. Use browser_open to create a new session.",
       inputSchema: BrowserListInputSchema,
+      outputSchema: BrowserListSessionsOutputSchema,
       annotations: annotations("List Browser Sessions", true)
     },
     async (input) => {
       const res = await req("GET", `/agent/sessions${input.include_closed ? "?all=1" : ""}`);
-      if (!res.ok) return textResult(res.data, true);
+      if (!res.ok) return errorResult("browser_list_sessions", res.data);
       const sessions = (res.data.sessions ?? []).map((s) => ({ ...s, watch_url: `${consoleBase}/console/${s.session_id}` }));
-      return textResult({ sessions });
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_sessions",
+        session_id: null,
+        sessions,
+        count: sessions.length
+      });
     }
   );
 }
@@ -1462,7 +1760,7 @@ ${bodyMd.slice(0, 3e3)}${bodyMd.length > 3e3 ? "\n\n*(truncated)*" : ""}` : "";
   const full = `# URL Extract: ${url}
 **${title}**
 ${headingSection}${kpoSection}${brandingSection}${bodySection}${screenshotSection}${mediaSection}${tips}`;
-  const textResult2 = oneBlock(full);
+  const textResult = oneBlock(full);
   const structuredContent = {
     url,
     title: d.title ?? null,
@@ -1477,13 +1775,13 @@ ${headingSection}${kpoSection}${brandingSection}${bodySection}${screenshotSectio
   if (screenshotMeta?.base64) {
     return {
       content: [
-        ...textResult2.content,
+        ...textResult.content,
         { type: "image", data: screenshotMeta.base64, mimeType: "image/png" }
       ],
       structuredContent
     };
   }
-  return { ...textResult2, structuredContent };
+  return { ...textResult, structuredContent };
 }
 function formatMapSiteUrls(raw, input) {
   const parsed = parseData(raw);
@@ -1612,13 +1910,25 @@ ${videoRows}`,
     }
   };
 }
+function structuredTranscriptChunks(chunks) {
+  return chunks.map((c) => ({
+    startSec: Number.isFinite(c.timestamp?.[0]) ? c.timestamp[0] : 0,
+    endSec: Number.isFinite(c.timestamp?.[1]) ? c.timestamp[1] : 0,
+    text: c.text
+  }));
+}
+function wordCount(text) {
+  return text.trim() ? text.trim().split(/\s+/).length : 0;
+}
 function formatYoutubeTranscribe(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
   const text = d.text ?? "";
   const chunks = d.chunks ?? [];
+  const videoId = d.videoId ?? input.videoId ?? null;
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
+  const words = wordCount(text);
   const chunkRows = chunks.slice(0, 50).map((c) => {
     const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
     const mm = String(Math.floor(sec / 60)).padStart(2, "0");
@@ -1626,8 +1936,8 @@ function formatYoutubeTranscribe(raw, input) {
     return `| ${mm}:${ss} | ${cell(truncate(c.text, 120))} |`;
   }).join("\n");
   const full = [
-    `# YouTube Transcript: \`${input.videoId}\``,
-    `**Duration:** ${durSec}s \xB7 **${text.split(" ").length} words**`,
+    `# YouTube Transcript: \`${videoId ?? input.url ?? "video"}\``,
+    `**Duration:** ${durSec}s \xB7 **${words} words**`,
     `
 ## Full Transcript
 ${text}`,
@@ -1640,7 +1950,22 @@ ${chunkRows}` : "",
 ---
 \u{1F4A1} Harvest more from this channel: use \`youtube_harvest\` with \`mode: "channel"\``
   ].filter(Boolean).join("\n");
-  return oneBlock(full);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      videoId,
+      url: videoId ? `https://www.youtube.com/watch?v=${videoId}` : input.url ?? null,
+      wordCount: words,
+      chunkCount: chunks.length,
+      durationMs: typeof d.durationMs === "number" ? d.durationMs : null,
+      transcriptText: text,
+      chunks: structuredTranscriptChunks(chunks),
+      resolvedInputs: {
+        videoId,
+        url: input.url ?? null
+      }
+    }
+  };
 }
 function formatFacebookPageIntel(raw, input) {
   const parsed = parseData(raw);
@@ -1650,12 +1975,13 @@ function formatFacebookPageIntel(raw, input) {
   const ads = d.ads ?? [];
   const s = d.summary ?? { totalAds: 0, activeCount: 0, videoCount: 0, imageCount: 0 };
   const adBlocks = ads.map((ad, i) => [
-    `### Ad ${i + 1}${ad.libraryId ? ` \xB7 \`${ad.libraryId}\`` : ""} \u2014 ${ad.status ?? "\u2014"} \xB7 ${ad.creativeType ?? "\u2014"} \xB7 ${ad.startDate ?? "\u2014"}`,
+    `### Ad ${i + 1}${ad.libraryId ? ` \xB7 \`${ad.libraryId}\`` : ""} \u2014 ${ad.status ?? "\u2014"} \xB7 ${ad.creativeType ?? "\u2014"} \xB7 ${ad.startDate ?? ad.started ?? "\u2014"}`,
     ad.headline ? `**Headline:** ${ad.headline}` : "",
     ad.primaryText ? `**Copy:** ${truncate(ad.primaryText, 200)}` : "",
     ad.cta ? `**CTA:** ${ad.cta}` : "",
-    ad.videoUrl ? `**Video URL:** \`${ad.videoUrl}\`` : "",
-    ad.variations ? `**Variations:** ${ad.variations}` : ""
+    ad.landingUrl ? `**Landing URL:** ${ad.landingUrl}` : "",
+    ad.videoUrl ?? ad.videoSrc ? `**Video URL:** \`${ad.videoUrl ?? ad.videoSrc}\`` : "",
+    ad.variations ?? ad.clusterCount ? `**Variations:** ${ad.variations ?? ad.clusterCount}` : ""
   ].filter(Boolean).join("\n")).join("\n\n---\n\n");
   const full = [
     `# Facebook Ad Intel: ${advertiser}`,
@@ -1681,11 +2007,16 @@ ${adBlocks}`,
         libraryId: ad.libraryId ?? null,
         status: ad.status ?? null,
         creativeType: ad.creativeType ?? null,
+        primaryText: ad.primaryText ?? null,
         headline: ad.headline ?? null,
         cta: ad.cta ?? null,
-        startDate: ad.startDate ?? null,
-        videoUrl: ad.videoUrl ?? null,
-        variations: typeof ad.variations === "number" ? ad.variations : null
+        startDate: ad.startDate ?? ad.started ?? null,
+        landingUrl: ad.landingUrl ?? null,
+        domain: ad.domain ?? null,
+        videoUrl: ad.videoUrl ?? ad.videoSrc ?? null,
+        imageUrl: ad.imageUrl ?? ad.imageSrc ?? null,
+        videoPoster: ad.videoPoster ?? null,
+        variations: typeof ad.variations === "number" ? ad.variations : typeof ad.clusterCount === "number" ? ad.clusterCount : null
       }))
     }
   };
@@ -1719,8 +2050,11 @@ ${rows}`,
       advertiserCount: advertisers.length,
       advertisers: advertisers.map((a) => ({
         name: a.pageName ?? a.name ?? null,
+        pageId: a.pageId ?? null,
+        pageUrl: a.pageUrl ?? null,
         adCount: typeof a.adCount === "number" ? a.adCount : null,
-        libraryId: a.sampleLibraryId ?? a.libraryId ?? null
+        libraryId: a.sampleLibraryId ?? a.libraryId ?? null,
+        sampleLibraryId: a.sampleLibraryId ?? null
       }))
     }
   };
@@ -1818,6 +2152,34 @@ function formatWorkflowSuggest(input) {
     }
   };
 }
+function workflowStepLines(data) {
+  const step = data.step;
+  const nextStep = data.nextStep;
+  const done = data.done === true;
+  const lines = [];
+  if (step) {
+    const index = Number(step.index ?? 0);
+    const totalSteps = step.totalSteps != null ? Number(step.totalSteps) : void 0;
+    const stepLabel = totalSteps ? `${index + 1}/${totalSteps}` : `${index + 1}`;
+    lines.push(`
+## Step ${stepLabel}: ${step.title ?? step.id ?? ""}`);
+    const output = step.output;
+    if (output && Object.keys(output).length) {
+      lines.push(Object.entries(output).map(([k, v]) => `- ${k}: ${typeof v === "object" ? JSON.stringify(v) : String(v)}`).join("\n"));
+    }
+    const warnings = Array.isArray(step.warnings) ? step.warnings : [];
+    if (warnings.length) lines.push(`
+**Warnings:**
+${warnings.map((w) => `- ${w}`).join("\n")}`);
+  }
+  if (done) {
+    lines.push("\n**Done.** All steps complete.");
+  } else if (nextStep && typeof nextStep === "object") {
+    lines.push(`
+**Next step:** \`${nextStep.id ?? nextStep.index}\` \u2014 call \`workflow_step\` with this run id to continue.`);
+  }
+  return lines;
+}
 function formatWorkflowRun(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -1831,6 +2193,7 @@ function formatWorkflowRun(raw, input) {
     `**Run ID:** \`${runId || "unknown"}\``,
     `**Status:** ${status}`,
     summary?.title ? `**Title:** ${summary.title}` : "",
+    ...workflowStepLines(parsed.data),
     summary?.summary ? `
 ## Summary
 ${summary.summary}` : "",
@@ -1846,6 +2209,42 @@ ${workflowArtifactRows(artifacts)}` : "",
       input: input.input ?? {},
       run,
       summary,
+      step: parsed.data.step,
+      nextStep: parsed.data.nextStep ?? null,
+      done: parsed.data.done === true,
+      artifacts
+    }
+  };
+}
+function formatWorkflowStep(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const run = parsed.data.run;
+  const summary = parsed.data.summary;
+  const artifacts = workflowArtifactsFrom(run);
+  const done = parsed.data.done === true;
+  const full = [
+    `# Workflow Step`,
+    `**Run ID:** \`${input.runId}\``,
+    `**Status:** ${run?.status ?? (done ? "done" : "running")}`,
+    ...workflowStepLines(parsed.data),
+    done && summary?.summary ? `
+## Summary
+${summary.summary}` : "",
+    artifacts.length ? `
+## Artifacts
+${workflowArtifactRows(artifacts)}` : "",
+    done && artifacts.length ? "\nUse `workflow_artifact_read` with the run id and artifact id to pull CSV, JSON, Markdown, or report content into context." : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      runId: input.runId,
+      run,
+      summary: summary ?? null,
+      step: parsed.data.step,
+      nextStep: parsed.data.nextStep ?? null,
+      done,
       artifacts
     }
   };
@@ -2250,6 +2649,7 @@ function formatFacebookAdTranscribe(raw, input) {
   const text = d.text ?? "";
   const chunks = d.chunks ?? [];
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
+  const words = wordCount(text);
   const chunkRows = chunks.slice(0, 50).map((c) => {
     const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
     const mm = String(Math.floor(sec / 60)).padStart(2, "0");
@@ -2258,7 +2658,7 @@ function formatFacebookAdTranscribe(raw, input) {
   }).join("\n");
   const full = [
     `# Facebook Ad Transcript`,
-    `**Duration:** ${durSec}s \xB7 **${text.split(" ").length} words**`,
+    `**Duration:** ${durSec}s \xB7 **${words} words**`,
     `
 ## Full Transcript
 ${text}`,
@@ -2271,7 +2671,20 @@ ${chunkRows}` : "",
 ---
 \u{1F4A1} Get more ads from this advertiser: use \`facebook_page_intel\`. For public Facebook reel/post URLs, use \`facebook_video_transcribe\`.`
   ].filter(Boolean).join("\n");
-  return oneBlock(full);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      videoUrl: input.videoUrl,
+      wordCount: words,
+      chunkCount: chunks.length,
+      durationMs: typeof d.durationMs === "number" ? d.durationMs : null,
+      transcriptText: text,
+      chunks: structuredTranscriptChunks(chunks),
+      resolvedInputs: {
+        videoUrl: input.videoUrl
+      }
+    }
+  };
 }
 function formatFacebookVideoTranscribe(raw, input) {
   const parsed = parseData(raw);
@@ -2279,7 +2692,7 @@ function formatFacebookVideoTranscribe(raw, input) {
   const d = parsed.data;
   const text = d.text ?? "";
   const chunks = d.chunks ?? [];
-  const wordCount = text.trim() ? text.trim().split(/\s+/).length : 0;
+  const wordCount2 = text.trim() ? text.trim().split(/\s+/).length : 0;
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
   const videoDuration = typeof d.videoDurationSec === "number" ? `${Math.round(d.videoDurationSec)}s` : "\u2014";
   const label = d.videoId ? `Facebook Organic Video \`${d.videoId}\`` : "Facebook Organic Video";
@@ -2292,7 +2705,7 @@ function formatFacebookVideoTranscribe(raw, input) {
   const full = [
     `# ${label} Transcript`,
     d.ownerName ? `**Owner:** ${d.ownerName}` : "",
-    `**Video duration:** ${videoDuration} \xB7 **Transcribed in:** ${durSec}s \xB7 **${wordCount} words**`,
+    `**Video duration:** ${videoDuration} \xB7 **Transcribed in:** ${durSec}s \xB7 **${wordCount2} words**`,
     d.pageUrl ? `**Page URL:** ${d.pageUrl}` : `**Page URL:** ${input.url}`,
     d.videoUrl ? `**Extracted MP4:** \`${d.videoUrl}\`` : "",
     `
@@ -2318,7 +2731,7 @@ ${chunkRows}` : "",
       bitrate: typeof d.bitrate === "number" ? d.bitrate : null,
       videoDurationSec: typeof d.videoDurationSec === "number" ? d.videoDurationSec : null,
       videoUrl: d.videoUrl ?? "",
-      wordCount,
+      wordCount: wordCount2,
       chunkCount: chunks.length,
       transcriptText: text,
       chunks: chunks.map((c) => ({
@@ -2331,451 +2744,612 @@ ${chunkRows}` : "",
 }
 
 // src/mcp/mcp-tool-schemas.ts
+var import_zod3 = require("zod");
+
+// src/schemas.ts
 var import_zod2 = require("zod");
+var DEFAULT_PROXY_MODE = "configured";
+var DEFAULT_MAPS_PROXY_MODE = "location";
+var HarvestOptionsSchema = import_zod2.z.object({
+  query: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().optional(),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop"),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional(),
+  debug: import_zod2.z.boolean().default(false),
+  depth: import_zod2.z.number().int().min(1).max(30).default(3),
+  maxQuestions: import_zod2.z.number().int().min(1).max(1e3).default(100),
+  headless: import_zod2.z.boolean().default(false),
+  profileDir: import_zod2.z.string().optional(),
+  proxy: import_zod2.z.string().url().optional(),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  kernelProxyResolution: import_zod2.z.unknown().optional(),
+  outputDir: import_zod2.z.string().default("./paa-output"),
+  format: import_zod2.z.enum(["json", "csv", "both"]).default("both"),
+  serpOnly: import_zod2.z.boolean().default(false),
+  pages: import_zod2.z.number().int().min(1).max(2).default(1)
+});
+var MapsPlaceOptionsSchema = import_zod2.z.object({
+  businessName: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().min(1),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  includeReviews: import_zod2.z.boolean().default(false),
+  maxReviews: import_zod2.z.number().int().min(1).max(500).default(50),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  headless: import_zod2.z.boolean().default(true)
+});
+var MapsSearchOptionsSchema = import_zod2.z.object({
+  query: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().optional(),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  maxResults: import_zod2.z.number().int().min(1).max(50).default(10),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional(),
+  debug: import_zod2.z.boolean().default(false),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  kernelProxyResolution: import_zod2.z.unknown().optional(),
+  headless: import_zod2.z.boolean().default(true)
+});
+var RawPAAItemSchema = import_zod2.z.object({
+  question: import_zod2.z.string().min(1),
+  answer: import_zod2.z.string().optional(),
+  sourceTitle: import_zod2.z.string().optional(),
+  sourceSite: import_zod2.z.string().optional(),
+  sourceCite: import_zod2.z.string().optional()
+});
+var RawMapsOverviewSchema = import_zod2.z.object({
+  name: import_zod2.z.string().nullable(),
+  rating: import_zod2.z.string().nullable(),
+  reviewCount: import_zod2.z.string().nullable(),
+  category: import_zod2.z.string().nullable(),
+  address: import_zod2.z.string().nullable(),
+  hoursSummary: import_zod2.z.string().nullable(),
+  phone: import_zod2.z.string().nullable(),
+  phoneDisplay: import_zod2.z.string().nullable(),
+  website: import_zod2.z.string().nullable(),
+  plusCode: import_zod2.z.string().nullable(),
+  bookingUrl: import_zod2.z.string().nullable()
+});
+var RawMapsHoursRowSchema = import_zod2.z.object({
+  day: import_zod2.z.string(),
+  hours: import_zod2.z.string()
+});
+var RawMapsReviewStatsSchema = import_zod2.z.object({
+  reviewHistogram: import_zod2.z.array(import_zod2.z.object({
+    stars: import_zod2.z.number(),
+    count: import_zod2.z.string()
+  })),
+  reviewTopics: import_zod2.z.array(import_zod2.z.object({
+    label: import_zod2.z.string(),
+    count: import_zod2.z.string()
+  }))
+});
+var RawMapsReviewCardSchema = import_zod2.z.object({
+  reviewId: import_zod2.z.string(),
+  author: import_zod2.z.string().nullable(),
+  stars: import_zod2.z.string().nullable(),
+  date: import_zod2.z.string().nullable(),
+  text: import_zod2.z.string().nullable(),
+  ownerResponse: import_zod2.z.string().nullable()
+});
+var RawMapsAboutAttributeSchema = import_zod2.z.object({
+  section: import_zod2.z.string(),
+  attribute: import_zod2.z.string()
+});
+
+// src/mcp/mcp-tool-schemas.ts
 var HarvestPaaInputSchema = {
-  query: import_zod2.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
-  location: import_zod2.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
-  maxQuestions: import_zod2.z.number().int().min(1).max(200).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 200. Use 10 for quick probes, 30 for normal research, 100-200 when the user asks for everything/full/deep research. Larger harvests get a longer server time budget (151-200 questions \u2192 up to 280s). Credits are charged by extracted question; unused request hold is refunded."),
-  gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
-  hl: import_zod2.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
-  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
-  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
-  debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
+  query: import_zod3.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
+  location: import_zod3.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
+  maxQuestions: import_zod3.z.number().int().min(1).max(200).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 200. Use 10 for quick probes, 30 for normal research, 100-200 when the user asks for everything/full/deep research. Larger harvests get a longer server time budget (151-200 questions \u2192 up to 280s). Credits are charged by extracted question; unused request hold is refunded."),
+  gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
+  hl: import_zod3.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
+  device: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy targeting mode. Default configured uses the service proxy without city/ZIP targeting for the highest general success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+  proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when the user gives a specific ZIP or city-center targeting needs to be forced."),
+  debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
 };
 var ExtractUrlInputSchema = {
-  url: import_zod2.z.string().url().describe("Public http/https URL to extract. Use this when the user provides one specific page URL."),
-  screenshot: import_zod2.z.boolean().default(false).describe("Also capture a full-page screenshot of the URL. Saved to ~/Downloads/mcp-scraper/screenshots/ and returned inline. Use when the user asks to see or capture the page visually."),
-  screenshotDevice: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport for screenshot. desktop = 1440\xD7900. mobile = 390\xD7844. Default desktop."),
-  extractBranding: import_zod2.z.boolean().default(false).describe("Extract brand colors, fonts, logo, and favicon using a rendered browser session. Returns colorScheme (light/dark), colors (primary/accent/background/text/heading as hex), fonts (heading/body family names), and assets (logo URL, favicon URL). Use when the user asks about brand colors, site theme, or brand assets."),
-  downloadMedia: import_zod2.z.boolean().default(false).describe("Extract and download all page media (images, video, audio) to ~/Downloads/mcp-scraper/media/. Ad networks, tracking pixels, and noise URLs are filtered automatically. Use when the user asks to download or harvest assets from a page."),
-  mediaTypes: import_zod2.z.array(import_zod2.z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
-  allowLocal: import_zod2.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
+  url: import_zod3.z.string().url().describe("Public http/https URL to extract. Use this when the user provides one specific page URL."),
+  screenshot: import_zod3.z.boolean().default(false).describe("Also capture a full-page screenshot of the URL. Saved to ~/Downloads/mcp-scraper/screenshots/ and returned inline. Use when the user asks to see or capture the page visually."),
+  screenshotDevice: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport for screenshot. desktop = 1440\xD7900. mobile = 390\xD7844. Default desktop."),
+  extractBranding: import_zod3.z.boolean().default(false).describe("Extract brand colors, fonts, logo, and favicon using a rendered browser session. Returns colorScheme (light/dark), colors (primary/accent/background/text/heading as hex), fonts (heading/body family names), and assets (logo URL, favicon URL). Use when the user asks about brand colors, site theme, or brand assets."),
+  downloadMedia: import_zod3.z.boolean().default(false).describe("Extract and download all page media (images, video, audio) to ~/Downloads/mcp-scraper/media/. Ad networks, tracking pixels, and noise URLs are filtered automatically. Use when the user asks to download or harvest assets from a page."),
+  mediaTypes: import_zod3.z.array(import_zod3.z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
+  allowLocal: import_zod3.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
 };
 var MapSiteUrlsInputSchema = {
-  url: import_zod2.z.string().url().describe("Public website URL or domain to crawl for internal URLs. Use before extract_site when the user asks to audit/map/crawl a site."),
-  maxUrls: import_zod2.z.number().int().min(1).max(500).optional().describe("Maximum URLs to discover. Use 100 for normal maps, higher when the user asks for a full inventory.")
+  url: import_zod3.z.string().url().describe("Public website URL or domain to crawl for internal URLs. Use before extract_site when the user asks to audit/map/crawl a site."),
+  maxUrls: import_zod3.z.number().int().min(1).max(500).optional().describe("Maximum URLs to discover. Use 100 for normal maps, higher when the user asks for a full inventory.")
 };
 var ExtractSiteInputSchema = {
-  url: import_zod2.z.string().url().describe("Public website URL or domain to extract across multiple pages. Use when the user asks for a site audit, website crawl, or full-site content/schema extraction."),
-  maxPages: import_zod2.z.number().int().min(1).max(50).optional().describe("Maximum pages to extract. Use 50 when the user asks for full results or a complete crawl within MCP limits.")
+  url: import_zod3.z.string().url().describe("Public website URL or domain to extract across multiple pages. Use when the user asks for a site audit, website crawl, or full-site content/schema extraction."),
+  maxPages: import_zod3.z.number().int().min(1).max(50).optional().describe("Maximum pages to extract. Use 50 when the user asks for full results or a complete crawl within MCP limits.")
 };
 var YoutubeHarvestInputSchema = {
-  mode: import_zod2.z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
-  query: import_zod2.z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
-  channelHandle: import_zod2.z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
-  maxVideos: import_zod2.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50. Increase when user asks for full channel/history.")
+  mode: import_zod3.z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
+  query: import_zod3.z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
+  channelHandle: import_zod3.z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
+  maxVideos: import_zod3.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50, maximum 500. Use 10-25 for quick topic discovery, 50 for normal channel/search harvests, and larger values only when the user asks for full channel/history because large responses consume more context.")
 };
 var YoutubeTranscribeInputSchema = {
-  videoId: import_zod2.z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
+  videoId: import_zod3.z.string().min(1).optional().describe("YouTube video ID, e.g. dQw4w9WgXcQ. Use only an ID returned by youtube_harvest or visible in a YouTube URL; do not invent one."),
+  url: import_zod3.z.string().url().optional().describe("Full YouTube URL, e.g. https://www.youtube.com/watch?v=dQw4w9WgXcQ or https://youtu.be/dQw4w9WgXcQ. Use this when the user pasted a URL instead of an ID. Provide videoId or url.")
 };
 var FacebookPageIntelInputSchema = {
-  pageId: import_zod2.z.string().optional(),
-  libraryId: import_zod2.z.string().optional(),
-  query: import_zod2.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
-  maxAds: import_zod2.z.number().int().min(1).max(200).default(50),
-  country: import_zod2.z.string().length(2).default("US")
+  pageId: import_zod3.z.string().optional().describe("Facebook advertiser/page ID. Use only a pageId returned by facebook_ad_search/facebook_page_intel or copied from Facebook Ad Library; do not construct one yourself."),
+  libraryId: import_zod3.z.string().optional().describe("Facebook Ad Library archive ID for a known ad or advertiser sample. Use a libraryId returned by facebook_ad_search, or a libraryId/adArchiveId visible in Ad Library."),
+  query: import_zod3.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
+  maxAds: import_zod3.z.number().int().min(1).max(200).default(50).describe("Maximum ads to inspect. Default 50, maximum 200. Prefer 25-50 for focused advertiser scans; use 100-200 only when the user asks for a broad ad archive sweep."),
+  country: import_zod3.z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US. Examples: US, CA, GB, AU. Infer from the user request when they name a country.")
 };
 var FacebookAdSearchInputSchema = {
-  query: import_zod2.z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
-  country: import_zod2.z.string().length(2).default("US"),
-  maxResults: import_zod2.z.number().int().min(1).max(20).default(10)
+  query: import_zod3.z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
+  country: import_zod3.z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US. Examples: US, CA, GB, AU."),
+  maxResults: import_zod3.z.number().int().min(1).max(20).default(10).describe("Maximum advertisers to return. Default 10, maximum 20. Prefer tighter search terms over maxing this out.")
 };
 var FacebookAdTranscribeInputSchema = {
-  videoUrl: import_zod2.z.string().url().describe("Direct Facebook CDN video URL from a facebook_page_intel ad result. Do not pass a public Facebook reel/post/share URL here; use facebook_video_transcribe for organic Facebook URLs.")
+  videoUrl: import_zod3.z.string().url().describe("Direct Facebook CDN video URL from a facebook_page_intel ad result. Do not pass a public Facebook reel/post/share URL here; use facebook_video_transcribe for organic Facebook URLs.")
 };
 var FacebookVideoTranscribeInputSchema = {
-  url: import_zod2.z.string().url().describe("Organic Facebook reel, video, watch, post, or share URL from facebook.com, m.facebook.com, or fb.watch. The tool renders the page, extracts the best matching public Facebook CDN MP4 URL, then transcribes it. Use this when the user pastes a normal Facebook video page URL and asks for the transcript or downloadable MP4."),
-  quality: import_zod2.z.enum(["best", "hd", "sd"]).default("best").describe("Preferred progressive MP4 quality. Use best by default; hd prefers the highest HD progressive URL; sd forces the SD URL.")
+  url: import_zod3.z.string().url().describe("Organic Facebook reel, video, watch, post, or share URL from facebook.com, m.facebook.com, or fb.watch. The tool renders the page, extracts the best matching public Facebook CDN MP4 URL, then transcribes it. Use this when the user pastes a normal Facebook video page URL and asks for the transcript or downloadable MP4."),
+  quality: import_zod3.z.enum(["best", "hd", "sd"]).default("best").describe("Preferred progressive MP4 quality. Use best by default; hd prefers the highest HD progressive URL; sd forces the SD URL.")
 };
 var MapsPlaceIntelInputSchema = {
-  businessName: import_zod2.z.string().min(1).describe('Business name only. If user says "Elite Roofing Denver CO", use businessName="Elite Roofing" and location="Denver, CO".'),
-  location: import_zod2.z.string().min(1).describe('City/region/country where the business should be searched, e.g. "Denver, CO". Infer from the user request when possible.'),
-  gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location."),
-  hl: import_zod2.z.string().length(2).default("en").describe("Language inferred from user request."),
-  includeReviews: import_zod2.z.boolean().default(false).describe("Whether to fetch individual review cards"),
-  maxReviews: import_zod2.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
+  businessName: import_zod3.z.string().min(1).describe('Business name only. If user says "Elite Roofing Denver CO", use businessName="Elite Roofing" and location="Denver, CO".'),
+  location: import_zod3.z.string().min(1).describe('City/region/country where the business should be searched, e.g. "Denver, CO". Infer from the user request when possible.'),
+  gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from location."),
+  hl: import_zod3.z.string().length(2).default("en").describe("Language inferred from user request."),
+  includeReviews: import_zod3.z.boolean().default(false).describe("Whether to fetch individual review cards. Use true when the user asks for reviews, customer pain, complaints, praise, themes, or review evidence."),
+  maxReviews: import_zod3.z.number().int().min(1).max(500).default(50).describe("Max review cards to return when includeReviews is true. Default 50, maximum 500. Use 50 for normal review analysis and larger values only for deep review mining.")
 };
 var MapsSearchInputSchema = {
-  query: import_zod2.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
-  location: import_zod2.z.string().optional().describe('City, region, country, or service area for the Maps search, e.g. "Denver, CO". Infer from the user request when present.'),
-  gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location."),
-  hl: import_zod2.z.string().length(2).default("en").describe("Language inferred from user request."),
-  maxResults: import_zod2.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts. Use configured for the server proxy ID, and none only for local direct-network debugging."),
-  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
-  debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
+  query: import_zod3.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
+  location: import_zod3.z.string().optional().describe('City, region, country, or service area for the Maps search, e.g. "Denver, CO". Infer from the user request when present.'),
+  gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from location."),
+  hl: import_zod3.z.string().length(2).default("en").describe("Language inferred from user request."),
+  maxResults: import_zod3.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy targeting mode. Maps defaults to location so local market searches get city/state residential proxy targeting and rotation. Use configured to force the service proxy without city/ZIP targeting, and none only for local direct-network debugging."),
+  proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
+  debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
 };
 var DirectoryWorkflowInputSchema = {
-  query: import_zod2.z.string().min(1).describe("Business category, niche, or keyword to search on Google Maps for every selected market, e.g. roofers, dentists, med spas. Do not include the city here."),
-  state: import_zod2.z.string().min(2).default("TN").describe("US state abbreviation or state name used to select Census places, e.g. TN or Tennessee."),
-  minPopulation: import_zod2.z.number().int().min(0).default(1e5).describe('Minimum Census place population for market selection. Use 100000 for "cities above 100k population".'),
-  populationYear: import_zod2.z.number().int().min(2020).max(2025).default(2025).describe("Census population estimate year from the 2020-2025 Population Estimates Program city/place dataset."),
-  maxCities: import_zod2.z.number().int().min(1).max(100).default(25).describe("Maximum number of markets to process after sorting by population descending."),
-  maxResultsPerCity: import_zod2.z.number().int().min(1).max(50).default(50).describe("Google Maps business/profile candidates to collect for each city. Maximum 50."),
-  concurrency: import_zod2.z.number().int().min(1).max(5).default(5).describe("How many city Maps searches to run in parallel. Use 5 for broad directory batches unless debugging."),
-  includeZipGroups: import_zod2.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
-  usZipsCsvPath: import_zod2.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
-  saveCsv: import_zod2.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts per city. Use configured for the server proxy ID, and none only for local direct-network debugging."),
-  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
-  debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
-};
-var RankTrackerModeSchema = import_zod2.z.enum(["maps", "organic", "ai_overview", "paa"]);
+  query: import_zod3.z.string().min(1).describe("Business category, niche, or keyword to search on Google Maps for every selected market, e.g. roofers, dentists, med spas. Do not include the city here."),
+  state: import_zod3.z.string().min(2).default("TN").describe("US state abbreviation or state name used to select Census places, e.g. TN or Tennessee."),
+  minPopulation: import_zod3.z.number().int().min(0).default(1e5).describe('Minimum Census place population for market selection. Use 100000 for "cities above 100k population".'),
+  populationYear: import_zod3.z.number().int().min(2020).max(2025).default(2025).describe("Census population estimate year from the 2020-2025 Population Estimates Program city/place dataset."),
+  maxCities: import_zod3.z.number().int().min(1).max(100).default(25).describe("Maximum number of markets to process after sorting by population descending."),
+  maxResultsPerCity: import_zod3.z.number().int().min(1).max(50).default(50).describe("Google Maps business/profile candidates to collect for each city. Maximum 50."),
+  concurrency: import_zod3.z.number().int().min(1).max(5).default(5).describe("How many city Maps searches to run in parallel. Use 5 for broad directory batches unless debugging."),
+  includeZipGroups: import_zod3.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
+  usZipsCsvPath: import_zod3.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
+  saveCsv: import_zod3.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy targeting mode for every city Maps search. Maps workflows default to location so each city can use city/state or ZIP-group residential proxy targeting. Use configured to force the service proxy without city/ZIP targeting, and none only for local direct-network debugging."),
+  proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its ZIP group or city/state location."),
+  debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
+};
+var RankTrackerModeSchema = import_zod3.z.enum(["maps", "organic", "ai_overview", "paa"]);
 var RankTrackerBlueprintInputSchema = {
-  projectName: import_zod2.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
-  targetDomain: import_zod2.z.string().min(1).optional().describe("Primary domain to track in organic results, AI Overview citations, and PAA sources, e.g. example.com."),
-  targetBusinessName: import_zod2.z.string().min(1).optional().describe("Primary Google Business Profile or brand/business name to match in Maps results. Required for reliable Maps rank tracking."),
-  trackingModes: import_zod2.z.array(RankTrackerModeSchema).min(1).max(4).default(["maps", "organic", "ai_overview", "paa"]).describe("Rank tracker surfaces to build. maps uses directory_workflow/maps_search. organic uses search_serp. ai_overview uses search_serp/harvest_paa. paa uses harvest_paa source presence."),
-  keywords: import_zod2.z.array(import_zod2.z.string().min(1)).max(200).default([]).describe("Seed keywords or service queries to track. Leave empty when the downstream AI should create the keyword table from user input."),
-  locations: import_zod2.z.array(import_zod2.z.string().min(1)).max(100).default([]).describe("Markets, cities, ZIPs, or service areas to track. Use city/state strings like Denver, CO for localized SERP and Maps checks."),
-  competitors: import_zod2.z.array(import_zod2.z.string().min(1)).max(100).default([]).describe("Optional competitor domains or business names to persist as comparison targets."),
-  database: import_zod2.z.enum(["postgres", "neon", "supabase", "sqlite", "mysql"]).default("postgres").describe("Database family the downstream AI should target when generating migrations."),
-  scheduleCadence: import_zod2.z.enum(["daily", "weekly", "monthly", "custom"]).default("weekly").describe("Default recurring rank check cadence for the generated cron/heartbeat plan."),
-  customCron: import_zod2.z.string().min(1).optional().describe("Cron expression to use when scheduleCadence is custom."),
-  timezone: import_zod2.z.string().min(1).default("UTC").describe("IANA timezone for scheduled rank checks, e.g. America/Denver."),
-  includeCron: import_zod2.z.boolean().default(true).describe("Include a cron or heartbeat worker plan. Keep true for production rank trackers."),
-  includeDashboard: import_zod2.z.boolean().default(true).describe("Include dashboard/reporting requirements in the generated prompt."),
-  includeAlerts: import_zod2.z.boolean().default(true).describe("Include alert rules for rank movement and SERP feature gains/losses."),
-  notes: import_zod2.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
-};
-var NullableString = import_zod2.z.string().nullable();
-var MapsSearchAttemptOutput = import_zod2.z.object({
-  attemptNumber: import_zod2.z.number().int().min(1),
-  maxAttempts: import_zod2.z.number().int().min(1),
-  status: import_zod2.z.enum(["ok", "failed"]),
-  outcome: import_zod2.z.string(),
-  willRetry: import_zod2.z.boolean(),
-  durationMs: import_zod2.z.number().int().min(0),
-  resultCount: import_zod2.z.number().int().min(0),
-  error: NullableString,
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]),
-  proxyResolutionSource: import_zod2.z.enum(["disabled", "location_reused", "location_created", "configured_fallback", "unavailable"]).nullable(),
-  proxyIdSuffix: NullableString,
-  proxyTargetLevel: import_zod2.z.enum(["zip", "city", "state"]).nullable(),
-  proxyTargetLocation: NullableString,
-  proxyTargetZip: NullableString,
-  browserSessionIdSuffix: NullableString,
-  observedIp: NullableString,
-  observedCity: NullableString,
-  observedRegion: NullableString
+  projectName: import_zod3.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
+  targetDomain: import_zod3.z.string().min(1).optional().describe("Primary domain to track in organic results, AI Overview citations, and PAA sources, e.g. example.com."),
+  targetBusinessName: import_zod3.z.string().min(1).optional().describe("Primary Google Business Profile or brand/business name to match in Maps results. Required for reliable Maps rank tracking."),
+  trackingModes: import_zod3.z.array(RankTrackerModeSchema).min(1).max(4).default(["maps", "organic", "ai_overview", "paa"]).describe("Rank tracker surfaces to build. maps uses directory_workflow/maps_search. organic uses search_serp. ai_overview uses search_serp/harvest_paa. paa uses harvest_paa source presence."),
+  keywords: import_zod3.z.array(import_zod3.z.string().min(1)).max(200).default([]).describe("Seed keywords or service queries to track. Leave empty when the downstream AI should create the keyword table from user input."),
+  locations: import_zod3.z.array(import_zod3.z.string().min(1)).max(100).default([]).describe("Markets, cities, ZIPs, or service areas to track. Use city/state strings like Denver, CO for localized SERP and Maps checks."),
+  competitors: import_zod3.z.array(import_zod3.z.string().min(1)).max(100).default([]).describe("Optional competitor domains or business names to persist as comparison targets."),
+  database: import_zod3.z.enum(["postgres", "neon", "supabase", "sqlite", "mysql"]).default("postgres").describe("Database family the downstream AI should target when generating migrations."),
+  scheduleCadence: import_zod3.z.enum(["daily", "weekly", "monthly", "custom"]).default("weekly").describe("Default recurring rank check cadence for the generated cron/heartbeat plan."),
+  customCron: import_zod3.z.string().min(1).optional().describe("Cron expression to use when scheduleCadence is custom."),
+  timezone: import_zod3.z.string().min(1).default("UTC").describe("IANA timezone for scheduled rank checks, e.g. America/Denver."),
+  includeCron: import_zod3.z.boolean().default(true).describe("Include a cron or heartbeat worker plan. Keep true for production rank trackers."),
+  includeDashboard: import_zod3.z.boolean().default(true).describe("Include dashboard/reporting requirements in the generated prompt."),
+  includeAlerts: import_zod3.z.boolean().default(true).describe("Include alert rules for rank movement and SERP feature gains/losses."),
+  notes: import_zod3.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
+};
+var NullableString2 = import_zod3.z.string().nullable();
+var MapsSearchAttemptOutput = import_zod3.z.object({
+  attemptNumber: import_zod3.z.number().int().min(1),
+  maxAttempts: import_zod3.z.number().int().min(1),
+  status: import_zod3.z.enum(["ok", "failed"]),
+  outcome: import_zod3.z.string(),
+  willRetry: import_zod3.z.boolean(),
+  durationMs: import_zod3.z.number().int().min(0),
+  resultCount: import_zod3.z.number().int().min(0),
+  error: NullableString2,
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]),
+  proxyResolutionSource: import_zod3.z.enum(["disabled", "location_reused", "location_created", "configured_fallback", "unavailable"]).nullable(),
+  proxyIdSuffix: NullableString2,
+  proxyTargetLevel: import_zod3.z.enum(["zip", "city", "state"]).nullable(),
+  proxyTargetLocation: NullableString2,
+  proxyTargetZip: NullableString2,
+  browserSessionIdSuffix: NullableString2,
+  observedIp: NullableString2,
+  observedCity: NullableString2,
+  observedRegion: NullableString2
 });
 var MapsSearchOutputSchema = {
-  query: import_zod2.z.string(),
-  location: import_zod2.z.string().nullable(),
-  searchQuery: import_zod2.z.string(),
-  searchUrl: import_zod2.z.string().url(),
-  extractedAt: import_zod2.z.string(),
-  requestedMaxResults: import_zod2.z.number().int().min(1).max(50),
-  resultCount: import_zod2.z.number().int().min(0).max(50),
-  results: import_zod2.z.array(import_zod2.z.object({
-    position: import_zod2.z.number().int().min(1),
-    name: import_zod2.z.string(),
-    placeUrl: import_zod2.z.string().url(),
-    cid: NullableString,
-    cidDecimal: NullableString,
-    rating: NullableString,
-    reviewCount: NullableString,
-    category: NullableString,
-    address: NullableString,
-    phone: NullableString,
-    hoursStatus: NullableString,
-    websiteUrl: NullableString,
-    directionsUrl: NullableString,
-    metadata: import_zod2.z.array(import_zod2.z.string())
+  query: import_zod3.z.string(),
+  location: import_zod3.z.string().nullable(),
+  searchQuery: import_zod3.z.string(),
+  searchUrl: import_zod3.z.string().url(),
+  extractedAt: import_zod3.z.string(),
+  requestedMaxResults: import_zod3.z.number().int().min(1).max(50),
+  resultCount: import_zod3.z.number().int().min(0).max(50),
+  results: import_zod3.z.array(import_zod3.z.object({
+    position: import_zod3.z.number().int().min(1),
+    name: import_zod3.z.string(),
+    placeUrl: import_zod3.z.string().url(),
+    cid: NullableString2,
+    cidDecimal: NullableString2,
+    rating: NullableString2,
+    reviewCount: NullableString2,
+    category: NullableString2,
+    address: NullableString2,
+    phone: NullableString2,
+    hoursStatus: NullableString2,
+    websiteUrl: NullableString2,
+    directionsUrl: NullableString2,
+    metadata: import_zod3.z.array(import_zod3.z.string())
   })),
-  attempts: import_zod2.z.array(MapsSearchAttemptOutput),
-  durationMs: import_zod2.z.number().int().min(0)
-};
-var DirectoryMapsBusinessOutput = import_zod2.z.object({
-  position: import_zod2.z.number().int().min(1),
-  name: import_zod2.z.string(),
-  placeUrl: import_zod2.z.string().url(),
-  cid: NullableString,
-  cidDecimal: NullableString,
-  rating: NullableString,
-  reviewCount: NullableString,
-  category: NullableString,
-  address: NullableString,
-  phone: NullableString,
-  hoursStatus: NullableString,
-  websiteUrl: NullableString,
-  directionsUrl: NullableString,
-  metadata: import_zod2.z.array(import_zod2.z.string())
+  attempts: import_zod3.z.array(MapsSearchAttemptOutput),
+  durationMs: import_zod3.z.number().int().min(0)
+};
+var DirectoryMapsBusinessOutput = import_zod3.z.object({
+  position: import_zod3.z.number().int().min(1),
+  name: import_zod3.z.string(),
+  placeUrl: import_zod3.z.string().url(),
+  cid: NullableString2,
+  cidDecimal: NullableString2,
+  rating: NullableString2,
+  reviewCount: NullableString2,
+  category: NullableString2,
+  address: NullableString2,
+  phone: NullableString2,
+  hoursStatus: NullableString2,
+  websiteUrl: NullableString2,
+  directionsUrl: NullableString2,
+  metadata: import_zod3.z.array(import_zod3.z.string())
 });
 var DirectoryWorkflowOutputSchema = {
-  query: import_zod2.z.string(),
-  state: import_zod2.z.string(),
-  minPopulation: import_zod2.z.number().int().min(0),
-  populationYear: import_zod2.z.number().int().min(2020).max(2025),
-  maxResultsPerCity: import_zod2.z.number().int().min(1).max(50),
-  concurrency: import_zod2.z.number().int().min(1).max(5),
-  censusSourceUrl: import_zod2.z.string().url(),
-  usZipsSourcePath: NullableString,
-  warnings: import_zod2.z.array(import_zod2.z.string()),
-  extractedAt: import_zod2.z.string(),
-  selectedCityCount: import_zod2.z.number().int().min(0),
-  totalResultCount: import_zod2.z.number().int().min(0),
-  csvPath: NullableString,
-  cities: import_zod2.z.array(import_zod2.z.object({
-    city: import_zod2.z.string(),
-    state: import_zod2.z.string(),
-    location: import_zod2.z.string(),
-    cityKey: import_zod2.z.string(),
-    censusName: import_zod2.z.string(),
-    population: import_zod2.z.number().int().min(0),
-    populationYear: import_zod2.z.number().int().min(2020).max(2025),
-    zips: import_zod2.z.array(import_zod2.z.string()),
-    counties: import_zod2.z.array(import_zod2.z.string()),
-    status: import_zod2.z.enum(["ok", "empty", "failed"]),
-    error: NullableString,
-    resultCount: import_zod2.z.number().int().min(0),
-    durationMs: import_zod2.z.number().int().min(0),
-    attempts: import_zod2.z.array(MapsSearchAttemptOutput),
-    results: import_zod2.z.array(DirectoryMapsBusinessOutput)
+  query: import_zod3.z.string(),
+  state: import_zod3.z.string(),
+  minPopulation: import_zod3.z.number().int().min(0),
+  populationYear: import_zod3.z.number().int().min(2020).max(2025),
+  maxResultsPerCity: import_zod3.z.number().int().min(1).max(50),
+  concurrency: import_zod3.z.number().int().min(1).max(5),
+  censusSourceUrl: import_zod3.z.string().url(),
+  usZipsSourcePath: NullableString2,
+  warnings: import_zod3.z.array(import_zod3.z.string()),
+  extractedAt: import_zod3.z.string(),
+  selectedCityCount: import_zod3.z.number().int().min(0),
+  totalResultCount: import_zod3.z.number().int().min(0),
+  csvPath: NullableString2,
+  cities: import_zod3.z.array(import_zod3.z.object({
+    city: import_zod3.z.string(),
+    state: import_zod3.z.string(),
+    location: import_zod3.z.string(),
+    cityKey: import_zod3.z.string(),
+    censusName: import_zod3.z.string(),
+    population: import_zod3.z.number().int().min(0),
+    populationYear: import_zod3.z.number().int().min(2020).max(2025),
+    zips: import_zod3.z.array(import_zod3.z.string()),
+    counties: import_zod3.z.array(import_zod3.z.string()),
+    status: import_zod3.z.enum(["ok", "empty", "failed"]),
+    error: NullableString2,
+    resultCount: import_zod3.z.number().int().min(0),
+    durationMs: import_zod3.z.number().int().min(0),
+    attempts: import_zod3.z.array(MapsSearchAttemptOutput),
+    results: import_zod3.z.array(DirectoryMapsBusinessOutput)
   })),
-  durationMs: import_zod2.z.number().int().min(0)
+  durationMs: import_zod3.z.number().int().min(0)
 };
-var RankTrackerToolPlanOutput = import_zod2.z.object({
-  tool: import_zod2.z.string(),
-  purpose: import_zod2.z.string()
+var RankTrackerToolPlanOutput = import_zod3.z.object({
+  tool: import_zod3.z.string(),
+  purpose: import_zod3.z.string()
 });
-var RankTrackerTableOutput = import_zod2.z.object({
-  name: import_zod2.z.string(),
-  purpose: import_zod2.z.string(),
-  keyColumns: import_zod2.z.array(import_zod2.z.string())
+var RankTrackerTableOutput = import_zod3.z.object({
+  name: import_zod3.z.string(),
+  purpose: import_zod3.z.string(),
+  keyColumns: import_zod3.z.array(import_zod3.z.string())
 });
-var RankTrackerCronJobOutput = import_zod2.z.object({
-  name: import_zod2.z.string(),
-  purpose: import_zod2.z.string(),
-  modes: import_zod2.z.array(RankTrackerModeSchema),
-  recommendedTools: import_zod2.z.array(import_zod2.z.string())
+var RankTrackerCronJobOutput = import_zod3.z.object({
+  name: import_zod3.z.string(),
+  purpose: import_zod3.z.string(),
+  modes: import_zod3.z.array(RankTrackerModeSchema),
+  recommendedTools: import_zod3.z.array(import_zod3.z.string())
 });
 var RankTrackerBlueprintOutputSchema = {
-  projectName: import_zod2.z.string(),
-  targetDomain: NullableString,
-  targetBusinessName: NullableString,
-  trackingModes: import_zod2.z.array(RankTrackerModeSchema),
-  database: import_zod2.z.string(),
-  recommendedTools: import_zod2.z.array(RankTrackerToolPlanOutput),
-  tables: import_zod2.z.array(RankTrackerTableOutput),
-  cron: import_zod2.z.object({
-    enabled: import_zod2.z.boolean(),
-    cadence: import_zod2.z.string(),
-    expression: import_zod2.z.string(),
-    timezone: import_zod2.z.string(),
-    jobs: import_zod2.z.array(RankTrackerCronJobOutput)
+  projectName: import_zod3.z.string(),
+  targetDomain: NullableString2,
+  targetBusinessName: NullableString2,
+  trackingModes: import_zod3.z.array(RankTrackerModeSchema),
+  database: import_zod3.z.string(),
+  recommendedTools: import_zod3.z.array(RankTrackerToolPlanOutput),
+  tables: import_zod3.z.array(RankTrackerTableOutput),
+  cron: import_zod3.z.object({
+    enabled: import_zod3.z.boolean(),
+    cadence: import_zod3.z.string(),
+    expression: import_zod3.z.string(),
+    timezone: import_zod3.z.string(),
+    jobs: import_zod3.z.array(RankTrackerCronJobOutput)
   }),
-  metrics: import_zod2.z.array(import_zod2.z.string()),
-  implementationPrompt: import_zod2.z.string()
-};
-var OrganicResultOutput = import_zod2.z.object({
-  position: import_zod2.z.number().int(),
-  title: import_zod2.z.string(),
-  url: import_zod2.z.string(),
-  domain: import_zod2.z.string(),
-  snippet: NullableString
+  metrics: import_zod3.z.array(import_zod3.z.string()),
+  implementationPrompt: import_zod3.z.string()
+};
+var OrganicResultOutput = import_zod3.z.object({
+  position: import_zod3.z.number().int(),
+  title: import_zod3.z.string(),
+  url: import_zod3.z.string(),
+  domain: import_zod3.z.string(),
+  snippet: NullableString2
 });
-var AiOverviewOutput = import_zod2.z.object({
-  detected: import_zod2.z.boolean(),
-  text: NullableString
+var AiOverviewOutput = import_zod3.z.object({
+  detected: import_zod3.z.boolean(),
+  text: NullableString2
 }).nullable();
-var EntityIdsOutput = import_zod2.z.object({
-  kgIds: import_zod2.z.array(import_zod2.z.string()),
-  cids: import_zod2.z.array(import_zod2.z.string()),
-  gcids: import_zod2.z.array(import_zod2.z.string())
+var EntityIdsOutput = import_zod3.z.object({
+  kgIds: import_zod3.z.array(import_zod3.z.string()),
+  cids: import_zod3.z.array(import_zod3.z.string()),
+  gcids: import_zod3.z.array(import_zod3.z.string())
 }).nullable();
 var HarvestPaaOutputSchema = {
-  query: import_zod2.z.string(),
-  location: NullableString,
-  questionCount: import_zod2.z.number().int().min(0),
-  completionStatus: NullableString,
-  questions: import_zod2.z.array(import_zod2.z.object({
-    question: import_zod2.z.string(),
-    answer: NullableString,
-    sourceTitle: NullableString,
-    sourceSite: NullableString
+  query: import_zod3.z.string(),
+  location: NullableString2,
+  questionCount: import_zod3.z.number().int().min(0),
+  completionStatus: NullableString2,
+  questions: import_zod3.z.array(import_zod3.z.object({
+    question: import_zod3.z.string(),
+    answer: NullableString2,
+    sourceTitle: NullableString2,
+    sourceSite: NullableString2
   })),
-  organicResults: import_zod2.z.array(OrganicResultOutput),
+  organicResults: import_zod3.z.array(OrganicResultOutput),
   aiOverview: AiOverviewOutput,
   entityIds: EntityIdsOutput,
-  durationMs: import_zod2.z.number().min(0).nullable()
+  durationMs: import_zod3.z.number().min(0).nullable()
 };
 var SearchSerpOutputSchema = {
-  query: import_zod2.z.string(),
-  location: NullableString,
-  organicResults: import_zod2.z.array(OrganicResultOutput),
-  localPack: import_zod2.z.array(import_zod2.z.object({
-    position: import_zod2.z.number().int(),
-    name: import_zod2.z.string(),
-    rating: NullableString,
-    reviewCount: NullableString,
-    websiteUrl: NullableString
+  query: import_zod3.z.string(),
+  location: NullableString2,
+  organicResults: import_zod3.z.array(OrganicResultOutput),
+  localPack: import_zod3.z.array(import_zod3.z.object({
+    position: import_zod3.z.number().int(),
+    name: import_zod3.z.string(),
+    rating: NullableString2,
+    reviewCount: NullableString2,
+    websiteUrl: NullableString2
   })),
   aiOverview: AiOverviewOutput,
   entityIds: EntityIdsOutput
 };
 var ExtractUrlOutputSchema = {
-  url: import_zod2.z.string(),
-  title: NullableString,
-  headings: import_zod2.z.array(import_zod2.z.object({
-    level: import_zod2.z.number().int(),
-    text: import_zod2.z.string()
+  url: import_zod3.z.string(),
+  title: NullableString2,
+  headings: import_zod3.z.array(import_zod3.z.object({
+    level: import_zod3.z.number().int(),
+    text: import_zod3.z.string()
   })),
-  schemaBlockCount: import_zod2.z.number().int().min(0),
-  entityName: NullableString,
-  entityTypes: import_zod2.z.array(import_zod2.z.string()),
-  napScore: import_zod2.z.number().nullable(),
-  missingSchemaFields: import_zod2.z.array(import_zod2.z.string()),
-  screenshotSaved: NullableString
+  schemaBlockCount: import_zod3.z.number().int().min(0),
+  entityName: NullableString2,
+  entityTypes: import_zod3.z.array(import_zod3.z.string()),
+  napScore: import_zod3.z.number().nullable(),
+  missingSchemaFields: import_zod3.z.array(import_zod3.z.string()),
+  screenshotSaved: NullableString2
 };
 var ExtractSiteOutputSchema = {
-  url: import_zod2.z.string(),
-  pageCount: import_zod2.z.number().int().min(0),
-  pages: import_zod2.z.array(import_zod2.z.object({
-    url: import_zod2.z.string(),
-    title: NullableString,
-    schemaTypes: import_zod2.z.array(import_zod2.z.string())
+  url: import_zod3.z.string(),
+  pageCount: import_zod3.z.number().int().min(0),
+  pages: import_zod3.z.array(import_zod3.z.object({
+    url: import_zod3.z.string(),
+    title: NullableString2,
+    schemaTypes: import_zod3.z.array(import_zod3.z.string())
   })),
-  durationMs: import_zod2.z.number().min(0)
+  durationMs: import_zod3.z.number().min(0)
 };
 var MapsPlaceIntelOutputSchema = {
-  name: import_zod2.z.string(),
-  rating: NullableString,
-  reviewCount: NullableString,
-  category: NullableString,
-  address: NullableString,
-  phone: NullableString,
-  website: NullableString,
-  hoursSummary: NullableString,
-  bookingUrl: NullableString,
-  kgmid: NullableString,
-  cidDecimal: NullableString,
-  cidUrl: NullableString,
-  lat: import_zod2.z.number().nullable(),
-  lng: import_zod2.z.number().nullable(),
-  reviewsStatus: import_zod2.z.string(),
-  reviewsCollected: import_zod2.z.number().int().min(0),
-  reviewTopics: import_zod2.z.array(import_zod2.z.object({
-    label: import_zod2.z.string(),
-    count: import_zod2.z.string()
+  name: import_zod3.z.string(),
+  rating: NullableString2,
+  reviewCount: NullableString2,
+  category: NullableString2,
+  address: NullableString2,
+  phone: NullableString2,
+  website: NullableString2,
+  hoursSummary: NullableString2,
+  bookingUrl: NullableString2,
+  kgmid: NullableString2,
+  cidDecimal: NullableString2,
+  cidUrl: NullableString2,
+  lat: import_zod3.z.number().nullable(),
+  lng: import_zod3.z.number().nullable(),
+  reviewsStatus: import_zod3.z.string(),
+  reviewsCollected: import_zod3.z.number().int().min(0),
+  reviewTopics: import_zod3.z.array(import_zod3.z.object({
+    label: import_zod3.z.string(),
+    count: import_zod3.z.string()
   }))
 };
 var CreditsInfoOutputSchema = {
-  balanceCredits: import_zod2.z.number().nullable(),
-  matchedCost: import_zod2.z.object({
-    label: import_zod2.z.string(),
-    credits: import_zod2.z.number(),
-    unit: import_zod2.z.string(),
-    notes: NullableString
+  balanceCredits: import_zod3.z.number().nullable(),
+  matchedCost: import_zod3.z.object({
+    label: import_zod3.z.string(),
+    credits: import_zod3.z.number(),
+    unit: import_zod3.z.string(),
+    notes: NullableString2
   }).nullable(),
-  costs: import_zod2.z.array(import_zod2.z.object({
-    key: import_zod2.z.string(),
-    label: import_zod2.z.string(),
-    credits: import_zod2.z.number(),
-    unit: import_zod2.z.string(),
-    notes: NullableString
+  costs: import_zod3.z.array(import_zod3.z.object({
+    key: import_zod3.z.string(),
+    label: import_zod3.z.string(),
+    credits: import_zod3.z.number(),
+    unit: import_zod3.z.string(),
+    notes: NullableString2
   })),
-  ledger: import_zod2.z.array(import_zod2.z.object({
-    createdAt: import_zod2.z.string(),
-    operation: import_zod2.z.string(),
-    credits: import_zod2.z.number(),
-    description: NullableString
+  ledger: import_zod3.z.array(import_zod3.z.object({
+    createdAt: import_zod3.z.string(),
+    operation: import_zod3.z.string(),
+    credits: import_zod3.z.number(),
+    description: NullableString2
   })),
-  concurrency: import_zod2.z.object({
-    currentExtraSlots: import_zod2.z.number().int().min(0),
-    currentLimit: import_zod2.z.number().int().min(1),
-    hasSubscription: import_zod2.z.boolean(),
-    upgrade: import_zod2.z.object({
-      product: import_zod2.z.string(),
-      priceLabel: import_zod2.z.string(),
-      unitAmountUsd: import_zod2.z.number(),
-      currency: import_zod2.z.string(),
-      interval: import_zod2.z.string(),
-      billingUrl: import_zod2.z.string().url(),
-      terminalCommand: import_zod2.z.string(),
-      terminalCommandWithApiKeyEnv: import_zod2.z.string()
+  concurrency: import_zod3.z.object({
+    currentExtraSlots: import_zod3.z.number().int().min(0),
+    currentLimit: import_zod3.z.number().int().min(1),
+    hasSubscription: import_zod3.z.boolean(),
+    upgrade: import_zod3.z.object({
+      product: import_zod3.z.string(),
+      priceLabel: import_zod3.z.string(),
+      unitAmountUsd: import_zod3.z.number(),
+      currency: import_zod3.z.string(),
+      interval: import_zod3.z.string(),
+      billingUrl: import_zod3.z.string().url(),
+      terminalCommand: import_zod3.z.string(),
+      terminalCommandWithApiKeyEnv: import_zod3.z.string()
     })
   }).nullable()
 };
 var MapSiteUrlsOutputSchema = {
-  startUrl: import_zod2.z.string(),
-  totalFound: import_zod2.z.number().int().min(0),
-  truncated: import_zod2.z.boolean(),
-  okCount: import_zod2.z.number().int().min(0),
-  redirectCount: import_zod2.z.number().int().min(0),
-  brokenCount: import_zod2.z.number().int().min(0),
-  urls: import_zod2.z.array(import_zod2.z.object({
-    url: import_zod2.z.string(),
-    status: import_zod2.z.number().int().nullable()
+  startUrl: import_zod3.z.string(),
+  totalFound: import_zod3.z.number().int().min(0),
+  truncated: import_zod3.z.boolean(),
+  okCount: import_zod3.z.number().int().min(0),
+  redirectCount: import_zod3.z.number().int().min(0),
+  brokenCount: import_zod3.z.number().int().min(0),
+  urls: import_zod3.z.array(import_zod3.z.object({
+    url: import_zod3.z.string(),
+    status: import_zod3.z.number().int().nullable()
   })),
-  durationMs: import_zod2.z.number().min(0)
+  durationMs: import_zod3.z.number().min(0)
 };
 var YoutubeHarvestOutputSchema = {
-  mode: import_zod2.z.string(),
-  videoCount: import_zod2.z.number().int().min(0),
-  channel: import_zod2.z.object({
-    title: NullableString,
-    subscriberCount: NullableString
+  mode: import_zod3.z.string(),
+  videoCount: import_zod3.z.number().int().min(0),
+  channel: import_zod3.z.object({
+    title: NullableString2,
+    subscriberCount: NullableString2
   }).nullable(),
-  videos: import_zod2.z.array(import_zod2.z.object({
-    videoId: import_zod2.z.string(),
-    title: import_zod2.z.string(),
-    channelName: NullableString,
-    views: NullableString,
-    duration: NullableString,
-    url: NullableString
+  videos: import_zod3.z.array(import_zod3.z.object({
+    videoId: import_zod3.z.string(),
+    title: import_zod3.z.string(),
+    channelName: NullableString2,
+    views: NullableString2,
+    duration: NullableString2,
+    url: NullableString2
   }))
 };
 var FacebookAdSearchOutputSchema = {
-  query: import_zod2.z.string(),
-  advertiserCount: import_zod2.z.number().int().min(0),
-  advertisers: import_zod2.z.array(import_zod2.z.object({
-    name: NullableString,
-    adCount: import_zod2.z.number().int().nullable(),
-    libraryId: NullableString
+  query: import_zod3.z.string(),
+  advertiserCount: import_zod3.z.number().int().min(0),
+  advertisers: import_zod3.z.array(import_zod3.z.object({
+    name: NullableString2,
+    pageId: NullableString2,
+    pageUrl: NullableString2,
+    adCount: import_zod3.z.number().int().nullable(),
+    libraryId: NullableString2,
+    sampleLibraryId: NullableString2
   }))
 };
 var FacebookPageIntelOutputSchema = {
-  advertiserName: NullableString,
-  totalAds: import_zod2.z.number().int().min(0),
-  activeCount: import_zod2.z.number().int().min(0),
-  videoCount: import_zod2.z.number().int().min(0),
-  imageCount: import_zod2.z.number().int().min(0),
-  ads: import_zod2.z.array(import_zod2.z.object({
-    libraryId: NullableString,
-    status: NullableString,
-    creativeType: NullableString,
-    headline: NullableString,
-    cta: NullableString,
-    startDate: NullableString,
-    videoUrl: NullableString,
-    variations: import_zod2.z.number().int().nullable()
+  advertiserName: NullableString2,
+  totalAds: import_zod3.z.number().int().min(0),
+  activeCount: import_zod3.z.number().int().min(0),
+  videoCount: import_zod3.z.number().int().min(0),
+  imageCount: import_zod3.z.number().int().min(0),
+  ads: import_zod3.z.array(import_zod3.z.object({
+    libraryId: NullableString2,
+    status: NullableString2,
+    creativeType: NullableString2,
+    primaryText: NullableString2,
+    headline: NullableString2,
+    cta: NullableString2,
+    startDate: NullableString2,
+    landingUrl: NullableString2,
+    domain: NullableString2,
+    videoUrl: NullableString2,
+    imageUrl: NullableString2,
+    videoPoster: NullableString2,
+    variations: import_zod3.z.number().int().nullable()
   }))
 };
 var FacebookVideoTranscribeOutputSchema = {
-  sourceUrl: import_zod2.z.string().url(),
-  pageUrl: import_zod2.z.string().url(),
-  videoId: NullableString,
-  ownerName: NullableString,
-  selectedQuality: import_zod2.z.string(),
-  bitrate: import_zod2.z.number().int().nullable(),
-  videoDurationSec: import_zod2.z.number().nullable(),
-  videoUrl: import_zod2.z.string().url(),
-  wordCount: import_zod2.z.number().int().min(0),
-  chunkCount: import_zod2.z.number().int().min(0),
-  transcriptText: import_zod2.z.string(),
-  chunks: import_zod2.z.array(import_zod2.z.object({
-    startSec: import_zod2.z.number(),
-    endSec: import_zod2.z.number(),
-    text: import_zod2.z.string()
+  sourceUrl: import_zod3.z.string().url(),
+  pageUrl: import_zod3.z.string().url(),
+  videoId: NullableString2,
+  ownerName: NullableString2,
+  selectedQuality: import_zod3.z.string(),
+  bitrate: import_zod3.z.number().int().nullable(),
+  videoDurationSec: import_zod3.z.number().nullable(),
+  videoUrl: import_zod3.z.string().url(),
+  wordCount: import_zod3.z.number().int().min(0),
+  chunkCount: import_zod3.z.number().int().min(0),
+  transcriptText: import_zod3.z.string(),
+  chunks: import_zod3.z.array(import_zod3.z.object({
+    startSec: import_zod3.z.number(),
+    endSec: import_zod3.z.number(),
+    text: import_zod3.z.string()
   }))
 };
+var TranscriptChunkOutput = import_zod3.z.object({
+  startSec: import_zod3.z.number(),
+  endSec: import_zod3.z.number(),
+  text: import_zod3.z.string()
+});
+var YoutubeTranscribeOutputSchema = {
+  videoId: NullableString2,
+  url: NullableString2,
+  wordCount: import_zod3.z.number().int().min(0),
+  chunkCount: import_zod3.z.number().int().min(0),
+  durationMs: import_zod3.z.number().nullable(),
+  transcriptText: import_zod3.z.string(),
+  chunks: import_zod3.z.array(TranscriptChunkOutput),
+  resolvedInputs: import_zod3.z.object({
+    videoId: NullableString2,
+    url: NullableString2
+  })
+};
+var FacebookAdTranscribeOutputSchema = {
+  videoUrl: import_zod3.z.string().url(),
+  wordCount: import_zod3.z.number().int().min(0),
+  chunkCount: import_zod3.z.number().int().min(0),
+  durationMs: import_zod3.z.number().nullable(),
+  transcriptText: import_zod3.z.string(),
+  chunks: import_zod3.z.array(TranscriptChunkOutput),
+  resolvedInputs: import_zod3.z.object({
+    videoUrl: import_zod3.z.string().url()
+  })
+};
+var CaptureSerpSnapshotOutputSchema = {
+  schemaVersion: import_zod3.z.literal("serp-intelligence.capture.v1"),
+  status: import_zod3.z.string(),
+  query: NullableString2,
+  location: NullableString2,
+  capturedAt: NullableString2,
+  resultCount: import_zod3.z.number().int().min(0).nullable(),
+  snapshotId: NullableString2,
+  resolvedInputs: import_zod3.z.record(import_zod3.z.unknown()),
+  artifacts: import_zod3.z.array(import_zod3.z.record(import_zod3.z.unknown())),
+  diagnostics: import_zod3.z.record(import_zod3.z.unknown()).nullable(),
+  providerPayload: import_zod3.z.record(import_zod3.z.unknown())
+};
+var CaptureSerpPageSnapshotsOutputSchema = {
+  schemaVersion: import_zod3.z.literal("serp-intelligence.page-snapshots.v1"),
+  status: import_zod3.z.string(),
+  count: import_zod3.z.number().int().min(0),
+  failedCount: import_zod3.z.number().int().min(0),
+  captures: import_zod3.z.array(import_zod3.z.record(import_zod3.z.unknown())),
+  resolvedInputs: import_zod3.z.record(import_zod3.z.unknown()),
+  diagnostics: import_zod3.z.record(import_zod3.z.unknown()).nullable(),
+  providerPayload: import_zod3.z.record(import_zod3.z.unknown())
+};
 var CreditsInfoInputSchema = {
-  item: import_zod2.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", "YouTube transcription", or "concurrency"'),
-  includeLedger: import_zod2.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
+  item: import_zod3.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", "YouTube transcription", or "concurrency"'),
+  includeLedger: import_zod3.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
 };
-var WorkflowIdSchema = import_zod2.z.enum([
+var WorkflowIdSchema = import_zod3.z.enum([
   "directory",
   "agent-packet",
   "local-competitive-audit",
@@ -2785,114 +3359,129 @@ var WorkflowIdSchema = import_zod2.z.enum([
   "ai-overview-language"
 ]);
 var WorkflowListInputSchema = {
-  includeRecipes: import_zod2.z.boolean().default(true).describe("Include high-level AI-facing recipes such as market analysis, ICP research, forum/review research, brand design briefings, CRO audits, positioning briefs, content gaps, and AI search visibility audits.")
+  includeRecipes: import_zod3.z.boolean().default(true).describe("Include high-level AI-facing recipes such as market analysis, ICP research, forum/review research, brand design briefings, CRO audits, positioning briefs, content gaps, and AI search visibility audits.")
 };
 var WorkflowSuggestInputSchema = {
-  goal: import_zod2.z.string().min(1).describe('The user goal or job to route, e.g. "market analysis for roofers in Tennessee", "ICP research for med spas", "CRO audit for this URL", or "brand design briefing".'),
-  query: import_zod2.z.string().optional().describe("Business category, niche, or Maps query when known."),
-  keyword: import_zod2.z.string().optional().describe("Search keyword, audience problem, or content topic when known."),
-  domain: import_zod2.z.string().optional().describe("Target domain or brand domain when known."),
-  url: import_zod2.z.string().url().optional().describe("Target URL when the workflow should inspect a specific page."),
-  location: import_zod2.z.string().optional().describe("City/region/country for localized research, e.g. Denver, CO."),
-  state: import_zod2.z.string().optional().describe("US state abbreviation or name for state-wide market research."),
-  maxSuggestions: import_zod2.z.number().int().min(1).max(8).default(3).describe("Number of matching workflow recipes to return.")
+  goal: import_zod3.z.string().min(1).describe('The user goal or job to route, e.g. "market analysis for roofers in Tennessee", "ICP research for med spas", "CRO audit for this URL", or "brand design briefing".'),
+  query: import_zod3.z.string().optional().describe("Business category, niche, or Maps query when known."),
+  keyword: import_zod3.z.string().optional().describe("Search keyword, audience problem, or content topic when known."),
+  domain: import_zod3.z.string().optional().describe("Target domain or brand domain when known."),
+  url: import_zod3.z.string().url().optional().describe("Target URL when the workflow should inspect a specific page."),
+  location: import_zod3.z.string().optional().describe("City/region/country for localized research, e.g. Denver, CO."),
+  state: import_zod3.z.string().optional().describe("US state abbreviation or name for state-wide market research."),
+  maxSuggestions: import_zod3.z.number().int().min(1).max(8).default(3).describe("Number of matching workflow recipes to return.")
 };
 var WorkflowRunInputSchema = {
-  workflowId: WorkflowIdSchema.describe("Workflow to run. Use workflow_list or workflow_suggest first when unsure."),
-  input: import_zod2.z.record(import_zod2.z.unknown()).default({}).describe("Workflow-specific input object. Examples: agent-packet uses {keyword, domain?, location?, maxQuestions?}; local-competitive-audit uses {query, state, minPopulation?, maxCities?, maxResultsPerCity?, hydrateTop?, maxReviews?}; serp-comparison uses {keyword, domain?, url?, location?, extractTop?}."),
-  webhookUrl: import_zod2.z.string().url().optional().describe("Optional HTTPS webhook to receive the completed hosted workflow run event.")
+  workflowId: WorkflowIdSchema.describe("Workflow to run: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. Use only these values; call workflow_list or workflow_suggest first when unsure."),
+  input: import_zod3.z.record(import_zod3.z.unknown()).default({}).describe("Workflow-specific input object. Examples: agent-packet uses {keyword, domain?, location?, maxQuestions?}; local-competitive-audit uses {query, state, minPopulation?, maxCities?, maxResultsPerCity?, hydrateTop?, maxReviews?}; serp-comparison uses {keyword, domain?, url?, location?, extractTop?}."),
+  webhookUrl: import_zod3.z.string().url().optional().describe("Optional HTTPS webhook to receive the completed hosted workflow run event.")
+};
+var WorkflowStepInputSchema = {
+  runId: import_zod3.z.string().min(1).describe("Workflow run id returned by workflow_run, workflow_step, or workflow_status. Use only a returned runId; do not construct one yourself. Advances the run by exactly one step (one logical leg, e.g. one live harvest).")
 };
 var WorkflowStatusInputSchema = {
-  runId: import_zod2.z.string().min(1).describe("Workflow run id returned by workflow_run.")
+  runId: import_zod3.z.string().min(1).describe("Workflow run id returned by workflow_run, workflow_step, or workflow_status. Use only a returned runId; do not construct one yourself.")
 };
 var WorkflowArtifactReadInputSchema = {
-  runId: import_zod2.z.string().min(1).describe("Workflow run id returned by workflow_run or workflow_status."),
-  artifactId: import_zod2.z.string().min(1).describe("Artifact id from the run artifact list."),
-  maxBytes: import_zod2.z.number().int().min(1e3).max(1e6).default(2e5).describe("Maximum bytes of artifact text to return inline. Use lower values for large CSV/JSON artifacts; call again with the downloadUrl if needed outside MCP.")
-};
-var WorkflowRecipeOutput = import_zod2.z.object({
-  id: import_zod2.z.string(),
-  title: import_zod2.z.string(),
-  description: import_zod2.z.string(),
-  primaryWorkflowId: import_zod2.z.string().nullable(),
-  recommendedTools: import_zod2.z.array(import_zod2.z.string()),
-  requiredInputs: import_zod2.z.array(import_zod2.z.string()),
-  optionalInputs: import_zod2.z.array(import_zod2.z.string()),
-  produces: import_zod2.z.array(import_zod2.z.string()),
-  runHint: import_zod2.z.string()
+  runId: import_zod3.z.string().min(1).describe("Workflow run id returned by workflow_run, workflow_step, or workflow_status. Use only a returned runId; do not construct one yourself."),
+  artifactId: import_zod3.z.string().min(1).describe("Artifact id from the run artifact list returned by workflow_run, workflow_step, or workflow_status. Use only a returned artifactId; do not construct one yourself."),
+  maxBytes: import_zod3.z.number().int().min(1e3).max(1e6).default(2e5).describe("Maximum bytes of artifact text to return inline. Use lower values for large CSV/JSON artifacts; call again with the downloadUrl if needed outside MCP.")
+};
+var WorkflowRecipeOutput = import_zod3.z.object({
+  id: import_zod3.z.string(),
+  title: import_zod3.z.string(),
+  description: import_zod3.z.string(),
+  primaryWorkflowId: import_zod3.z.string().nullable(),
+  recommendedTools: import_zod3.z.array(import_zod3.z.string()),
+  requiredInputs: import_zod3.z.array(import_zod3.z.string()),
+  optionalInputs: import_zod3.z.array(import_zod3.z.string()),
+  produces: import_zod3.z.array(import_zod3.z.string()),
+  runHint: import_zod3.z.string()
 });
-var WorkflowDefinitionOutput = import_zod2.z.object({
-  id: import_zod2.z.string(),
-  title: import_zod2.z.string(),
-  description: import_zod2.z.string()
+var WorkflowDefinitionOutput = import_zod3.z.object({
+  id: import_zod3.z.string(),
+  title: import_zod3.z.string(),
+  description: import_zod3.z.string()
 });
-var WorkflowArtifactOutput = import_zod2.z.record(import_zod2.z.unknown());
+var WorkflowArtifactOutput = import_zod3.z.record(import_zod3.z.unknown());
 var WorkflowListOutputSchema = {
-  workflows: import_zod2.z.array(WorkflowDefinitionOutput),
-  recipes: import_zod2.z.array(WorkflowRecipeOutput)
+  workflows: import_zod3.z.array(WorkflowDefinitionOutput),
+  recipes: import_zod3.z.array(WorkflowRecipeOutput)
 };
 var WorkflowSuggestOutputSchema = {
-  goal: import_zod2.z.string(),
-  suggestions: import_zod2.z.array(WorkflowRecipeOutput)
+  goal: import_zod3.z.string(),
+  suggestions: import_zod3.z.array(WorkflowRecipeOutput)
 };
 var WorkflowRunOutputSchema = {
-  workflowId: import_zod2.z.string(),
-  input: import_zod2.z.record(import_zod2.z.unknown()),
-  run: import_zod2.z.record(import_zod2.z.unknown()).optional(),
-  summary: import_zod2.z.record(import_zod2.z.unknown()).optional(),
-  artifacts: import_zod2.z.array(WorkflowArtifactOutput)
+  workflowId: import_zod3.z.string(),
+  input: import_zod3.z.record(import_zod3.z.unknown()),
+  run: import_zod3.z.record(import_zod3.z.unknown()).optional(),
+  summary: import_zod3.z.record(import_zod3.z.unknown()).optional(),
+  step: import_zod3.z.record(import_zod3.z.unknown()).optional(),
+  nextStep: import_zod3.z.record(import_zod3.z.unknown()).nullable().optional(),
+  done: import_zod3.z.boolean().optional(),
+  artifacts: import_zod3.z.array(WorkflowArtifactOutput)
+};
+var WorkflowStepOutputSchema = {
+  runId: import_zod3.z.string(),
+  run: import_zod3.z.record(import_zod3.z.unknown()).optional(),
+  summary: import_zod3.z.record(import_zod3.z.unknown()).nullable().optional(),
+  step: import_zod3.z.record(import_zod3.z.unknown()).optional(),
+  nextStep: import_zod3.z.record(import_zod3.z.unknown()).nullable().optional(),
+  done: import_zod3.z.boolean(),
+  artifacts: import_zod3.z.array(WorkflowArtifactOutput)
 };
 var WorkflowStatusOutputSchema = {
-  run: import_zod2.z.record(import_zod2.z.unknown()).optional(),
-  artifacts: import_zod2.z.array(WorkflowArtifactOutput)
+  run: import_zod3.z.record(import_zod3.z.unknown()).optional(),
+  artifacts: import_zod3.z.array(WorkflowArtifactOutput)
 };
 var WorkflowArtifactReadOutputSchema = {
-  runId: import_zod2.z.string(),
-  artifactId: import_zod2.z.string(),
-  contentType: import_zod2.z.string(),
-  bytes: import_zod2.z.number().int().min(0),
-  truncated: import_zod2.z.boolean(),
-  text: import_zod2.z.string()
+  runId: import_zod3.z.string(),
+  artifactId: import_zod3.z.string(),
+  contentType: import_zod3.z.string(),
+  bytes: import_zod3.z.number().int().min(0),
+  truncated: import_zod3.z.boolean(),
+  text: import_zod3.z.string()
 };
 var SearchSerpInputSchema = {
-  query: import_zod2.z.string().min(1).describe('Core search topic only. Separate location when possible. If user says "best dentist in Brooklyn NY serp", use query="best dentist" and location="Brooklyn, NY".'),
-  location: import_zod2.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
-  gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
-  hl: import_zod2.z.string().default("en").describe("Google interface/content language inferred from user request."),
-  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
-  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
-  debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
-  pages: import_zod2.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
+  query: import_zod3.z.string().min(1).describe('Core search topic only. Separate location when possible. If user says "best dentist in Brooklyn NY serp", use query="best dentist" and location="Brooklyn, NY".'),
+  location: import_zod3.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
+  gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
+  hl: import_zod3.z.string().default("en").describe("Google interface/content language inferred from user request."),
+  device: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy targeting mode. Default configured uses the service proxy without city/ZIP targeting for the highest general SERP success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+  proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when the user gives a specific ZIP or city-center targeting needs to be forced."),
+  debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
+  pages: import_zod3.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
 };
 var CaptureSerpSnapshotInputSchema = {
-  query: import_zod2.z.string().min(1).describe("Core search query to capture as a structured SERP Intelligence snapshot. Separate the place into location when the user gives a city, region, country, or ZIP."),
-  location: import_zod2.z.string().optional().describe("City, region, country, or service area used for localized Google results. MCP Scraper records location evidence; UULE alone is not proof of localization."),
-  gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
-  hl: import_zod2.z.string().default("en").describe("Google interface/content language inferred from the user request."),
-  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
-  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting when a precise city-center or ZIP proxy is needed. With proxyMode location this ZIP is used for each fresh proxy attempt."),
-  pages: import_zod2.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
-  debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
-  includePageSnapshots: import_zod2.z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
-  pageSnapshotLimit: import_zod2.z.number().int().min(0).max(10).default(0).describe("Maximum ranking-page snapshots to capture when includePageSnapshots is true. Use 0 when only SERP evidence is needed.")
+  query: import_zod3.z.string().min(1).describe("Core search query to capture as a structured SERP Intelligence snapshot. Separate the place into location when the user gives a city, region, country, or ZIP."),
+  location: import_zod3.z.string().optional().describe("City, region, country, or service area used for localized Google results. MCP Scraper records location evidence; UULE alone is not proof of localization."),
+  gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
+  hl: import_zod3.z.string().default("en").describe("Google interface/content language inferred from the user request."),
+  device: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy behavior for capture. Default configured uses the service proxy without city/ZIP targeting for the highest general capture success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+  proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when a precise city-center or ZIP proxy is needed."),
+  pages: import_zod3.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
+  debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
+  includePageSnapshots: import_zod3.z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
+  pageSnapshotLimit: import_zod3.z.number().int().min(0).max(10).default(0).describe("Maximum ranking-page snapshots to capture when includePageSnapshots is true. Use 0 when only SERP evidence is needed.")
 };
 var ScreenshotInputSchema = {
-  url: import_zod2.z.string().url().describe("URL to capture as a full-page screenshot. Use http or https. Pass allowLocal: true to capture localhost or private-network URLs during development."),
-  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport profile. desktop = 1440\xD7900. mobile = 390\xD7844. Use desktop by default; use mobile when the user asks for a mobile view."),
-  allowLocal: import_zod2.z.boolean().default(false).describe("Allow localhost and private-network URLs (127.x, 192.168.x, 10.x, etc.). For local development only \u2014 not for production use.")
+  url: import_zod3.z.string().url().describe("URL to capture as a full-page screenshot. Use http or https. Pass allowLocal: true to capture localhost or private-network URLs during development."),
+  device: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport profile. desktop = 1440\xD7900. mobile = 390\xD7844. Use desktop by default; use mobile when the user asks for a mobile view."),
+  allowLocal: import_zod3.z.boolean().default(false).describe("Allow localhost and private-network URLs (127.x, 192.168.x, 10.x, etc.). For local development only \u2014 not for production use.")
 };
 var CaptureSerpPageSnapshotsInputSchema = {
-  urls: import_zod2.z.array(import_zod2.z.string().url()).min(1).max(25).describe("Public HTTP/HTTPS URLs to capture as SERP Intelligence page snapshots. Do not pass localhost, private IPs, file URLs, or internal admin URLs."),
-  targets: import_zod2.z.array(import_zod2.z.object({
-    url: import_zod2.z.string().url().describe("Public HTTP/HTTPS URL to capture."),
-    sourceKind: import_zod2.z.enum(["organic", "ai_citation", "local_pack_website", "configured_target", "site_subject"]).default("configured_target").describe("Why this page is being captured for SERP Intelligence evidence."),
-    sourcePosition: import_zod2.z.number().int().min(1).optional().describe("Ranking or citation position when the page came from SERP evidence.")
+  urls: import_zod3.z.array(import_zod3.z.string().url()).min(1).max(25).describe("Public HTTP/HTTPS URLs to capture as SERP Intelligence page snapshots. Do not pass localhost, private IPs, file URLs, or internal admin URLs."),
+  targets: import_zod3.z.array(import_zod3.z.object({
+    url: import_zod3.z.string().url().describe("Public HTTP/HTTPS URL to capture."),
+    sourceKind: import_zod3.z.enum(["organic", "ai_citation", "local_pack_website", "configured_target", "site_subject"]).default("configured_target").describe("Why this page is being captured for SERP Intelligence evidence."),
+    sourcePosition: import_zod3.z.number().int().min(1).optional().describe("Ranking or citation position when the page came from SERP evidence.")
   }).strict()).min(1).max(25).optional().describe("Structured page snapshot targets. Use this instead of urls when source kind or position should be preserved."),
-  maxConcurrency: import_zod2.z.number().int().min(1).max(5).default(2).describe("Parallel page captures. Use 2 normally; higher values can increase proxy/browser pressure."),
-  timeoutMs: import_zod2.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds. Increase for slow pages; timeout artifacts are returned as structured capture failures."),
-  debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics for page snapshot debugging. Use true for capture, network, or proxy troubleshooting.")
+  maxConcurrency: import_zod3.z.number().int().min(1).max(5).default(2).describe("Parallel page captures. Use 2 normally; higher values can increase proxy/browser pressure."),
+  timeoutMs: import_zod3.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds. Increase for slow pages; timeout artifacts are returned as structured capture failures."),
+  debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics for page snapshot debugging. Use true for capture, network, or proxy troubleshooting.")
 };
 
 // src/mcp/rank-tracker-blueprint.ts
@@ -3278,70 +3867,72 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   if (savesReports) registerSavedReportResources(server2);
   server2.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). For US local SERPs, leave proxyMode as location so the service uses fresh residential proxy IDs across retries, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear or the market evidence is wrong. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
+    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting for the highest general success rate. Use proxyMode location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
     inputSchema: HarvestPaaInputSchema,
     outputSchema: HarvestPaaOutputSchema,
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
   server2.registerTool("search_serp", {
     title: "Google SERP Lookup",
-    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. For US city/state rankings, keep proxyMode as location and pass proxyZip when a city-center ZIP is known; location mode uses fresh residential proxy IDs, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear, the proxy tunnel fails, or location evidence is wrong."),
+    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting. Use proxyMode location and proxyZip only when the user explicitly needs city/ZIP-targeted residential proxy evidence."),
     inputSchema: SearchSerpInputSchema,
     outputSchema: SearchSerpOutputSchema,
     annotations: liveWebToolAnnotations("Google SERP Lookup")
   }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
   server2.registerTool("extract_url", {
     title: "Single URL Extract",
-    description: withReportNote("Extract structured data from one public URL: page content as Markdown, heading structure, JSON-LD schema, entity details, NAP score, metadata, and missing schema fields. Use when the user provides a single URL or asks to inspect/scrape one page."),
+    description: withReportNote("Extract structured data from one public URL when the user provides one page, asks to inspect/scrape a page, or needs page content, schema, headings, metadata, screenshots, branding, or media assets. Returns structured page fields plus artifact handles for saved reports/screenshots/media when requested. Use map_site_urls before extracting a site inventory; use extract_site for multi-page crawling."),
     inputSchema: ExtractUrlInputSchema,
     outputSchema: ExtractUrlOutputSchema,
     annotations: liveWebToolAnnotations("Single URL Extract")
   }, async (input) => formatExtractUrl(await executor.extractUrl(input), input));
   server2.registerTool("map_site_urls", {
     title: "Site URL Map",
-    description: withReportNote("Map/crawl a public website to build a URL inventory with HTTP status codes, broken links, redirects, and site scope. Use before extract_site for audits or when the user asks for a sitemap/URL inventory."),
+    description: withReportNote("Map/crawl a public website when the user asks for a sitemap, URL inventory, broken-link scan, redirect scan, or crawl planning. Returns internal URLs with HTTP status and truncation metadata. Use this before extract_site when choosing pages for an audit; use extract_url for one known page."),
     inputSchema: MapSiteUrlsInputSchema,
     outputSchema: MapSiteUrlsOutputSchema,
     annotations: liveWebToolAnnotations("Site URL Map")
   }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
   server2.registerTool("extract_site", {
     title: "Multi-Page Site Extract",
-    description: withReportNote("Run multi-page extraction across a public website. Returns per-page titles, H1s, metadata, headings, schema/entity data, canonical URLs, and content. Use for website audits, competitor audits, and full-site extraction."),
+    description: withReportNote("Run multi-page extraction across a public website when the user asks for a website audit, competitor audit, full-site content crawl, schema inventory, or page metadata review. Returns per-page titles, H1s, metadata, headings, schema/entity data, canonical URLs, and content. Use map_site_urls first when URL selection matters; use extract_url for one page."),
     inputSchema: ExtractSiteInputSchema,
     outputSchema: ExtractSiteOutputSchema,
     annotations: liveWebToolAnnotations("Multi-Page Site Extract")
   }, async (input) => formatExtractSite(await executor.extractSite(input), input));
   server2.registerTool("youtube_harvest", {
     title: "YouTube Video Harvest",
-    description: withReportNote('Harvest YouTube video metadata by search query or channel handle/ID/URL. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, dates, durations, URLs, thumbnails, and videoIds for follow-up transcription.'),
+    description: withReportNote('Harvest YouTube video metadata when the user wants to find videos by topic, inspect a channel library, compare video angles, or get videoIds for later transcription. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, durations, URLs, and videoIds for follow-up transcription. Use youtube_transcribe after selecting one video.'),
     inputSchema: YoutubeHarvestInputSchema,
     outputSchema: YoutubeHarvestOutputSchema,
     annotations: liveWebToolAnnotations("YouTube Video Harvest")
   }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
   server2.registerTool("youtube_transcribe", {
     title: "YouTube Transcription",
-    description: withReportNote("Fetch and transcribe captions from a YouTube video. Returns full transcript, timestamped chunks, and word count. Pass a videoId from youtube_harvest results or infer it from a YouTube URL if the user provided one."),
+    description: withReportNote("Fetch and transcribe captions from a YouTube video. Use this when the user asks what was said in a YouTube video, wants claims/offers/lessons extracted from a video, or provides a YouTube URL for transcript work. Returns full transcript, timestamped chunks, word count, and resolvedInputs. Pass videoId from youtube_harvest results, or pass url when the user pasted a YouTube URL. Use youtube_harvest first when you need to discover videos by topic/channel."),
     inputSchema: YoutubeTranscribeInputSchema,
+    outputSchema: YoutubeTranscribeOutputSchema,
     annotations: liveWebToolAnnotations("YouTube Transcription")
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   server2.registerTool("facebook_page_intel", {
     title: "Facebook Advertiser Ad Intel",
-    description: withReportNote("Harvest ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and direct ad video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name as query. Use after facebook_ad_search when possible. For normal public Facebook reels/posts/watch/share URLs, use facebook_video_transcribe instead."),
+    description: withReportNote("Harvest ads from a Facebook advertiser when the user wants current ad copy, creative angles, CTAs, video URLs, or competitive ad intelligence for one brand/page. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and direct ad video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name as query. Use facebook_ad_search first when the advertiser handle is unknown. For normal public Facebook reels/posts/watch/share URLs, use facebook_video_transcribe instead."),
     inputSchema: FacebookPageIntelInputSchema,
     outputSchema: FacebookPageIntelOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
   }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
   server2.registerTool("facebook_ad_search", {
     title: "Facebook Ad Library Search",
-    description: withReportNote("Search Facebook Ad Library by brand, advertiser, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use to discover competitors, then pass libraryId to facebook_page_intel."),
+    description: withReportNote("Search Facebook Ad Library when the user wants to find advertisers by brand, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use this to discover competitor/page handles, then pass libraryId or pageId to facebook_page_intel for ad details."),
     inputSchema: FacebookAdSearchInputSchema,
     outputSchema: FacebookAdSearchOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
   server2.registerTool("facebook_ad_transcribe", {
     title: "Facebook Ad Transcription",
-    description: "Transcribe audio from a Facebook ad video CDN URL. Returns full transcript and timestamped chunks. Use only with the direct videoUrl value from facebook_page_intel results, not public Facebook post/reel/share URLs.",
+    description: "Transcribe audio from a Facebook ad video CDN URL. Use this when facebook_page_intel returned a direct videoUrl and the user asks what the ad says, what claims it makes, or wants ad-message extraction. Returns full transcript, timestamped chunks, word count, and resolvedInputs. Use only with the direct videoUrl value from facebook_page_intel results; do not pass public Facebook post/reel/share URLs. Use facebook_video_transcribe for organic Facebook URLs, and facebook_page_intel first when you only have a brand/page/ad library handle.",
     inputSchema: FacebookAdTranscribeInputSchema,
+    outputSchema: FacebookAdTranscribeOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Ad Transcription")
   }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
   server2.registerTool("facebook_video_transcribe", {
@@ -3360,14 +3951,14 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server2.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." For US city/state Maps searches, keep proxyMode as location so the browser service creates a fresh residential proxy ID and browser session for the market; retryable failures rotate to a new proxy and new browser session for up to 5 attempts. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
+    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." Maps is the default location-targeted surface: omit proxyMode for normal Maps use so the service creates residential proxy evidence for the requested market and rotates on retryable failures. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Use proxyMode configured only when you explicitly do not want city/ZIP proxy targeting. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
     inputSchema: MapsSearchInputSchema,
     outputSchema: MapsSearchOutputSchema,
     annotations: liveWebToolAnnotations("Google Maps Business Search")
   }, async (input) => formatMapsSearch(await executor.mapsSearch(input), input));
   server2.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Use concurrency up to 5 for parallel city sessions. Keep proxyMode as location so each city search creates fresh residential proxy IDs and browser sessions; retryable city failures rotate to a new proxy and new browser session for up to 5 attempts. Saved CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. Use maps_place_intel only when a selected profile needs deeper review topics, profile review count confirmation, or review cards. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
+    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Maps workflows default to location-targeted proxying so each city can use city/state or ZIP-group residential proxy evidence; use proxyMode configured only when you explicitly do not want city/ZIP proxy targeting. Saved CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. Use maps_place_intel only when a selected profile needs deeper review topics, profile review count confirmation, or review cards. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
     inputSchema: DirectoryWorkflowInputSchema,
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
@@ -3388,21 +3979,28 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   }, async (input) => formatWorkflowSuggest(input));
   server2.registerTool("workflow_run", {
     title: "Run Workflow",
-    description: withReportNote("Run a higher-level MCP Scraper workflow and return the run id, summary, and artifacts. Use after workflow_suggest or workflow_list. Runnable workflow ids: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. This is the main MCP tool for executing market analysis, ICP evidence packets, local competitive audits, Maps/SERP comparisons, content gap briefs, and AI Overview language guidance."),
+    description: withReportNote("Start a higher-level MCP Scraper workflow. Use after workflow_suggest or workflow_list. Runnable workflow ids: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. This is the main MCP tool for market analysis, ICP evidence packets, local competitive audits, Maps/SERP comparisons, content gap briefs, and AI Overview language guidance. Stepwise workflows (e.g. agent-packet) run ONE leg per call and return runId, the step output, and nextStep \u2014 when nextStep is present, call workflow_step with the runId to run the next leg, and keep calling it until done is true. This keeps each call short instead of one long blocking run, so report each step result to the user as it arrives."),
     inputSchema: WorkflowRunInputSchema,
     outputSchema: WorkflowRunOutputSchema,
     annotations: liveWebToolAnnotations("Run Workflow")
   }, async (input) => formatWorkflowRun(await executor.workflowRun(input), input));
+  server2.registerTool("workflow_step", {
+    title: "Advance Workflow Step",
+    description: withReportNote("Run the next leg of a stepwise MCP Scraper workflow started with workflow_run. Pass the runId. Each call executes exactly one logical step (typically one live harvest), persists that step's artifacts, and returns the step output plus nextStep. Keep calling workflow_step with the same runId until done is true, reporting each step result to the user as it lands. Use this instead of waiting on one long workflow call \u2014 it avoids client timeouts on long multi-step jobs."),
+    inputSchema: WorkflowStepInputSchema,
+    outputSchema: WorkflowStepOutputSchema,
+    annotations: liveWebToolAnnotations("Advance Workflow Step")
+  }, async (input) => formatWorkflowStep(await executor.workflowStep(input), input));
   server2.registerTool("workflow_status", {
     title: "Workflow Status",
-    description: "Fetch a hosted workflow run by id and list its current status and artifacts. Use after workflow_run when the model needs to re-open a run, inspect artifact ids, or recover from a long workflow.",
+    description: "Fetch a hosted workflow run by id and list its current status and artifacts. Use when a workflow may still be running, when the model needs to re-open a run, inspect artifact ids, recover from a long workflow, or decide whether to call workflow_step or workflow_artifact_read next. Use only a runId returned by workflow_run/workflow_step/workflow_status; do not construct one yourself.",
     inputSchema: WorkflowStatusInputSchema,
     outputSchema: WorkflowStatusOutputSchema,
     annotations: liveWebToolAnnotations("Workflow Status")
   }, async (input) => formatWorkflowStatus(await executor.workflowStatus(input), input));
   server2.registerTool("workflow_artifact_read", {
     title: "Read Workflow Artifact",
-    description: "Read a workflow artifact back into MCP context by run id and artifact id. Use this before writing final deliverables so the answer is grounded in generated evidence.json, CSVs, Markdown briefs, reports, and task files instead of memory. Use maxBytes to limit large CSV/JSON artifacts.",
+    description: "Read a workflow artifact back into MCP context by run id and artifact id. Use this before writing final deliverables so the answer is grounded in generated evidence.json, CSVs, Markdown briefs, reports, and task files instead of memory. Use workflow_status first when artifact ids are unknown. Use only artifactId values returned by workflow_run/workflow_step/workflow_status; do not construct one yourself. Use maxBytes to limit large CSV/JSON artifacts.",
     inputSchema: WorkflowArtifactReadInputSchema,
     outputSchema: WorkflowArtifactReadOutputSchema,
     annotations: liveWebToolAnnotations("Read Workflow Artifact")
@@ -3482,7 +4080,7 @@ function renderInstallTerminal(options) {
     "1/1 install surfaces ready",
     colorize("Newest: MCP workflow tools for market analysis, ICP research, CRO audits, brand briefs, and AI search visibility.", "lime", color),
     "",
-    `${colorize("Tools", "cyan", color)}  ${colorize("(38 MCP tools)", "muted", color)}`,
+    `${colorize("Tools", "cyan", color)}  ${colorize("(39 MCP tools)", "muted", color)}`,
     toolRow("search", ["harvest_paa", "search_serp", "maps_search", "maps_place_intel"], color),
     toolRow("extract", ["extract_url", "map_site_urls", "extract_site", "directory_workflow"], color),
     toolRow("build", ["rank_tracker_blueprint", "cron plan", "database prompt"], color),
@@ -3490,7 +4088,7 @@ function renderInstallTerminal(options) {
     toolRow("browser", ["browser_open", "browser_screenshot", "browser_read", "browser_locate", "browser_replay_mark", "browser_replay_annotate"], color),
     toolRow("account", ["credits_info", "local reports", "MCP resources"], color),
     `${colorize("Workflows", "cyan", color)}  ${colorize("(MCP + CLI + API)", "muted", color)}`,
-    toolRow("route", ["workflow_list", "workflow_suggest", "workflow_run", "workflow_status", "workflow_artifact_read"], color),
+    toolRow("route", ["workflow_list", "workflow_suggest", "workflow_run", "workflow_step", "workflow_status", "workflow_artifact_read"], color),
     toolRow("seo", ["directory", "agent-packet", "local audit", "map/serp comparison", "PAA/AIO briefs", "scheduled runs"], color),
     "",
     colorize("Usage tips:", "amber", color),