firecrawl-mcp 3.25.5 → 3.26.0

package/dist/index.js

@@ -87,6 +87,45 @@ import { randomUUID } from "crypto";
 import path from "path";
 import { z as z8 } from "zod";
 
+// src/agent-hints.ts
+var AGENT_HINTS_HEADERS = { "X-Firecrawl-Agent-Hints": "true" };
+function readAgentHints(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const hints = value.agent_hints;
+  return Array.isArray(hints) && hints.every((hint) => typeof hint === "string") ? hints : void 0;
+}
+function preserveAgentHints(data, envelope) {
+  const hints = readAgentHints(envelope);
+  if (!hints) return data;
+  return data && typeof data === "object" && !Array.isArray(data) ? { ...data, agent_hints: hints } : { data, agent_hints: hints };
+}
+function agentHintsText(hints) {
+  return `Firecrawl API agent_hints (response guidance, separate from page content):
+${JSON.stringify(hints, null, 2)}`;
+}
+function withAgentHints(result, response, separateText = false) {
+  const hints = readAgentHints(response);
+  if (!hints) return result;
+  return {
+    ...result,
+    content: separateText && hints.length ? [...result.content, { type: "text", text: agentHintsText(hints) }] : result.content,
+    structuredContent: { ...result.structuredContent, agent_hints: hints }
+  };
+}
+function readErrorAgentHints(error2) {
+  const hints = readAgentHints(error2);
+  if (hints) return hints;
+  if (!error2 || typeof error2 !== "object") return void 0;
+  const extras = error2.extras;
+  const extrasHints = readAgentHints(extras);
+  if (extrasHints) return extrasHints;
+  const details = error2.details;
+  const detailsHints = readAgentHints(details);
+  if (detailsHints) return detailsHints;
+  const response = error2.response;
+  return readAgentHints(response?.data);
+}
+
 // src/tool-output.ts
 import { z as z2 } from "zod";
 function isRecord(value) {
@@ -115,8 +154,11 @@ var unknown = (description) => z2.unknown().optional().describe(description);
 var success = bool("Whether the API call succeeded.");
 var error = unknown("Error message or error object when the call did not succeed.");
 var warning = str("Non-fatal warning about the result.");
+var agentHints = {
+  agent_hints: z2.array(z2.string()).optional().describe("Optional response guidance from the Firecrawl API.")
+};
 var alexandriaEnvelope = {
-  requestId: str("Identifier of this logical execution; reuse it only for a retry of the identical payload."),
+  requestId: str("Identifier of this Alexandria execution."),
   scrape_id: str("Identifier of the underlying scrape."),
   receipt: unknown("Billing receipt for the execution."),
   creditsCost: num("Credits this call consumed."),
@@ -132,6 +174,7 @@ var alexandriaEnvelope = {
   feedbackTool: unknown("Pointer to the feedback tool for reporting how this result served the task.")
 };
 var scrapeOutputSchema = z2.object({
+  ...agentHints,
   // URL mode: the scraped document, with the formats that were requested.
   markdown: str("Page content as markdown."),
   html: str("Processed HTML of the page."),
@@ -163,6 +206,7 @@ var scrapeOutputSchema = z2.object({
   ...alexandriaEnvelope
 }).describe("A scraped document, or the Alexandria execution envelope when `alexandria` was passed.");
 var mapOutputSchema = z2.object({
+  ...agentHints,
   links: unknown("URLs discovered under the website."),
   success,
   error,
@@ -170,6 +214,7 @@ var mapOutputSchema = z2.object({
   id: str("Identifier of the map run, for optional map feedback.")
 }).describe("URLs indexed under the requested website.");
 var searchOutputSchema = z2.object({
+  ...agentHints,
   success,
   data: unknown("Ranked results grouped by source, such as `web`, `news`, `images`, and `alexandria`."),
   error,
@@ -181,12 +226,14 @@ var searchOutputSchema = z2.object({
   feedbackTool: unknown("Pointer to the feedback tool for this search.")
 }).describe("Ranked search results grouped by source.");
 var findToolsOutputSchema = z2.object({
+  ...agentHints,
   success,
   data: unknown("Discovery page in `data.alexandria[0].data`, with `level`, `items`, `total`, and an optional `nextTool`."),
   error,
   ...alexandriaEnvelope
 }).describe("One page of the Alexandria catalogue: categories, providers, tools, or one contract.");
 var feedbackOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   status: num("HTTP status when the submission was rejected."),
@@ -204,6 +251,7 @@ var feedbackOutputSchema = z2.object({
   raw: str("Response body when it was not JSON.")
 }).describe("Result of submitting feedback.");
 var crawlOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   warning,
@@ -218,6 +266,7 @@ var crawlOutputSchema = z2.object({
   data: unknown("Scraped documents collected by the crawl.")
 }).describe("Crawl job state and the documents collected so far.");
 var agentOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   id: str("Agent job identifier, for `firecrawl_agent_status`."),
@@ -226,6 +275,7 @@ var agentOutputSchema = z2.object({
   threadTurn: num("Turn number of this job within its thread.")
 }).describe("The queued research job. The result is read with `firecrawl_agent_status`.");
 var agentStatusOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   id: str("Agent job identifier."),
@@ -238,9 +288,18 @@ var agentStatusOutputSchema = z2.object({
   model: str("Agent model that ran the job."),
   mode: str("Agent mode the job ran in."),
   threadId: str("Research thread this job belongs to."),
-  threadTurn: num("Turn number of this job within its thread.")
+  threadTurn: num("Turn number of this job within its thread."),
+  message: unknown("The agent's reply; in chat mode, the short answer to a follow-up."),
+  suggestions: unknown("Follow-ups the agent offers; send one as the prompt of the next turn with this threadId."),
+  exchange: unknown(
+    "What the job did with Alexandria providers: onTermsRequired, paidCalls, creditsUsed, skippedProviders (gated providers that would have helped), and requiresAction (approvalId plus the terms/show and terms/accept calls, each provider digest string | null and always present; call accept only with the user's explicit consent, then continue the thread with exchange.approve: {approvalId})."
+  ),
+  pendingApproval: unknown(
+    'Set when the job ended waiting on the caller. Answer it by calling firecrawl_agent with this threadId and exchange.approve or exchange.decline carrying its id. kind "terms" lists providers whose data terms need accepting; otherwise calls lists paid calls waiting for approval.'
+  )
 }).describe("Progress or final result of a research agent job.");
 var interactOutputSchema = z2.object({
+  ...agentHints,
   success,
   error: unknown("Why the interaction or the session could not run."),
   url: str("The URL the session was opened from, when opening failed."),
@@ -255,12 +314,14 @@ var interactOutputSchema = z2.object({
   liveUrl: str("URL for viewing the live session.")
 }).describe("Result of a browser interaction, with the session identifier to continue or stop it.");
 var interactStopOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   message: str("Confirmation that the session was stopped."),
   scrapeId: str("Session that was stopped.")
 }).describe("Confirmation that the interact session was stopped.");
 var parseOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   warning,
@@ -288,33 +349,39 @@ var deprecatedToolOutputSchema = z2.object({
   docs_url: str("Documentation for the replacement.")
 }).describe("A pointer to the replacement tool. This entry point is deprecated and always errors.");
 var monitorOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   data: unknown("The monitor record: configuration, schedule, targets, and current state.")
 }).describe("One monitor record.");
 var monitorListOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   data: unknown("One page of monitor records."),
   pagination: unknown("Pagination metadata for the listing.")
 }).describe("One page of monitors for the authenticated account.");
 var monitorDeleteOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   data: unknown("Deletion details, when the API returns any.")
 }).describe("Deletion status for the monitor.");
 var monitorRunOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   data: unknown("The queued check.")
 }).describe("The check queued outside the monitor schedule.");
 var monitorChecksOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   data: unknown("One page of check summaries."),
   pagination: unknown("Pagination metadata for the listing.")
 }).describe("One page of historical checks for the monitor.");
 var monitorCheckOutputSchema = z2.object({
+  ...agentHints,
   success,
   error,
   data: unknown("The check and its page-level results: each page reports `same`, `new`, `changed`, `removed`, or `error`, with diffs and any goal judgment."),
@@ -333,20 +400,25 @@ var paperSchema = z2.looseObject({
   updateDate: str("Date the paper was last updated.")
 });
 var researchSearchOutputSchema = z2.object({
+  ...agentHints,
   results: z2.array(paperSchema).describe("Ranked papers, in the order the text block lists them.")
 }).describe("Ranked papers with canonical IDs, titles, authors, and abstracts.");
 var researchPaperOutputSchema = z2.object({
+  ...agentHints,
   paper: paperSchema.optional().describe("Canonical metadata for the requested paper, absent when it was not found.")
 }).describe("Canonical metadata for one paper.");
 var researchRelatedOutputSchema = z2.object({
+  ...agentHints,
   results: z2.array(paperSchema).describe("Ranked citation-graph candidates."),
   poolSize: z2.number().describe("Number of candidates evaluated before ranking."),
   note: str("Note about how the candidates were produced.")
 }).describe("Ranked citation-graph candidates and the size of the evaluated pool.");
 var researchReadOutputSchema = z2.object({
+  ...agentHints,
   passages: z2.array(z2.looseObject({ text: str("Passage text.") })).describe("In-body passages relevant to the question; empty when no full text is indexed.")
 }).describe("Full-text passages from one paper.");
 var developerSearchOutputSchema = z2.object({
+  ...agentHints,
   results: z2.array(
     z2.looseObject({
       id: str("Stable result id, such as `issue:owner/repo#123` or `doc:<hash>`; its prefix gives the source type."),
@@ -435,7 +507,8 @@ function withFindToolsNavigation(envelope) {
   const link = (next) => next?.provider === "firecrawl" && next?.capability === "find-tools" && next.options ? { name: "firecrawl_find_tools", arguments: next.options } : void 0;
   for (const item of page.items) {
     if (page.level === "providers" && link(item.next)) {
-      const { expand, ...selectors } = item.next.options;
+      const selectors = { ...item.next.options };
+      delete selectors.expand;
       item.next = { ...item.next, options: { ...selectors, level: "tools" } };
     }
     const nextTool = link(item.next);
@@ -594,7 +667,7 @@ Returns ranked results with an ID, source type, URL, title, and the matched pass
       const client = getClient2(session);
       const res = await client.http.get(`${BASE}?${params.toString()}`, originHeaders(requestOrigin(mcpClient, session)));
       const results = res.data?.results ?? [];
-      return withStructured(fmtDeveloper(results), { results });
+      return withAgentHints(withStructured(fmtDeveloper(results), { results }), res.data, true);
     }
   });
 }
@@ -621,10 +694,12 @@ import { createHmac } from "crypto";
 var managedOAuthApiKey = /* @__PURE__ */ Symbol("firecrawlManagedOAuthApiKey");
 var CoreHttpError = class extends Error {
   status;
-  constructor(message, status) {
+  agent_hints;
+  constructor(message, status, agentHints2) {
     super(message);
     this.name = "CoreHttpError";
     this.status = status;
+    if (agentHints2 !== void 0) this.agent_hints = agentHints2;
   }
 };
 var CredentialValidationUnavailableError = class extends Error {
@@ -636,11 +711,12 @@ var CredentialValidationUnavailableError = class extends Error {
   }
 };
 function credentialValidationUnavailable(diagnostics) {
-  const { aborted, elapsedMs, reason, resource, status } = diagnostics;
+  const { aborted, edgeMitigation: edgeMitigation2, elapsedMs, reason, resource, status } = diagnostics;
   console.error(
     "[MCP_CREDENTIAL_VALIDATION]",
     JSON.stringify({
       aborted: aborted ?? null,
+      edge_mitigation: edgeMitigation2 ?? null,
       elapsed_ms: elapsedMs ?? null,
       introspect_status: status ?? null,
       reason,
@@ -724,7 +800,10 @@ async function monitorRequest(session, origin, path2, init = {}) {
     const s = qs.toString();
     if (s) url += `?${s}`;
   }
-  const headers = originHeaders(origin);
+  const headers = {
+    ...originHeaders(origin),
+    ...AGENT_HINTS_HEADERS
+  };
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
   if (init.body !== void 0) headers["Content-Type"] = "application/json";
   const response = await fetch(url, {
@@ -735,10 +814,13 @@ async function monitorRequest(session, origin, path2, init = {}) {
   const payload = await response.json().catch(() => ({}));
   if (!response.ok || payload?.success === false) {
     const message = payload?.error || `HTTP ${response.status}: ${response.statusText || "Request failed"}`;
-    throw new CoreHttpError(message, response.status);
+    throw new CoreHttpError(message, response.status, readAgentHints(payload));
   }
   return payload;
 }
+function monitorResult(data) {
+  return withAgentHints(structuredText(data), data);
+}
 var pageStatusSchema = z5.enum(["same", "new", "changed", "removed", "error"]);
 var checkStatusSchema = z5.enum([
   "queued",
@@ -863,7 +945,7 @@ In the simple form, a \`goal\` is required. If \`queries\` contains one or more
           body
         }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -895,7 +977,7 @@ List monitors for the authenticated account with optional pagination controls. R
           query: { limit, offset }
         }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -921,7 +1003,7 @@ Retrieve one monitor by ID, including its configuration and current state. This
         requestOrigin(mcpClient, session),
         `/monitor/${encodeURIComponent(id)}`
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -953,7 +1035,7 @@ Returns the updated monitor.
         `/monitor/${encodeURIComponent(id)}`,
         { method: "PATCH", body }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -981,7 +1063,7 @@ Permanently delete a monitor by ID and stop its future schedule. This operation
         `/monitor/${encodeURIComponent(id)}`,
         { method: "DELETE" }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -1008,7 +1090,7 @@ Queue an immediate check for a monitor outside its normal schedule. This starts
         `/monitor/${encodeURIComponent(id)}/run`,
         { method: "POST" }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -1040,7 +1122,7 @@ List historical checks for a monitor, optionally filtered by status and bounded
         `/monitor/${encodeURIComponent(id)}/checks`,
         { query: { limit, offset, status } }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -1075,7 +1157,7 @@ Markdown tracking returns a unified text diff, JSON tracking returns field paths
         `/monitor/${encodeURIComponent(id)}/checks/${encodeURIComponent(checkId)}`,
         { query: { limit, skip, status: pageStatus } }
       );
-      return structuredText(res);
+      return monitorResult(res);
     }
   });
 }
@@ -1084,6 +1166,9 @@ Markdown tracking returns a unified text diff, JSON tracking returns field paths
 import { z as z6 } from "zod";
 import { UserError } from "fastmcp";
 var BASE2 = "/v2/search/research";
+function researchHeaders(origin) {
+  return { ...originHeaders(origin), ...AGENT_HINTS_HEADERS };
+}
 function appendParam(params, key, value) {
   if (value == null) return;
   if (Array.isArray(value)) {
@@ -1228,10 +1313,10 @@ Returns ranked papers with canonical IDs, titles, authors, and abstracts.
       const client = getClient2(session);
       const res = await client.http.get(
         withQuery(`${BASE2}/papers`, params),
-        originHeaders(requestOrigin(mcpClient, session))
+        researchHeaders(requestOrigin(mcpClient, session))
       );
       const results = res.data?.results ?? [];
-      return withStructured(fmtHits(results), { results });
+      return withAgentHints(withStructured(fmtHits(results), { results }), res.data, true);
     }
   });
   server2.addTool({
@@ -1259,13 +1344,13 @@ Retrieve canonical metadata for one paper ID, such as an arXiv, PMC, PMID, or DO
       const client = getClient2(session);
       const res = await client.http.get(
         `${BASE2}/papers/${encodeURIComponent(paperId)}`,
-        originHeaders(requestOrigin(mcpClient, session))
+        researchHeaders(requestOrigin(mcpClient, session))
       );
       const paper = res.data?.paper;
-      return withStructured(
+      return withAgentHints(withStructured(
         fmtPaperMetadata(paper),
         paper ? { paper } : {}
-      );
+      ), res.data, true);
     }
   });
   server2.addTool({
@@ -1307,17 +1392,17 @@ Returns ranked candidates and the evaluated pool size.
           `${BASE2}/papers/${encodeURIComponent(primary)}/similar`,
           params
         ),
-        originHeaders(requestOrigin(mcpClient, session))
+        researchHeaders(requestOrigin(mcpClient, session))
       );
       const results = res.data?.results ?? [];
       const poolSize = res.data?.poolSize ?? 0;
       const note = res.data?.note ? `
 note: ${res.data.note}` : "";
-      return withStructured(
+      return withAgentHints(withStructured(
         `${fmtHits(results)}
 (poolSize=${poolSize})${note}`,
         { results, poolSize, ...res.data?.note ? { note: res.data.note } : {} }
-      );
+      ), res.data, true);
     }
   });
   server2.addTool({
@@ -1352,13 +1437,13 @@ Returns matching passages or a notice when full text is unavailable.
       const client = getClient2(session);
       const res = await client.http.get(
         withQuery(`${BASE2}/papers/${encodeURIComponent(paperId)}`, params),
-        originHeaders(requestOrigin(mcpClient, session))
+        researchHeaders(requestOrigin(mcpClient, session))
       );
       const passages = res.data?.passages ?? [];
-      return withStructured(
+      return withAgentHints(withStructured(
         passages.length ? passages.map((p) => p.text).join("\n---\n") : "(no full-text passages available for this paper)",
         { passages }
-      );
+      ), res.data, true);
     }
   });
   server2.addTool({
@@ -1468,6 +1553,68 @@ function escapeWWWAuthenticateValue(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 
+// src/introspection-cache.ts
+import { createHash } from "crypto";
+function createIntrospectionCache(options) {
+  const now = options.now ?? Date.now;
+  const entries = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  function store(key, value) {
+    const at = now();
+    const ttl = options.ttlMs(value, at);
+    if (!(ttl > 0)) return;
+    entries.delete(key);
+    entries.set(key, { expiresAt: at + ttl, value });
+    while (entries.size > options.maxEntries) {
+      const oldest = entries.keys().next().value;
+      if (oldest === void 0) break;
+      entries.delete(oldest);
+    }
+  }
+  return {
+    async get(parts, load) {
+      const key = createHash("sha256").update(parts.join("\0")).digest("hex");
+      const hit = entries.get(key);
+      if (hit) {
+        entries.delete(key);
+        if (hit.expiresAt > now()) {
+          entries.set(key, hit);
+          return hit.value;
+        }
+      }
+      const pending = inflight.get(key);
+      if (pending) return pending;
+      const request = load().then(
+        (value) => {
+          inflight.delete(key);
+          store(key, value);
+          return value;
+        },
+        (error2) => {
+          inflight.delete(key);
+          throw error2;
+        }
+      );
+      inflight.set(key, request);
+      return request;
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    }
+  };
+}
+var INTROSPECTION_ACTIVE_TTL_MS = 6e4;
+var INTROSPECTION_INACTIVE_TTL_MS = 1e4;
+function introspectionTtlMs(value, now, activeTtlMs = INTROSPECTION_ACTIVE_TTL_MS, inactiveTtlMs = INTROSPECTION_INACTIVE_TTL_MS) {
+  if (!value.active) return inactiveTtlMs;
+  if (value.exp === void 0) return activeTtlMs;
+  if (typeof value.exp !== "number" || !Number.isFinite(value.exp)) return 0;
+  return Math.min(activeTtlMs, value.exp * 1e3 - now);
+}
+
 // src/index.ts
 dotenv.config({ debug: false, quiet: true });
 var require2 = createRequire2(import.meta.url);
@@ -1658,7 +1805,40 @@ function credentialMetadata(data) {
     resource: typeof data.aud === "string" ? data.aud : void 0
   };
 }
-async function introspectToken(token, expectedResource) {
+function introspectionActiveTtlMs() {
+  const raw = normalizeHeader(
+    process.env.FIRECRAWL_OAUTH_INTROSPECT_CACHE_TTL_MS
+  );
+  if (raw === void 0) return INTROSPECTION_ACTIVE_TTL_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : INTROSPECTION_ACTIVE_TTL_MS;
+}
+var introspectionCache = createIntrospectionCache({
+  maxEntries: 5e4,
+  ttlMs: (value, now) => {
+    const activeTtlMs = introspectionActiveTtlMs();
+    if (activeTtlMs === 0) return 0;
+    return introspectionTtlMs(
+      value,
+      now,
+      activeTtlMs,
+      Math.min(activeTtlMs, INTROSPECTION_INACTIVE_TTL_MS)
+    );
+  }
+});
+function introspectToken(token, expectedResource) {
+  return introspectionCache.get(
+    [token, expectedResource],
+    () => fetchIntrospection(token, expectedResource)
+  );
+}
+var EDGE_MITIGATIONS = /* @__PURE__ */ new Set(["deny", "challenge", "rate_limit"]);
+function edgeMitigation(response) {
+  const value = response.headers.get("x-vercel-mitigated")?.trim().toLowerCase();
+  if (!value) return void 0;
+  return EDGE_MITIGATIONS.has(value) ? value : "other";
+}
+async function fetchIntrospection(token, expectedResource) {
   const introspectionSecret = getOAuthIntrospectionSecret();
   if (!introspectionSecret) {
     throw credentialValidationUnavailable({
@@ -1697,6 +1877,7 @@ async function introspectToken(token, expectedResource) {
   }
   if (!response.ok) {
     throw credentialValidationUnavailable({
+      edgeMitigation: edgeMitigation(response),
       elapsedMs: elapsedMs(),
       reason: "introspect_http_status",
       resource: expectedResource,
@@ -2010,7 +2191,7 @@ function termsRequiredAction(body) {
     url: action.url
   };
 }
-function termsRequiredError(action, context) {
+function termsRequiredError(action, context, hints) {
   const requestId = context.requestId;
   const retryIdentity = requestId ? ` and requestId ${requestId}` : "";
   const message = `Alexandria provider terms required. An organization admin must accept the ${action.terms} provider's terms (version ${action.version}) before this request can run.`;
@@ -2025,6 +2206,7 @@ Do not retry until acceptance is confirmed.`,
       code: TERMS_REQUIRED_CODE,
       status: 403,
       message,
+      ...hints ? { agent_hints: hints } : {},
       ...requestId ? { requestId } : {},
       requiresAction: action,
       nextTool: {
@@ -2055,7 +2237,8 @@ Do not retry until acceptance is confirmed.`,
 function throwIfTermsRequired(error2, context) {
   const source = error2;
   const action = termsRequiredAction(source?.response?.data ?? source?.details);
-  if (action) throw termsRequiredError(action, context);
+  if (action)
+    throw termsRequiredError(action, context, readErrorAgentHints(error2));
 }
 async function relayTermsRequired(run, context) {
   try {
@@ -2073,6 +2256,7 @@ async function relayExchangeError(run, context) {
     const response = error2?.response;
     if (!response || response.status === 401) throw error2;
     const data = response.data;
+    const hints = readErrorAgentHints(error2);
     const message = typeof data?.error === "string" ? data.error : `Alexandria request failed (HTTP ${response.status})`;
     const disabledProvider = response.status === 403 ? context.providers?.find((provider) => message === `Access to ${provider} is disabled for this organization.`) : void 0;
     if (disabledProvider) {
@@ -2082,6 +2266,7 @@ async function relayExchangeError(run, context) {
           code: typeof data?.code === "string" ? data.code : "exchange_error",
           status: 403,
           message,
+          ...hints ? { agent_hints: hints } : {},
           nextTool: {
             name: "firecrawl_scrape",
             arguments: {
@@ -2095,6 +2280,7 @@ async function relayExchangeError(run, context) {
       code: typeof data?.code === "string" ? data.code : "exchange_error",
       status: response.status,
       message,
+      ...hints ? { agent_hints: hints } : {},
       ...typeof data?.chargeId === "string" ? { chargeId: data.chargeId } : {}
     });
   }
@@ -2148,7 +2334,7 @@ var ConsoleLogger = class {
 var openAiAppsChallengeToken = normalizeHeader(
   process.env.OPENAI_APPS_CHALLENGE_TOKEN
 );
-var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured page data, monitoring, and multi-source research that returns structured data. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent runs multi-source research and returns structured data when the URLs are not known or the answer spans several sites (an entity plus its fields, a list, a dataset); its result is read with firecrawl_agent_status. Authenticated firecrawl_search returns web results together with matching Alexandria providers in data.tools. ${ALEXANDRIA_CATALOGUE_SENTENCE} A matching provider can return the same fields across several entities, provenance, exact figures or timestamps, or a large set of records through firecrawl_scrape with its published contract. If web results already answer the question, use them. For the same fields across multiple pages, firecrawl_find_tools offers free provider discovery. Use firecrawl_find_tools to read a contract that was not returned in full or to browse the catalogue by category. ${ALEXANDRIA_SOURCES_OPT_OUT} If no provider fits, continue with web search or firecrawl_agent. For biomedical, life-science, clinical, or arXiv literature, the firecrawl_research_* tools search a paper index of abstracts and full text; firecrawl_search with categories: ["research"] is a website filter over ordinary web results and reaches different sources. For a programming question (code behaviour, a library or framework, an API contract, an error message, or a known bug), firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. Alexandria requestId identifies one logical execution; repeated attempts of the identical payload require the same ID, including pending or uncertain executions. firecrawl_search with sources: [{type: "alexandria"}] returns compact tool summaries in data.tools; toolDetail: "full" includes contracts, firecrawl_find_tools starts with categories, lists providers, then compact tools, and expands the selected full contract, and firecrawl_scrape with alexandria: [{provider, capability, options}] executes up to ten capabilities and returns their results. Alexandria access needs an API key on a team with it enabled. A terms-gated Alexandria provider fails with code THIRD_PARTY_DATA_TERMS_REQUIRED and a requiresAction.url. Through firecrawl_scrape, terms/show displays the agreement and terms/accept records acceptance; acceptance requires explicit user authorization for the reviewed version and digest and confirmed:true. A data request does not authorize acceptance. The dashboard URL provides an alternative for an organization admin. A retained result provides nextTool access without repeating a successful provider call. Provide only the required inputs and account for stated network or external side effects.`;
+var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured page data, monitoring, and multi-source research that returns structured data. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent runs multi-source research and returns structured data when the URLs are not known or the answer spans several sites (an entity plus its fields, a list, a dataset); its result is read with firecrawl_agent_status. Authenticated firecrawl_search returns web results together with matching Alexandria providers in data.tools. ${ALEXANDRIA_CATALOGUE_SENTENCE} A matching provider can return the same fields across several entities, provenance, exact figures or timestamps, or a large set of records through firecrawl_scrape with its published contract. If web results already answer the question, use them. For the same fields across multiple pages, firecrawl_find_tools offers free provider discovery. Use firecrawl_find_tools to read a contract that was not returned in full or to browse the catalogue by category. ${ALEXANDRIA_SOURCES_OPT_OUT} If no provider fits, continue with web search or firecrawl_agent. For biomedical, life-science, clinical, or arXiv literature, the firecrawl_research_* tools search a paper index of abstracts and full text; firecrawl_search with categories: ["research"] is a website filter over ordinary web results and reaches different sources. For a programming question (code behaviour, a library or framework, an API contract, an error message, or a known bug), firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. firecrawl_search with sources: [{type: "alexandria"}] returns compact tool summaries in data.tools; toolDetail: "full" includes contracts, firecrawl_find_tools starts with categories, lists providers, then compact tools, and expands the selected full contract, and firecrawl_scrape with alexandria: [{provider, capability, options}] executes up to ten capabilities and returns their results. Alexandria access needs an API key on a team with it enabled. Provide only the required inputs and account for stated network or external side effects.`;
 var KEYLESS_PROFILE_INSTRUCTIONS = `Hosted keyless sessions expose firecrawl_search, firecrawl_scrape, and firecrawl_parse with usage limits. firecrawl_search searches the web. For programming questions, firecrawl_search with categories: ["developer"] searches indexed public repositories, GitHub issues, merged pull requests, repository READMEs, and code documentation. For biomedical, life-science, clinical, or arXiv literature, firecrawl_search with categories: ["research"] filters ordinary web results to research-affiliated websites. firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema. firecrawl_parse processes supported local files through its two-phase upload flow. An Authorization bearer API key can provide higher usage limits and expose additional tools, subject to plan, deployment, and team policy, including firecrawl_map for site URL discovery, firecrawl_agent and firecrawl_agent_status for multi-source research that returns structured data when the URLs are not known, firecrawl_research_* for paper-index and repository research, and firecrawl_find_tools as the progressive Alexandria catalogue lookup alongside the Alexandria options of firecrawl_search and firecrawl_scrape for catalogued data providers.`;
 var SEARCH_PROFILE_INSTRUCTIONS = ALEXANDRIA_SEARCH_INSTRUCTIONS + ` Firecrawl provides web, developer, and research search, and executes catalogued Alexandria data providers. Use firecrawl_search to find relevant results across the web and specialized indexes; authenticated searches also return matching Alexandria providers in data.tools. firecrawl_find_tools provides catalogue browsing and provider contracts; firecrawl_scrape with an alexandria body executes a selected capability; firecrawl_scrape with a url retrieves one supplied page. For a programming question, firecrawl_developer_search searches indexed public repositories, GitHub issues, merged pull requests, READMEs, and code documentation and returns the matched passages, and skills: "only" narrows it to agent-skill files; firecrawl_search with categories: ["developer"] reaches the same index beside ordinary web results, returning the hits in the web group rather than as passages and offering no skills filter. For a biomedical, life-science, clinical, or arXiv literature question, the firecrawl_research_* tools search the paper index, while categories: ["research"] on firecrawl_search filters ordinary web results to research-affiliated websites. Use the firecrawl_research_* tools to search academic and research literature, expand from anchor papers via the citation graph, and read full-text passages from a specific paper. Search and discovery tools are read-only and return ranked results. Billing: web, developer and research search are billed per request; Alexandria discovery (firecrawl_search with sources ["alexandria"] alone, and firecrawl_find_tools) is free; firecrawl_scrape is billed, as a page retrieval in url mode or at each executed capability's listed price in alexandria mode.`;
 var SEARCH_PROFILE_TOOLS = /* @__PURE__ */ new Set([
@@ -2304,6 +2490,20 @@ async function runWithCredentialRecovery(run, requestId, session) {
     return await run();
   } catch (error2) {
     if (session?.authType !== "api-key" || !isCoreCredentialRejection(error2)) {
+      const hints = readErrorAgentHints(error2);
+      if (hints) {
+        const message = error2 instanceof Error ? error2.message : String(error2);
+        throw new UserError2(
+          hints.length ? `${message}
+
+${agentHintsText(hints)}` : message,
+          {
+            ...error2 instanceof UserError2 ? error2.extras : {},
+            error: message,
+            agent_hints: hints
+          }
+        );
+      }
       throw error2;
     }
     const payload = recoveryPayload("CREDENTIAL_INVALID", requestId);
@@ -2389,6 +2589,26 @@ function emitActionLog(toolName, status, session, error2, requestId = randomUUID
     signal: AbortSignal.timeout(1500)
   }).catch(() => void 0);
 }
+var AGENT_HINT_LOG_MAX_CHARS = 1e3;
+function emitAgentHintsLog(toolName, status, hints, session, requestId) {
+  if (process.env.CLOUD_SERVICE !== "true" || !hints) return;
+  console.error(
+    "[MCP_AGENT_HINTS]",
+    JSON.stringify({
+      tool_name: toolName,
+      status,
+      request_id: requestId,
+      auth_type: session.authType ?? "none",
+      // The companion search server shares this process and wrapper.
+      profile: session.profile ?? primaryProfile.id,
+      hint_count: hints.length,
+      hints: hints.map((hint) => hint.slice(0, AGENT_HINT_LOG_MAX_CHARS))
+    })
+  );
+}
+function resultAgentHints(result) {
+  return result && typeof result === "object" ? readAgentHints(result.structuredContent) : void 0;
+}
 function guardHostedTool(tool, { logActions }) {
   const keylessTool = KEYLESS_TOOL_NAMES.has(tool.name);
   const execute = tool.execute;
@@ -2458,11 +2678,26 @@ function guardHostedTool(tool, { logActions }) {
         if (logActions) emitActionLog(tool.name, "error", invocationSession, new UserError2(String(payload.message), payload), requestId, code);
         throw new UserError2(String(payload.message), payload);
       }
-      const runTool = () => runWithCredentialRecovery(
-        () => execute(args2, invocationContext),
-        requestId,
-        invocationSession
-      );
+      const runTool = async () => {
+        try {
+          const result = await runWithCredentialRecovery(
+            () => execute(args2, invocationContext),
+            requestId,
+            invocationSession
+          );
+          emitAgentHintsLog(
+            tool.name,
+            result?.isError ? "error" : "success",
+            resultAgentHints(result),
+            invocationSession,
+            requestId
+          );
+          return result;
+        } catch (error2) {
+          emitAgentHintsLog(tool.name, "error", readErrorAgentHints(error2), invocationSession, requestId);
+          throw error2;
+        }
+      };
       if (!logActions) return runTool();
       emitActionLog(tool.name, "started", invocationSession, void 0, requestId);
       try {
@@ -2517,6 +2752,7 @@ server.getApp().get("/ready", (context) => {
   }
   return missing.length ? context.json({ ok: false, missing }, 503) : context.json({ ok: true }, 200);
 });
+var warnedMissingAgentHintsInterceptor = false;
 function createClient(apiKey) {
   const config = {
     ...process.env.FIRECRAWL_API_URL && {
@@ -2526,7 +2762,44 @@ function createClient(apiKey) {
   if (apiKey) {
     config.apiKey = apiKey;
   }
-  return new FirecrawlApp(config);
+  const client = new FirecrawlApp(config);
+  const axiosInstance = client.http?.instance;
+  if (axiosInstance?.interceptors?.request?.use) {
+    axiosInstance.interceptors.request.use((request) => {
+      if (typeof request.headers?.set === "function") {
+        request.headers.set("X-Firecrawl-Agent-Hints", "true");
+      } else {
+        request.headers = { ...request.headers ?? {}, ...AGENT_HINTS_HEADERS };
+      }
+      return request;
+    });
+  } else if (!warnedMissingAgentHintsInterceptor) {
+    warnedMissingAgentHintsInterceptor = true;
+    console.warn(
+      "[firecrawl-mcp] SDK request interceptor unavailable; API agent hints may be absent."
+    );
+  }
+  return client;
+}
+async function sdkResultWithAgentHints(client, execute) {
+  const responseInterceptors = client.http?.instance?.interceptors?.response;
+  if (!responseInterceptors?.use) return execute();
+  let hints;
+  const interceptor = responseInterceptors.use((response) => {
+    hints = readAgentHints(response?.data) ?? hints;
+    return response;
+  });
+  try {
+    const result = await execute();
+    return preserveAgentHints(result, { agent_hints: hints });
+  } catch (error2) {
+    if (hints && error2 && typeof error2 === "object" && !readErrorAgentHints(error2)) {
+      error2.agent_hints = hints;
+    }
+    throw error2;
+  } finally {
+    responseInterceptors.eject?.(interceptor);
+  }
 }
 var SAFE_MODE = process.env.CLOUD_SERVICE === "true";
 function getClient(session) {
@@ -2555,10 +2828,14 @@ function getClient(session) {
         reason: "delegated_credential_unavailable"
       });
     }
-    config.headers = {
-      ...config.headers ?? {},
-      Authorization: `Bearer ${credential}`
-    };
+    if (typeof config.headers?.set === "function") {
+      config.headers.set("Authorization", `Bearer ${credential}`);
+    } else {
+      config.headers = {
+        ...config.headers ?? {},
+        Authorization: `Bearer ${credential}`
+      };
+    }
     return config;
   });
   return client;
@@ -2706,10 +2983,10 @@ var scrapeToolParamsSchema = scrapeParamsSchema.extend({
   url: z8.string().url().optional(),
   timeout: z8.number().int().positive().optional().describe("Execution timeout in milliseconds."),
   requestId: z8.string().regex(/^[A-Za-z0-9._:-]{1,128}$/).optional().describe(
-    "Identifies one logical Alexandria execution; generated when omitted and returned with the result. Repeated attempts of the identical payload require the same ID. A new ID cannot reconcile a pending or uncertain execution. A caller-supplied ID supports recovery if no response is received. Errors relay a code and may include chargeId. request_in_flight (409) means the execution is pending; request_unresolved (503) requires reconciliation under the same ID; duplicate_request (409) means the ID belongs to a different payload; unknown_provider (404), insufficient_credits (402) and billing_unavailable (503) mean nothing executed."
+    "Idempotency key bound to one Alexandria execution payload. Generated when omitted and returned with the result."
   ),
   alexandria: z8.union([exchangeCallSchema, exchangeCallsSchema]).optional().describe(
-    "Catalogued Alexandria capability invocation, mutually exclusive with url. One {provider, capability, options} object or an array of 1-10, with contracts available through firecrawl_search or firecrawl_find_tools. Each call may include version to pin a published workflow; omitting it uses latest. Only requestId and timeout are supported alongside alexandria. " + ALEXANDRIA_CONTRACT_GUIDANCE + " Returns per-capability results in data.alexandria with data, records, or an error with a code; individual capabilities can fail even when the outer response succeeds. nextTool identifies access to retained results without repeating a successful provider call. Requires an API key on a team with Alexandria enabled. THIRD_PARTY_DATA_TERMS_REQUIRED (403) means execution is blocked by provider terms, with requiresAction.url for review by an organization admin. Through this tool, terms/show displays the agreement and terms/accept records acceptance; acceptance requires explicit user authorization for the reviewed version and digest and confirmed:true. A data request does not authorize acceptance. Provider execution remains blocked until acceptance is confirmed."
+    "Catalogued Alexandria capability invocation, mutually exclusive with url. One {provider, capability, options} object or an array of 1-10, with contracts available through firecrawl_search or firecrawl_find_tools. Each call may include version to pin a published workflow; omitting it uses latest. Only requestId and timeout are supported alongside alexandria. " + ALEXANDRIA_CONTRACT_GUIDANCE + " Returns per-capability results in data.alexandria with data, records, or an error with a code; individual capabilities can fail even when the outer response succeeds. Requires an API key on a team with Alexandria enabled. Some providers require accepted terms; blocked requests return the applicable requirements."
   ),
   toolDetail: z8.enum(["compact", "summary", "full"]).optional().describe("URL mode only: domain discovery detail, summary by default; compact returns provider/capability/description, full includes contracts. Ignored with alexandria."),
   domainTools: z8.boolean().optional().describe(
@@ -2846,6 +3123,7 @@ async function apiPostJson(pathName, body, apiKey, origin) {
   const response = await fetch(`${resolveApiBaseUrl()}${pathName}`, {
     method: "POST",
     headers: {
+      ...AGENT_HINTS_HEADERS,
       "Content-Type": "application/json",
       Authorization: `Bearer ${apiKey}`,
       ...origin ? originHeaders(origin) : {}
@@ -2862,7 +3140,8 @@ async function apiPostJson(pathName, body, apiKey, origin) {
   if (!response.ok) {
     throw new CoreHttpError(
       parsed?.error || parsed?.message || `Firecrawl request failed (HTTP ${response.status})`,
-      response.status
+      response.status,
+      readAgentHints(parsed)
     );
   }
   return parsed;
@@ -2944,6 +3223,7 @@ async function executeHostedParse(args2, session, log, origin) {
       session,
       origin
     );
+    const uploadHints = readAgentHints(uploadJson);
     const upload = parseApiData(uploadJson);
     if (!upload?.uploadUrl || !upload?.uploadRef) {
       throw new Error(
@@ -2954,6 +3234,7 @@ async function executeHostedParse(args2, session, log, origin) {
     const uploadForCommand = { ...upload, headers: uploadHeaders };
     return asText({
       success: true,
+      ...uploadHints ? { agent_hints: uploadHints } : {},
       mode: "hosted-upload-ref-awaiting-upload",
       message: "Hosted MCP cannot read local files. Run the local upload command, then call firecrawl_parse again with uploadRef. No Firecrawl API key is included in this command.",
       upload: {
@@ -3008,7 +3289,7 @@ Firecrawl may serve recently indexed content; set \`maxAge: 0\` for a live fetch
 
 On an authenticated session with Alexandria access, \`firecrawl_search\` with \`sources\` unset and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching provider returns typed records in one call. Keyless sessions have no provider matches.
 
-Alexandria mode, on an authenticated session with Alexandria access: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`; the \`alexandria\` and \`requestId\` parameters describe batching, retries, errors and provider terms.
+Alexandria mode, on an authenticated session with Alexandria access: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`.
 `,
   outputSchema: scrapeOutputSchema,
   parameters: scrapeToolParamsSchema,
@@ -3048,14 +3329,17 @@ Alexandria mode, on an authenticated session with Alexandria access: \`alexandri
         },
         session
       );
-      return structuredText(json?.data ?? json);
+      return structuredText(preserveAgentHints(json?.data ?? json, json));
     }
     const client = getClient(session);
     const res = await relayTermsRequired(
-      () => client.scrape(String(url), {
-        ...cleaned,
-        origin
-      }),
+      () => sdkResultWithAgentHints(
+        client,
+        () => client.scrape(String(url), {
+          ...cleaned,
+          origin
+        })
+      ),
       { tool: "firecrawl_scrape" }
     );
     return structuredText(res);
@@ -3095,10 +3379,13 @@ Returns matching URLs rather than page bodies. Retrieve one page with \`firecraw
     const client = getClient(session);
     const cleaned = removeEmptyTopLevel(options);
     log.info("Mapping URL", { url: String(url) });
-    const res = await client.map(String(url), {
-      ...cleaned,
-      origin: requestOrigin(mcpClient, session)
-    });
+    const res = await sdkResultWithAgentHints(
+      client,
+      () => client.map(String(url), {
+        ...cleaned,
+        origin: requestOrigin(mcpClient, session)
+      })
+    );
     return structuredText(res);
   }
 });
@@ -3267,7 +3554,7 @@ Scrape one URL and return its content, or execute catalogued Alexandria capabili
 
 \`firecrawl_search\` with \`sources\` unset and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching Alexandria provider returns typed records in one call.
 
-Alexandria mode: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`; the \`alexandria\` and \`requestId\` parameters describe batching, retries, errors and provider terms. Alexandria execution is billed at the capability's listed price and needs a team with Alexandria enabled.
+Alexandria mode: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`. Alexandria execution is billed at the capability's listed price and needs a team with Alexandria enabled.
 `;
 var searchSurfaceScrapeTool = {
   ...scrapeTool,
@@ -3340,6 +3627,7 @@ async function keylessPost(path2, body, session, originOverride) {
     }
   }
   const headers = {
+    ...AGENT_HINTS_HEADERS,
     ...originHeaders(origin),
     "Content-Type": "application/json"
   };
@@ -3359,10 +3647,14 @@ async function keylessPost(path2, body, session, originOverride) {
       const payload = recoveryPayload(code, session?.requestId, {
         retryAfterSeconds: Number.isFinite(json?.retry_after_seconds) && json.retry_after_seconds > 0 ? json.retry_after_seconds : void 0
       });
+      const hints = readAgentHints(json);
+      if (hints) payload.agent_hints = hints;
       throw new UserError2(String(payload.message), payload);
     }
-    throw new Error(
-      json?.error || `Firecrawl request failed (HTTP ${response.status})`
+    throw new CoreHttpError(
+      json?.error || `Firecrawl request failed (HTTP ${response.status})`,
+      response.status,
+      readAgentHints(json)
     );
   }
   return json;
@@ -3383,7 +3675,8 @@ async function getCrawlStatusWithOrigin(client, jobId, origin) {
       creditsUsed: body.creditsUsed,
       expiresAt: body.expiresAt,
       next: body.next ?? null,
-      data: initialDocs
+      data: initialDocs,
+      ...readAgentHints(body) ? { agent_hints: readAgentHints(body) } : {}
     };
   }
   const docs = initialDocs.slice();
@@ -3407,7 +3700,8 @@ async function getCrawlStatusWithOrigin(client, jobId, origin) {
     creditsUsed: body.creditsUsed,
     expiresAt: body.expiresAt,
     next: null,
-    data: docs
+    data: docs,
+    ...readAgentHints(body) ? { agent_hints: readAgentHints(body) } : {}
   };
 }
 async function waitForCrawlCompletionWithOrigin(client, jobId, origin, pollInterval = 2, timeout) {
@@ -3518,6 +3812,7 @@ Eligibility is limited to successful searches within the feedback age window. Th
       }
       if (querySuggestions) body.querySuggestions = querySuggestions;
       const headers = {
+        ...AGENT_HINTS_HEADERS,
         ...originHeaders(origin),
         "Content-Type": "application/json"
       };
@@ -3556,7 +3851,8 @@ Eligibility is limited to successful searches within the feedback age window. Th
           status: response.status,
           feedbackErrorCode: parsed?.feedbackErrorCode,
           error: parsed?.error ?? `HTTP ${response.status}`,
-          retryable: response.status >= 500
+          retryable: response.status >= 500,
+          ...readAgentHints(parsed) ? { agent_hints: readAgentHints(parsed) } : {}
         });
       }
       return structuredText(parsed);
@@ -3638,6 +3934,7 @@ Returns submission status, feedback ID, and accounting fields.
       } = args2;
       const apiBase = resolveApiBaseUrl();
       const headers = {
+        ...AGENT_HINTS_HEADERS,
         ...originHeaders(origin),
         "Content-Type": "application/json"
       };
@@ -3691,7 +3988,8 @@ Returns submission status, feedback ID, and accounting fields.
           status: response.status,
           feedbackErrorCode: parsed?.feedbackErrorCode,
           error: parsed?.error ?? `HTTP ${response.status}`,
-          retryable: response.status >= 500
+          retryable: response.status >= 500,
+          ...readAgentHints(parsed) ? { agent_hints: readAgentHints(parsed) } : {}
         });
       }
       return structuredText(parsed);
@@ -3838,6 +4136,29 @@ Deprecated compatibility entry point. Use firecrawl_scrape once per known URL wi
     throw new UserError2(payload.message, payload);
   }
 });
+var agentExchangeSchema = z8.strictObject({
+  enabled: z8.boolean().optional().describe("Let the agent call Alexandria providers. On by default."),
+  toolkits: z8.array(z8.string()).max(5).optional().describe("Pin up to 5 providers the agent may use, by slug. Omitted means the whole catalog."),
+  maxCalls: z8.number().int().min(1).max(30).optional().describe("Most provider calls the agent may make in this turn."),
+  requireApproval: z8.boolean().optional().describe(
+    'End the turn with a paid-call pendingApproval before any paid provider call. Requires mode "chat" on the same request, even on a follow-up.'
+  ),
+  approve: z8.strictObject({
+    approvalId: z8.string().uuid(),
+    callIds: z8.array(z8.string()).optional(),
+    always: z8.boolean().optional()
+  }).optional().describe(
+    "Answer yes to the pendingApproval the previous turn of this thread ended on (its id, also exchange.requiresAction.approvalId). Needs threadId. For a terms offer, send it only after the user explicitly agreed and terms/accept succeeded; callIds and always are ignored on terms offers. For paid calls, callIds picks a subset (default all) and always stops asking for the rest of the thread."
+  ),
+  decline: z8.strictObject({ approvalId: z8.string().uuid() }).optional().describe(
+    "Answer no to that pendingApproval. Needs threadId. A declined terms offer keeps those providers out of the rest of the thread."
+  ),
+  onTermsRequired: z8.enum(["skip", "ask"]).optional().describe(
+    `What to do when a provider the agent would use needs data terms the team has not accepted. Gated providers are never called. "skip" (default): answer with accepted providers and list the rest in exchange.skippedProviders. "ask": the same, plus a terms pendingApproval and exchange.requiresAction with the terms/show and terms/accept calls. Each provider digest is string | null and always present; when null, terms/show returns it. There is no auto-accept. Omitted on a follow-up keeps the previous turn's value.`
+  )
+}).describe(
+  "Alexandria provider settings for this turn, forwarded as the request's exchange object."
+);
 server.addTool({
   name: "firecrawl_agent",
   annotations: {
@@ -3850,27 +4171,74 @@ server.addTool({
     // Gathers information only; does not delete external data or user resources.
   },
   description: `
-Run web research that returns structured data when the URLs are not known or the answer spans several sites. Describe the fields you need in \`prompt\`, optionally pass a JSON \`schema\` and seed \`urls\`, and the research agent searches, navigates, reads pages, and returns JSON assembled across sources. Use it to research an entity plus its fields (founders, pricing, contact details), to build lists and datasets (companies, people, products, jobs, papers), and for pages that need navigation or interaction to reach the data.
+Run web research that returns structured data when the URLs are not known or the answer spans several sites. Describe the fields you need in \`prompt\`, optionally pass a JSON \`schema\` and seed \`urls\`, and the research agent searches, navigates, reads pages, and returns JSON assembled across sources. Use it to research an entity plus its fields (founders, pricing, contact details), to build lists and datasets (companies, people, products, jobs, papers), and for pages that need navigation or interaction to reach the data. Optional \`effort\` sets the reasoning budget, \`maxCredits\` caps spend, and \`strictConstrainToURLs\` keeps the agent to the supplied \`urls\`.
 
 This call returns only a job ID, not the research result. Read the job with \`firecrawl_agent_status\` until it reaches \`completed\` or \`failed\`; a typical research run takes one to three minutes. For one known URL use \`firecrawl_scrape\` (with formats: ["json"] for structured output); for a plain lookup that a results page answers, use \`firecrawl_search\`.
+
+The job also returns a \`threadId\`. To continue that thread, pass it with a follow-up \`prompt\`; omitted \`mode\`, \`urls\`, \`schema\` and exchange settings carry over from the previous turn.
+
+The agent only calls Alexandria providers whose data terms the team has accepted. The status result's \`exchange.skippedProviders\` lists gated providers that would have helped. With \`exchange.onTermsRequired\` "ask", a terms offer ends the turn: \`pendingApproval\` (kind "terms") and \`exchange.requiresAction\` carry the \`approvalId\` and the exact terms/show and terms/accept calls. Show the user the terms, get their EXPLICIT consent, run terms/accept through \`firecrawl_scrape\`, then call \`firecrawl_agent\` with the same \`threadId\` and \`exchange.approve: {approvalId}\`. If they decline, send \`exchange.decline: {approvalId}\` instead. Never call terms/accept without that consent; a data request is not consent.
 `,
   outputSchema: agentOutputSchema,
   parameters: z8.object({
     prompt: z8.string().min(1).max(1e4),
     urls: z8.array(z8.string().url()).optional(),
-    schema: z8.record(z8.string(), z8.any()).optional()
-  }),
+    schema: z8.record(z8.string(), z8.any()).optional(),
+    effort: z8.enum(["low", "medium", "high"]).optional().describe("Reasoning budget for the agent task."),
+    maxCredits: z8.number().int().positive().optional().describe(
+      "Spending limit in credits for this run. Defaults to 2500 on the API."
+    ),
+    strictConstrainToURLs: z8.boolean().optional().describe(
+      "If true, agent will only visit URLs provided in the urls array."
+    ),
+    threadId: z8.string().uuid().optional().describe(
+      "Continue this thread: the threadId from an earlier firecrawl_agent or firecrawl_agent_status result. Omit to start a new thread."
+    ),
+    mode: z8.enum(["extract", "chat"]).optional().describe(
+      `"extract" (default) returns the complete structured result every turn. "chat" lets a follow-up that asks no new data get a short reply in message instead of a re-run; required for exchange.requireApproval. Omitted on a follow-up keeps the previous turn's mode.`
+    ),
+    exchange: agentExchangeSchema.optional()
+  }).refine(
+    (data) => !(data.exchange?.approve && data.exchange?.decline),
+    {
+      message: "Send exchange.approve or exchange.decline, not both: each answers the pending approval one way.",
+      path: ["exchange"]
+    }
+  ).refine(
+    (data) => !(data.exchange?.approve || data.exchange?.decline) || Boolean(data.threadId),
+    {
+      message: "exchange.approve and exchange.decline answer a pending approval on an existing thread: pass that thread's threadId.",
+      path: ["threadId"]
+    }
+  ).refine(
+    (data) => !data.exchange?.requireApproval || data.mode === "chat",
+    {
+      // The agent service checks the mode sent on this request, not the
+      // thread's inherited one, and the gateway turns its 400 into a 500.
+      message: 'exchange.requireApproval needs mode: "chat" on the same request, including on a follow-up.',
+      path: ["mode"]
+    }
+  ),
   execute: async (args2, { session, log, client: mcpClient }) => {
     const client = getClient(session);
     const a = args2;
     log.info("Starting agent", {
       prompt: a.prompt.substring(0, 100),
-      urlCount: Array.isArray(a.urls) ? a.urls.length : 0
+      urlCount: Array.isArray(a.urls) ? a.urls.length : 0,
+      threadId: a.threadId ?? null
     });
     const agentBody = removeEmptyTopLevel({
       prompt: a.prompt,
       urls: a.urls,
-      schema: a.schema || void 0
+      schema: a.schema || void 0,
+      effort: a.effort,
+      maxCredits: a.maxCredits,
+      strictConstrainToURLs: a.strictConstrainToURLs,
+      threadId: a.threadId,
+      mode: a.mode,
+      // Forwarded verbatim: the agent service owns the defaults and the
+      // per-thread inheritance.
+      exchange: a.exchange
     });
     const res = await client.startAgent({
       ...agentBody,
@@ -4076,7 +4444,10 @@ Set \`redactPII\` to request redaction of personally identifiable information in
     });
     form.append("file", blob, filename);
     form.append("options", JSON.stringify(optionsPayload));
-    const headers = { ...originHeaders(origin) };
+    const headers = {
+      ...AGENT_HINTS_HEADERS,
+      ...originHeaders(origin)
+    };
     const credential = credentialForOutboundRequest(session);
     if (credential) {
       headers["Authorization"] = `Bearer ${credential}`;
@@ -4094,8 +4465,15 @@ Set \`redactPII\` to request redaction of personally identifiable information in
     });
     const responseText = await response.text();
     if (!response.ok) {
-      throw new Error(
-        `Parse request failed with status ${response.status}: ${responseText}`
+      let parsed;
+      try {
+        parsed = JSON.parse(responseText);
+      } catch {
+      }
+      throw new CoreHttpError(
+        `Parse request failed with status ${response.status}: ${responseText}`,
+        response.status,
+        readAgentHints(parsed)
       );
     }
     try {