firecrawl-mcp 3.25.4 → 3.26.0

package/dist/index.js

@@ -45,10 +45,9 @@ var alexandriaFeedbackFields = {
     )
   ).max(20).optional()
 };
-var ALEXANDRIA_FEEDBACK_GUIDANCE = 'After an Alexandria task, whether a capability ran or discovery found nothing for the website, call firecrawl_feedback once per website with endpoint "alexandria": requestedWebsite (the url the user needed data from and the requestedFunctionality they needed), a rating, a rationale from observed results, and any providerFeedback or capabilityFeedback gaps. It is free, needs no job ID, has no deadline, and follows the answer rather than replacing it.';
 var ALEXANDRIA_FEEDBACK_HINT = {
   name: "firecrawl_feedback",
-  when: "Once per website after the task is complete, including when no provider covered the site. Free; no job ID or deadline.",
+  when: "Optional after task completion; at most once per website, including uncovered sites. Free; no job ID or deadline.",
   arguments: {
     endpoint: "alexandria",
     rating: "<good | partial | bad>",
@@ -86,14 +85,367 @@ import { readFile } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
 import { randomUUID } from "crypto";
 import path from "path";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
-// src/alexandria.ts
+// 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) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function withStructured(text, data) {
+  return isRecord(data) ? { content: [{ type: "text", text }], structuredContent: data } : { content: [{ type: "text", text }] };
+}
+function structuredText(data) {
+  return withStructured(JSON.stringify(data, null, 2), data);
+}
+function structuredCompact(data) {
+  return withStructured(JSON.stringify(data), data);
+}
+function structuredJsonText(text) {
+  try {
+    return withStructured(text, JSON.parse(text));
+  } catch {
+    return { content: [{ type: "text", text }] };
+  }
+}
+var str = (description) => z2.string().nullable().optional().describe(description);
+var num = (description) => z2.number().nullable().optional().describe(description);
+var bool = (description) => z2.boolean().nullable().optional().describe(description);
+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 Alexandria execution."),
+  scrape_id: str("Identifier of the underlying scrape."),
+  receipt: unknown("Billing receipt for the execution."),
+  creditsCost: num("Credits this call consumed."),
+  delivery: str("`retained` when the full result stayed server-side instead of being inlined."),
+  responseBytes: num("Size of the full result in bytes."),
+  estimatedTokens: num("Estimated token cost of the full result."),
+  tokenEstimateMethod: str("How `estimatedTokens` was derived."),
+  inlineTokenBudget: num("Token budget above which a result is retained rather than inlined."),
+  workspaceId: str("Workspace holding a retained result, for inspection through virtual Bash."),
+  idleTtlSeconds: num("Seconds a retained workspace stays available while idle."),
+  message: str("Guidance that accompanies the result."),
+  nextTool: unknown("A follow-up tool call (`{name, arguments}`) that continues or inspects this result."),
+  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."),
+  rawHtml: str("Unprocessed HTML of the page."),
+  summary: str("Summary of the page content."),
+  links: unknown("Links found on the page."),
+  screenshot: unknown("Screenshot of the page."),
+  images: unknown("Images found on the page."),
+  audio: unknown("Audio extracted from the page."),
+  video: unknown("Video extracted from the page."),
+  answer: str("Targeted answer to the question that was asked of the page."),
+  highlights: unknown("Highlighted passages from the page."),
+  pages: unknown("Physical PDF pages, when `parsers[].pages` is set."),
+  blocks: unknown("Typed PDF layout blocks, when `parsers[].blocks` is set."),
+  product: unknown("Product data extracted from the page."),
+  menu: unknown("Menu data extracted from the page."),
+  json: unknown("Structured data matching the requested JSON schema or prompt."),
+  attributes: unknown("Values collected by the requested attribute selectors."),
+  actions: unknown("Results of the browser actions that ran during the scrape."),
+  changeTracking: unknown("Change-tracking comparison against the previous scrape."),
+  branding: unknown("Branding data extracted from the page."),
+  metadata: unknown("Page metadata; authenticated responses can include `metadata.scrapeId` for scrape feedback."),
+  tools: unknown("Domain-matched Alexandria tools for the page, when `domainTools` is set."),
+  warning,
+  // Alexandria mode and error envelopes.
+  success,
+  error,
+  data: unknown("Alexandria mode: per-capability results in `data.alexandria`, each with `data`, `records`, or an `error`."),
+  ...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,
+  warning,
+  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,
+  warning,
+  id: str("Search identifier, for optional `firecrawl_search_feedback`."),
+  creditsUsed: num("Credits this search consumed."),
+  tools: unknown("Domain-matched Alexandria tools for the results."),
+  nextTool: unknown("A follow-up tool call that continues this search."),
+  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."),
+  feedbackErrorCode: str("Machine-readable reason the submission was rejected."),
+  retryable: bool("Whether retrying the submission can succeed."),
+  message: str("Human-readable result of the submission."),
+  feedbackId: str("Identifier of the recorded feedback."),
+  creditsRefunded: num("Credits refunded for this submission, when eligible."),
+  creditsRefundedToday: num("Credits refunded to the team so far this UTC day."),
+  dailyRefundCap: num("The team's daily refund cap in credits."),
+  dailyCapReached: bool("Whether the daily refund cap is reached; further feedback today still records but refunds nothing."),
+  alreadySubmitted: bool("Whether feedback for this job was already recorded."),
+  warning,
+  data: unknown("Payload returned with the accepted feedback."),
+  raw: str("Response body when it was not JSON.")
+}).describe("Result of submitting feedback.");
+var crawlOutputSchema = z2.object({
+  ...agentHints,
+  success,
+  error,
+  warning,
+  id: str("Crawl identifier, for `firecrawl_check_crawl_status`."),
+  status: str("Crawl state, such as `scraping`, `completed`, or `failed`."),
+  completed: num("Pages crawled so far."),
+  total: num("Pages the crawl expects to visit."),
+  creditsUsed: num("Credits the crawl consumed."),
+  expiresAt: str("When the crawl results expire."),
+  next: str("URL of the next page of results, when the data is paginated."),
+  url: str("The URL the crawl started from."),
+  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`."),
+  status: str("Job state at submission time."),
+  threadId: str("Research thread this job belongs to."),
+  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."),
+  status: str("Job state: `processing` is non-terminal; `completed` and `failed` are terminal."),
+  progress: unknown("Progress information for a running job."),
+  data: unknown("Research result, present once the job has completed."),
+  creditsUsed: num("Credits the job consumed."),
+  sources: unknown("Sources the agent read."),
+  expiresAt: str("When the job result expires and can no longer be read."),
+  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."),
+  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."),
+  scrapeId: str("Session identifier; pass it to reuse the session or to `firecrawl_interact_stop`."),
+  result: unknown("Interaction result, when it is not an object of its own."),
+  output: unknown("Execution output."),
+  stdout: str("Standard output of the executed code."),
+  stderr: str("Standard error of the executed code."),
+  exitCode: num("Exit status of the executed code."),
+  data: unknown("Payload returned by the interaction."),
+  sessionUrl: str("URL for viewing the live session."),
+  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,
+  mode: str("Which phase of the hosted flow produced this response."),
+  message: str("Guidance for the next call."),
+  data: unknown("Parsed document content; can include `data.metadata.scrapeId` for parse feedback."),
+  upload: z2.object({
+    command: str("Local command that performs the upload. It carries no Firecrawl API key."),
+    method: str("HTTP method for the upload."),
+    headers: unknown("Headers the upload request must send."),
+    fields: unknown("Form fields the upload request must send, for a POST upload."),
+    uploadUrl: str("URL to upload the local file to."),
+    uploadRef: str("Reference to pass back on the second call."),
+    expiresAt: str("When the upload URL expires."),
+    maxSizeBytes: num("Largest file the upload URL accepts.")
+  }).optional().describe("Hosted phase one: how to upload the local file."),
+  nextToolCall: unknown("Hosted phase one: the second `firecrawl_parse` call to make once the upload succeeds, as `{name, arguments}`."),
+  notes: z2.array(z2.string()).nullable().optional().describe("Hosted phase one: constraints on completing the upload flow."),
+  raw: str("Response body when it was not JSON.")
+}).describe("Parsed document content, or the upload instructions for the hosted two-call flow.");
+var deprecatedToolOutputSchema = z2.object({
+  code: str("Always `DEPRECATED_TOOL`."),
+  message: str("Why the tool is unavailable and what to call instead."),
+  replacement: unknown("The replacement tool, with instructions and example arguments."),
+  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."),
+  pagination: unknown("Pagination metadata for the page results."),
+  next: str("URL of the next page of results, when more exist.")
+}).describe("One monitor check with its page-level diff results.");
+var paperSchema = z2.looseObject({
+  paperId: str("Canonical paper identifier."),
+  primaryId: str("Display identifier, ordered for citation and fetch use."),
+  ids: unknown("Source identifiers by namespace, such as `arxiv`, `doi`, or `pmid`."),
+  title: str("Paper title."),
+  abstract: str("Paper abstract."),
+  authors: unknown("Authors, as a comma-joined string or as `{name, affiliation}` entries."),
+  categories: z2.array(z2.string()).nullable().optional().describe("Paper categories, such as `cs.LG`."),
+  createdDate: str("Date the paper was first indexed or published."),
+  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."),
+      url: str("Source URL."),
+      title: str("Result title."),
+      passages: z2.array(z2.looseObject({ text: str("Matched passage, in markdown.") })).optional().describe("Matched passages.")
+    })
+  ).describe("Ranked results, in the order the text block lists them.")
+}).describe("Ranked developer-index results with their matched passages.");
+var creditUsageOutputSchema = z2.object({
+  // Current view.
+  remainingCredits: num("Credits left in the current billing period; can exceed `planCredits` when extra credits were purchased or granted."),
+  planCredits: num("Credits included in the plan for the period."),
+  billingPeriodStart: str("Start of the current billing period; null when the billing provider reports no period."),
+  billingPeriodEnd: str("End of the current billing period; null when the billing provider reports no period."),
+  // Historical view.
+  success,
+  error,
+  periods: unknown("Historical periods sorted by start date, each with `startDate`, `endDate`, `creditsUsed`, and `apiKey` when broken down by key.")
+}).describe("The team credit balance, or historical credit consumption by period.");
+
+// src/alexandria.ts
+import { z as z3 } from "zod";
 var catalogueTypes = ["alexandria", "exchange"];
-var searchSourceSchema = z2.union([
-  z2.enum(["web", "images", "news", ...catalogueTypes]),
-  z2.object({ type: z2.enum(["web", "images", "news", ...catalogueTypes]) }).strict()
+var searchSourceSchema = z3.union([
+  z3.enum(["web", "images", "news", ...catalogueTypes]),
+  z3.object({ type: z3.enum(["web", "images", "news", ...catalogueTypes]) }).strict()
 ]);
 function hasAlexandria(sources) {
   return Array.isArray(sources) && sources.some(
@@ -116,25 +468,25 @@ function normalizeSearchSources(sources) {
 function searchQueryIsValid(args2) {
   return !!args2.query?.trim();
 }
-var findToolsSchema = z2.object({
-  query: z2.string().trim().min(1).max(2e3).optional().describe("Semantic lookup of tools for the data you need. Selectors constrain the search."),
-  urls: z2.array(
-    z2.string().url().regex(/^https?:\/\//)
+var findToolsSchema = z3.object({
+  query: z3.string().trim().min(1).max(2e3).optional().describe("Semantic lookup of tools for the data you need. Selectors constrain the search."),
+  urls: z3.array(
+    z3.string().url().regex(/^https?:\/\//)
   ).min(1).max(100).optional(),
-  providers: z2.array(z2.string().min(1)).min(1).max(50).optional().describe("Provider IDs returned by category browsing. Lists compact tools by default."),
-  categories: z2.array(z2.string().min(1)).min(1).max(50).optional().describe("Category IDs returned by an empty call. Lists providers by default."),
-  groups: z2.array(z2.string().min(1)).min(1).max(50).optional().describe("Optional group IDs for explicit group browsing."),
-  capabilities: z2.array(z2.string().min(1)).min(1).max(50).optional().describe("Exact capability IDs. A selected capability expands its complete contract by default."),
-  level: z2.enum(["categories", "providers", "groups", "tools"]).optional(),
-  expand: z2.array(z2.enum(["options", "response", "examples"])).optional().describe('Use ["options", "response"] for inputs and output shape without example payloads; [] keeps results compact. Omit for full contracts on selected capabilities.'),
-  limit: z2.number().int().min(1).max(100).optional(),
-  offset: z2.number().int().nonnegative().optional()
+  providers: z3.array(z3.string().min(1)).min(1).max(50).optional().describe("Provider IDs returned by category browsing. Lists compact tools by default."),
+  categories: z3.array(z3.string().min(1)).min(1).max(50).optional().describe("Category IDs returned by an empty call. Lists providers by default."),
+  groups: z3.array(z3.string().min(1)).min(1).max(50).optional().describe("Optional group IDs for explicit group browsing."),
+  capabilities: z3.array(z3.string().min(1)).min(1).max(50).optional().describe("Exact capability IDs. A selected capability expands its complete contract by default."),
+  level: z3.enum(["categories", "providers", "groups", "tools"]).optional(),
+  expand: z3.array(z3.enum(["options", "response", "examples"])).optional().describe('Use ["options", "response"] for inputs and output shape without example payloads; [] keeps results compact. Omit for full contracts on selected capabilities.'),
+  limit: z3.number().int().min(1).max(100).optional(),
+  offset: z3.number().int().nonnegative().optional()
 }).strict();
 var ALEXANDRIA_CATALOGUE_VERTICALS = "companies, people, jobs, finance and filings, public records and government spending, real estate, places and restaurants, retail and prices, package registries and developer data, news, research, and more";
 var ALEXANDRIA_CATALOGUE_SENTENCE = "Alexandria is Firecrawl's catalogue of data providers and workflows across " + ALEXANDRIA_CATALOGUE_VERTICALS + "; providers return typed, sourced records through published contracts.";
-var ALEXANDRIA_SOURCES_OPT_OUT = 'Passing sources without alexandria in it (for example ["web"] or ["news"]) excludes Alexandria provider matches; omit sources unless you specifically need web-only or news-only results, or include "alexandria" alongside them.';
+var ALEXANDRIA_SOURCES_OPT_OUT = 'A search with sources: ["web"] omits semantic provider discovery; domainTools: true can still return website-matched tools. Web-only results use domainTools: false.';
 var ALEXANDRIA_SEARCH_LEAD = "Authenticated search also returns matching Alexandria data providers in data.tools (" + ALEXANDRIA_CATALOGUE_VERTICALS + "). Prefer a provider over scraping pages when the task needs the same fields across several entities, exact figures or timestamps, provenance, or many records; use web results when they already answer the question. " + ALEXANDRIA_SOURCES_OPT_OUT;
-var ALEXANDRIA_CONTRACT_GUIDANCE = "Read the selected contract before executing: required inputs and requiresOneOf groups (at least one member per group), example.request/example.response when present, and response.key (do not assume records is the result key). Follow the declared pagination input and response cursor, preserving filters; catalogue next is separate from provider pagination.";
+var ALEXANDRIA_CONTRACT_GUIDANCE = "The selected contract marks required inputs and any requiresOneOf groups (at least one member per group); it may include example.request/example.response and response.key (which may differ from records). Where pagination is declared, its fields govern paging with the same filters; catalogue next is separate from provider pagination.";
 function findToolsOptions(args2) {
   const level = args2.level ?? (args2.query || args2.capabilities?.length || args2.providers?.length || args2.groups?.length || args2.urls?.length ? "tools" : args2.categories?.length ? "providers" : "categories");
   if (level === "categories" && (args2.query || args2.providers?.length || args2.categories?.length || args2.groups?.length || args2.capabilities?.length || args2.urls?.length || args2.expand !== void 0)) {
@@ -155,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);
@@ -164,7 +517,7 @@ function withFindToolsNavigation(envelope) {
   if (link(page.next)) page.nextTool = link(page.next);
   return envelope;
 }
-var ALEXANDRIA_SEARCH_INSTRUCTIONS = 'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only, or sources: ["web"] for web only. domainTools: false disables domain matching. Tool matches describe available structured-data capabilities, not executed data. toolDetail: "compact" (default) returns only provider, capability and description; "summary" adds metadata; "full" includes their input and output contracts. Execute a matched tool through firecrawl_scrape with an alexandria body; use firecrawl_find_tools to browse the catalogue or read a full contract.';
+var ALEXANDRIA_SEARCH_INSTRUCTIONS = 'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only. ' + ALEXANDRIA_SOURCES_OPT_OUT + ' Tool matches describe available structured-data capabilities, not executed data. toolDetail: "compact" (default) returns only provider, capability and description; "summary" adds metadata; "full" includes their input and output contracts. firecrawl_scrape with an alexandria body executes a selected capability; firecrawl_find_tools provides catalogue browsing and full contracts.';
 
 // src/alexandria-output.ts
 var INLINE_TOKEN_BUDGET = 2e4;
@@ -231,7 +584,7 @@ async function alexandriaOutput(payload, calls, post, recoveryRequestId, extras
 }
 
 // src/developer.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/origin.ts
 import { createRequire } from "module";
@@ -297,12 +650,13 @@ Search an index of public repositories, GitHub issues, merged pull requests, rep
 
 Returns ranked results with an ID, source type, URL, title, and the matched passages in markdown.
 `,
-    parameters: z3.object({
-      query: z3.string().min(1).describe(
+    outputSchema: developerSearchOutputSchema,
+    parameters: z4.object({
+      query: z4.string().min(1).describe(
         "Natural-language developer question or search phrase, including the library, error message, or API involved when relevant."
       ),
-      k: z3.number().int().min(1).max(100).optional().describe("Number of ranked results to return (default 10)."),
-      skills: z3.enum(["only"]).optional().describe('Set to "only" to search only agent-skill files.')
+      k: z4.number().int().min(1).max(100).optional().describe("Number of ranked results to return (default 10)."),
+      skills: z4.enum(["only"]).optional().describe('Set to "only" to search only agent-skill files.')
     }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { query, k, skills } = args2;
@@ -312,7 +666,8 @@ Returns ranked results with an ID, source type, URL, title, and the matched pass
       if (skills != null) params.append("skills", skills);
       const client = getClient2(session);
       const res = await client.http.get(`${BASE}?${params.toString()}`, originHeaders(requestOrigin(mcpClient, session)));
-      return fmtDeveloper(res.data?.results);
+      const results = res.data?.results ?? [];
+      return withAgentHints(withStructured(fmtDeveloper(results), { results }), res.data, true);
     }
   });
 }
@@ -332,17 +687,19 @@ function extractSingleTrustedClientIp(rawForwardedFor) {
 }
 
 // src/monitor.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/session-credential.ts
 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 {
@@ -354,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,
@@ -442,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, {
@@ -453,15 +814,15 @@ 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 asText(data) {
-  return JSON.stringify(data, null, 2);
+function monitorResult(data) {
+  return withAgentHints(structuredText(data), data);
 }
-var pageStatusSchema = z4.enum(["same", "new", "changed", "removed", "error"]);
-var checkStatusSchema = z4.enum([
+var pageStatusSchema = z5.enum(["same", "new", "changed", "removed", "error"]);
+var checkStatusSchema = z5.enum([
   "queued",
   "running",
   "completed",
@@ -554,22 +915,23 @@ Create a recurring scrape, crawl, or search monitor that compares each check wit
 
 In the simple form, a \`goal\` is required. If \`queries\` contains one or more non-empty values and is supplied with \`page\`/\`pages\`, \`queries\` create the search target and page targets are ignored. A monitor schedules future network checks and can send configured email or webhook notifications. Returns the created monitor.
 `,
-    parameters: z4.object({
-      body: z4.record(z4.string(), z4.any()).optional(),
-      page: z4.string().optional(),
-      pages: z4.array(z4.string()).optional(),
-      queries: z4.array(z4.string()).optional(),
-      searchWindow: z4.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
-      maxResults: z4.number().int().min(1).max(50).optional(),
-      includeDomains: z4.array(z4.string()).optional(),
-      excludeDomains: z4.array(z4.string()).optional(),
-      goal: z4.string().optional(),
-      name: z4.string().optional(),
-      scheduleText: z4.string().optional(),
-      timezone: z4.string().optional(),
-      email: z4.string().optional(),
-      includeDiffs: z4.boolean().optional(),
-      webhookUrl: z4.string().optional()
+    outputSchema: monitorOutputSchema,
+    parameters: z5.object({
+      body: z5.record(z5.string(), z5.any()).optional(),
+      page: z5.string().optional(),
+      pages: z5.array(z5.string()).optional(),
+      queries: z5.array(z5.string()).optional(),
+      searchWindow: z5.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
+      maxResults: z5.number().int().min(1).max(50).optional(),
+      includeDomains: z5.array(z5.string()).optional(),
+      excludeDomains: z5.array(z5.string()).optional(),
+      goal: z5.string().optional(),
+      name: z5.string().optional(),
+      scheduleText: z5.string().optional(),
+      timezone: z5.string().optional(),
+      email: z5.string().optional(),
+      includeDiffs: z5.boolean().optional(),
+      webhookUrl: z5.string().optional()
     }),
     execute: async (args2, { session, log, client: mcpClient }) => {
       const body = buildMonitorCreateBody(args2);
@@ -583,7 +945,7 @@ In the simple form, a \`goal\` is required. If \`queries\` contains one or more
           body
         }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -600,9 +962,10 @@ In the simple form, a \`goal\` is required. If \`queries\` contains one or more
     description: `
 List monitors for the authenticated account with optional pagination controls. Returns one page of monitor records and pagination metadata.
 `,
-    parameters: z4.object({
-      limit: z4.number().int().positive().optional(),
-      offset: z4.number().int().nonnegative().optional()
+    outputSchema: monitorListOutputSchema,
+    parameters: z5.object({
+      limit: z5.number().int().positive().optional(),
+      offset: z5.number().int().nonnegative().optional()
     }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { limit, offset } = args2;
@@ -614,7 +977,7 @@ List monitors for the authenticated account with optional pagination controls. R
           query: { limit, offset }
         }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -631,7 +994,8 @@ List monitors for the authenticated account with optional pagination controls. R
     description: `
 Retrieve one monitor by ID, including its configuration and current state. This does not run or modify the monitor.
 `,
-    parameters: z4.object({ id: z4.string() }),
+    outputSchema: monitorOutputSchema,
+    parameters: z5.object({ id: z5.string() }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { id } = args2;
       const res = await monitorRequest(
@@ -639,7 +1003,7 @@ Retrieve one monitor by ID, including its configuration and current state. This
         requestOrigin(mcpClient, session),
         `/monitor/${encodeURIComponent(id)}`
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -658,9 +1022,10 @@ Patch an existing monitor by ID. The body can change its name, active/paused sta
 
 Returns the updated monitor.
 `,
-    parameters: z4.object({
-      id: z4.string(),
-      body: z4.record(z4.string(), z4.any())
+    outputSchema: monitorOutputSchema,
+    parameters: z5.object({
+      id: z5.string(),
+      body: z5.record(z5.string(), z5.any())
     }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { id, body } = args2;
@@ -670,7 +1035,7 @@ Returns the updated monitor.
         `/monitor/${encodeURIComponent(id)}`,
         { method: "PATCH", body }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -687,7 +1052,8 @@ Returns the updated monitor.
     description: `
 Permanently delete a monitor by ID and stop its future schedule. This operation cannot be undone and returns deletion status.
 `,
-    parameters: z4.object({ id: z4.string() }),
+    outputSchema: monitorDeleteOutputSchema,
+    parameters: z5.object({ id: z5.string() }),
     execute: async (args2, { session, log, client: mcpClient }) => {
       const { id } = args2;
       log.info("Deleting monitor", { id });
@@ -697,7 +1063,7 @@ Permanently delete a monitor by ID and stop its future schedule. This operation
         `/monitor/${encodeURIComponent(id)}`,
         { method: "DELETE" }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -714,7 +1080,8 @@ Permanently delete a monitor by ID and stop its future schedule. This operation
     description: `
 Queue an immediate check for a monitor outside its normal schedule. This starts network work for the monitor's configured targets and returns the queued check.
 `,
-    parameters: z4.object({ id: z4.string() }),
+    outputSchema: monitorRunOutputSchema,
+    parameters: z5.object({ id: z5.string() }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { id } = args2;
       const res = await monitorRequest(
@@ -723,7 +1090,7 @@ Queue an immediate check for a monitor outside its normal schedule. This starts
         `/monitor/${encodeURIComponent(id)}/run`,
         { method: "POST" }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -740,10 +1107,11 @@ Queue an immediate check for a monitor outside its normal schedule. This starts
     description: `
 List historical checks for a monitor, optionally filtered by status and bounded by a result limit. Returns one page of check summaries and pagination metadata.
 `,
-    parameters: z4.object({
-      id: z4.string(),
-      limit: z4.number().int().positive().optional(),
-      offset: z4.number().int().nonnegative().optional(),
+    outputSchema: monitorChecksOutputSchema,
+    parameters: z5.object({
+      id: z5.string(),
+      limit: z5.number().int().positive().optional(),
+      offset: z5.number().int().nonnegative().optional(),
       status: checkStatusSchema.optional()
     }),
     execute: async (args2, { session, client: mcpClient }) => {
@@ -754,7 +1122,7 @@ List historical checks for a monitor, optionally filtered by status and bounded
         `/monitor/${encodeURIComponent(id)}/checks`,
         { query: { limit, offset, status } }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
   server2.addTool({
@@ -773,11 +1141,12 @@ Retrieve one monitor check and its page-level results, optionally filtered by pa
 
 Markdown tracking returns a unified text diff, JSON tracking returns field paths with previous/current values and a current snapshot, and mixed tracking returns both. Returns one page of results plus a \`next\` URL when more pages exist.
 `,
-    parameters: z4.object({
-      id: z4.string(),
-      checkId: z4.string(),
-      limit: z4.number().int().positive().optional(),
-      skip: z4.number().int().nonnegative().optional(),
+    outputSchema: monitorCheckOutputSchema,
+    parameters: z5.object({
+      id: z5.string(),
+      checkId: z5.string(),
+      limit: z5.number().int().positive().optional(),
+      skip: z5.number().int().nonnegative().optional(),
       pageStatus: pageStatusSchema.optional()
     }),
     execute: async (args2, { session, client: mcpClient }) => {
@@ -788,15 +1157,18 @@ Markdown tracking returns a unified text diff, JSON tracking returns field paths
         `/monitor/${encodeURIComponent(id)}/checks/${encodeURIComponent(checkId)}`,
         { query: { limit, skip, status: pageStatus } }
       );
-      return asText(res);
+      return monitorResult(res);
     }
   });
 }
 
 // src/research.ts
-import { z as z5 } from "zod";
+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)) {
@@ -910,21 +1282,22 @@ Several distinct framings of the same question surface different papers than a s
 
 Returns ranked papers with canonical IDs, titles, authors, and abstracts.
 `,
-    parameters: z5.object({
-      query: z5.string().min(1).describe(
+    outputSchema: researchSearchOutputSchema,
+    parameters: z6.object({
+      query: z6.string().min(1).describe(
         "Natural-language research topic or question, including methods, systems, conditions, populations, interventions, or outcomes when relevant."
       ),
-      k: z5.number().int().min(1).max(500).optional().describe("Number of ranked papers to return (default 40)."),
-      authors: z5.array(z5.string()).optional().describe(
+      k: z6.number().int().min(1).max(500).optional().describe("Number of ranked papers to return (default 40)."),
+      authors: z6.array(z6.string()).optional().describe(
         "Author substring filter(s); ALL must match (case-insensitive)."
       ),
-      categories: z5.array(z5.string()).optional().describe(
+      categories: z6.array(z6.string()).optional().describe(
         "Paper category filter(s) (e.g. `cs.LG`); ALL provided values must match."
       ),
-      from: z5.string().optional().describe(
+      from: z6.string().optional().describe(
         "Inclusive lower bound on created/updated date (`YYYY-MM-DD`)."
       ),
-      to: z5.string().optional().describe(
+      to: z6.string().optional().describe(
         "Inclusive upper bound on created/updated date (`YYYY-MM-DD`)."
       )
     }),
@@ -940,9 +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))
       );
-      return fmtHits(res.data?.results);
+      const results = res.data?.results ?? [];
+      return withAgentHints(withStructured(fmtHits(results), { results }), res.data, true);
     }
   });
   server2.addTool({
@@ -959,8 +1333,9 @@ Returns ranked papers with canonical IDs, titles, authors, and abstracts.
     description: `
 Retrieve canonical metadata for one paper ID, such as an arXiv, PMC, PMID, or DOI identifier. Returns the title, abstract, authors, categories, source IDs, and dates as markdown.
 `,
-    parameters: z5.object({
-      paperId: z5.string().min(1).describe(
+    outputSchema: researchPaperOutputSchema,
+    parameters: z6.object({
+      paperId: z6.string().min(1).describe(
         "Canonical paperId or primaryId such as `arxiv:1706.03762`, `pmcid:PMC12530322`, `pmid:40953549`, or `doi:10.1016/j.neunet.2025.108095`."
       )
     }),
@@ -969,9 +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))
       );
-      return fmtPaperMetadata(res.data?.paper);
+      const paper = res.data?.paper;
+      return withAgentHints(withStructured(
+        fmtPaperMetadata(paper),
+        paper ? { paper } : {}
+      ), res.data, true);
     }
   });
   server2.addTool({
@@ -990,12 +1369,13 @@ Find citation-graph candidates from one to ten \`seed_ids\`; the first ID is the
 
 Returns ranked candidates and the evaluated pool size.
 `,
-    parameters: z5.object({
-      seed_ids: z5.array(z5.string()).min(1).max(10),
-      intent: z5.string().min(1),
-      mode: z5.enum(["similar", "citers", "references"]).optional(),
-      k: z5.number().int().min(1).max(500).optional(),
-      rerank: z5.boolean().optional().describe("Apply an additional rerank over the fused candidates.")
+    outputSchema: researchRelatedOutputSchema,
+    parameters: z6.object({
+      seed_ids: z6.array(z6.string()).min(1).max(10),
+      intent: z6.string().min(1),
+      mode: z6.enum(["similar", "citers", "references"]).optional(),
+      k: z6.number().int().min(1).max(500).optional(),
+      rerank: z6.boolean().optional().describe("Apply an additional rerank over the fused candidates.")
     }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { seed_ids, intent, mode, k, rerank } = args2;
@@ -1012,12 +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 `${fmtHits(res.data?.results)}
-(poolSize=${res.data?.poolSize ?? 0})${note}`;
+      return withAgentHints(withStructured(
+        `${fmtHits(results)}
+(poolSize=${poolSize})${note}`,
+        { results, poolSize, ...res.data?.note ? { note: res.data.note } : {} }
+      ), res.data, true);
     }
   });
   server2.addTool({
@@ -1036,12 +1421,13 @@ Retrieve in-body passages from one paper that are relevant to a specific questio
 
 Returns matching passages or a notice when full text is unavailable.
 `,
-    parameters: z5.object({
-      paperId: z5.string().min(1).describe(
+    outputSchema: researchReadOutputSchema,
+    parameters: z6.object({
+      paperId: z6.string().min(1).describe(
         "Canonical paperId or primaryId such as `arxiv:1706.03762`, `pmcid:PMC12530322`, `pmid:40953549`, or `doi:10.1016/j.neunet.2025.108095`."
       ),
-      question: z5.string().min(1),
-      k: z5.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
+      question: z6.string().min(1),
+      k: z6.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
     }),
     execute: async (args2, { session, client: mcpClient }) => {
       const { paperId, question, k } = args2;
@@ -1051,10 +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 passages.length ? passages.map((p) => p.text).join("\n---\n") : "(no full-text passages available for this paper)";
+      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({
@@ -1068,9 +1457,10 @@ Returns matching passages or a notice when full text is unavailable.
     description: `
 Deprecated compatibility entry point. Use firecrawl_developer_search for GitHub issues, pull requests, and READMEs, plus code documentation, returned as matched passages.
 `,
-    parameters: z5.object({
-      query: z5.string().min(1),
-      k: z5.number().int().min(1).max(100).optional()
+    outputSchema: deprecatedToolOutputSchema,
+    parameters: z6.object({
+      query: z6.string().min(1),
+      k: z6.number().int().min(1).max(100).optional()
     }),
     canList: () => false,
     beforeValidate: () => {
@@ -1089,10 +1479,7 @@ Deprecated compatibility entry point. Use firecrawl_developer_search for GitHub
 }
 
 // src/usage.ts
-import { z as z6 } from "zod";
-function asText2(data) {
-  return JSON.stringify(data, null, 2);
-}
+import { z as z7 } from "zod";
 function assertSuccessful(status, response, operation) {
   if (status === 200 && response.success) return;
   throw new Error(response.error || `Failed to ${operation}`);
@@ -1113,11 +1500,12 @@ The current view returns \`remainingCredits\`, \`planCredits\`, \`billingPeriodS
 
 The historical view returns periods sorted by start date with \`startDate\`, \`endDate\`, and \`creditsUsed\`. Set \`byApiKey\` to include separate periods per API key, identified by the optional \`apiKey\` field. The newest period's \`endDate\` can be null.
 `,
-    parameters: z6.object({
-      view: z6.enum(["current", "historical"]).optional().describe(
+    outputSchema: creditUsageOutputSchema,
+    parameters: z7.object({
+      view: z7.enum(["current", "historical"]).optional().describe(
         "Select current balance or historical monthly usage. Defaults to current."
       ),
-      byApiKey: z6.boolean().optional().describe(
+      byApiKey: z7.boolean().optional().describe(
         'Break historical usage down by API key. When view is omitted, true selects the historical view; it cannot be combined with view "current".'
       )
     }),
@@ -1142,7 +1530,7 @@ The historical view returns periods sorted by start date with \`startDate\`, \`e
           response2.data,
           "get historical credit usage"
         );
-        return asText2(response2.data);
+        return structuredText(response2.data);
       }
       const response = await client.http.get(
         "/v2/team/credit-usage",
@@ -1150,7 +1538,7 @@ The historical view returns periods sorted by start date with \`startDate\`, \`e
       );
       assertSuccessful(response.status, response.data, "get credit usage");
       const data = response.data.data ?? response.data;
-      return asText2({
+      return structuredText({
         remainingCredits: data.remainingCredits ?? data.remaining_credits ?? 0,
         planCredits: data.planCredits ?? data.plan_credits,
         billingPeriodStart: data.billingPeriodStart ?? data.billing_period_start ?? null,
@@ -1165,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);
@@ -1248,11 +1698,11 @@ function getOAuthProtectedResourceMetadataUrl(profile) {
   const base = `${resource.origin}/.well-known/oauth-protected-resource`;
   return profile.id === "full" ? base : `${base}${resource.pathname}`;
 }
-function createOAuthChallengeResponse(error, profile, details = {}) {
+function createOAuthChallengeResponse(error2, profile, details = {}) {
   if (!isMcpOAuthEnabled()) {
     return void 0;
   }
-  const errorMessage = error instanceof Error ? error.message : String(error || "Unauthorized");
+  const errorMessage = error2 instanceof Error ? error2.message : String(error2 || "Unauthorized");
   const wwwAuthenticateDescription = errorMessage.replace(/[\r\n]+/g, " ").trim();
   const wwwAuthenticate = [
     ...profile.advertiseOAuth ? [
@@ -1304,8 +1754,8 @@ function createInvalidOAuthRecoveryResponse(recovery) {
   );
 }
 var CREDENTIAL_VALIDATION_RETRY_AFTER_SECONDS = 5;
-function createCredentialValidationUnavailableResponse(error) {
-  return new Response(error.message, {
+function createCredentialValidationUnavailableResponse(error2) {
+  return new Response(error2.message, {
     headers: {
       "Content-Type": "text/plain; charset=utf-8",
       "Retry-After": String(CREDENTIAL_VALIDATION_RETRY_AFTER_SECONDS)
@@ -1355,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({
@@ -1394,6 +1877,7 @@ async function introspectToken(token, expectedResource) {
   }
   if (!response.ok) {
     throw credentialValidationUnavailable({
+      edgeMitigation: edgeMitigation(response),
       elapsedMs: elapsedMs(),
       reason: "introspect_http_status",
       resource: expectedResource,
@@ -1601,13 +2085,13 @@ function makeAuthenticate(profile) {
         session
       );
       return session;
-    }).catch((error) => {
+    }).catch((error2) => {
       emitSearchCompanionAuthTelemetry(profile, request, "rejected");
       emitLegacyKeyPathTelemetry(profile, request, "rejected");
-      if (error instanceof InvalidFirecrawlCredentialError) {
-        throw createInvalidCredentialResponse(error);
+      if (error2 instanceof InvalidFirecrawlCredentialError) {
+        throw createInvalidCredentialResponse(error2);
       }
-      if (error instanceof InvalidOAuthCredentialError) {
+      if (error2 instanceof InvalidOAuthCredentialError) {
         const recovery = invalidOAuthRecoveryPayload();
         const oauthChallenge2 = createOAuthChallengeResponse(
           new Error(recovery.message),
@@ -1616,15 +2100,15 @@ function makeAuthenticate(profile) {
         );
         throw oauthChallenge2 ?? createInvalidOAuthRecoveryResponse(recovery);
       }
-      if (error instanceof CredentialValidationUnavailableError) {
-        throw createCredentialValidationUnavailableResponse(error);
+      if (error2 instanceof CredentialValidationUnavailableError) {
+        throw createCredentialValidationUnavailableResponse(error2);
       }
       const shouldChallenge = requestShouldReceiveOAuthChallenge(request, profile);
-      const oauthChallenge = shouldChallenge ? createOAuthChallengeResponse(error, profile) : void 0;
+      const oauthChallenge = shouldChallenge ? createOAuthChallengeResponse(error2, profile) : void 0;
       if (oauthChallenge) {
         throw oauthChallenge;
       }
-      throw error;
+      throw error2;
     });
     if (request) {
       request[authResultByRequest] = authResult;
@@ -1644,30 +2128,30 @@ function removeEmptyTopLevel(obj) {
   }
   return out;
 }
-var searchDomainSchema = z7.string().trim().toLowerCase().min(1).max(253).regex(
+var searchDomainSchema = z8.string().trim().toLowerCase().min(1).max(253).regex(
   /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/,
   "Domain must be a valid hostname without protocol or path"
 );
 var searchToolBaseFields = {
-  toolDetail: z7.enum(["compact", "summary", "full"]).optional().describe("Compact by default. Compact returns only provider, capability and description; full includes contracts. Inspect selected compact tools with firecrawl_find_tools providers and capabilities."),
-  query: z7.string().min(1).describe("Query for web and semantic tool discovery. Operators include quoted phrases, `-term`, `site:host`, `inurl:term`, `intitle:term`, and `related:host`; the set is non-exhaustive. Catalogue browsing is available through firecrawl_find_tools."),
-  domainTools: z7.boolean().optional().describe(
+  toolDetail: z8.enum(["compact", "summary", "full"]).optional().describe("Compact by default. Compact returns only provider, capability and description; full includes contracts. Inspect selected compact tools with firecrawl_find_tools providers and capabilities."),
+  query: z8.string().min(1).describe("Query for web and semantic tool discovery. Operators include quoted phrases, `-term`, `site:host`, `inurl:term`, `intitle:term`, and `related:host`; the set is non-exhaustive. Catalogue browsing is available through firecrawl_find_tools."),
+  domainTools: z8.boolean().optional().describe(
     "Include domain-matched tools for result URLs. Defaults to true when Alexandria is combined with web, news or images; semantic-only search leaves domain matching off."
   ),
-  highlights: z7.boolean().optional().describe(
+  highlights: z8.boolean().optional().describe(
     "Return query-relevant page excerpts for web and news results when available (default). Highlights appear in web `description` and news `snippet`; otherwise, original snippets are returned. Set to false to keep the original search snippets."
   ),
-  limit: z7.number().int().min(1).max(100).optional(),
-  tbs: z7.string().optional(),
-  filter: z7.string().optional(),
-  location: z7.string().optional(),
-  includeDomains: z7.array(searchDomainSchema).optional().describe("Hostnames to restrict results to. Mutually exclusive with excludeDomains."),
-  excludeDomains: z7.array(searchDomainSchema).optional().describe("Hostnames to leave out of results. Mutually exclusive with includeDomains."),
-  sources: z7.array(searchSourceSchema).optional().describe("Search sources; authenticated sessions default to web + alexandria, keyless sessions to web only. " + ALEXANDRIA_SOURCES_OPT_OUT + ' Use ["alexandria"] alone for provider discovery without web results.'),
-  categories: z7.array(z7.enum(["research", "pdf", "developer"])).optional().describe(
+  limit: z8.number().int().min(1).max(100).optional(),
+  tbs: z8.string().optional(),
+  filter: z8.string().optional(),
+  location: z8.string().optional(),
+  includeDomains: z8.array(searchDomainSchema).optional().describe("Hostnames to restrict results to. Mutually exclusive with excludeDomains."),
+  excludeDomains: z8.array(searchDomainSchema).optional().describe("Hostnames to leave out of results. Mutually exclusive with includeDomains."),
+  sources: z8.array(searchSourceSchema).optional().describe("Search sources; authenticated sessions default to web + alexandria, keyless sessions to web only. " + ALEXANDRIA_SOURCES_OPT_OUT + ' Use ["alexandria"] alone for provider discovery without web results.'),
+  categories: z8.array(z8.enum(["research", "pdf", "developer"])).optional().describe(
     'Limit results to specific source types. `research` restricts ordinary web results to research-affiliated websites and returns page snippets, which is separate from the `firecrawl_research_*` tools that search paper abstracts and full text across biomedical (PubMed, bioRxiv, medRxiv) and arXiv literature; `pdf` searches PDF results; `developer` searches an index built for coding agents over public repositories, GitHub issues, merged pull requests, repository READMEs, and code documentation. `developer` returns hits in `data.web` with `category: "developer"`; the other categories also filter `data.web`.'
   ),
-  enterprise: z7.array(z7.enum(["default", "anon", "zdr"])).optional()
+  enterprise: z8.array(z8.enum(["default", "anon", "zdr"])).optional()
 };
 function searchDomainsAreExclusive(args2) {
   return !(args2.includeDomains?.length && args2.excludeDomains?.length);
@@ -1675,15 +2159,15 @@ function searchDomainsAreExclusive(args2) {
 var SEARCH_DOMAINS_CONFLICT_MESSAGE = "includeDomains and excludeDomains cannot both be specified";
 var EXCHANGE_KEY_REQUIRED_MESSAGE = "Alexandria requires an API key on a team with Alexandria access";
 var EXCHANGE_MAX_CALLS = 10;
-var exchangeCallSchema = z7.object({
-  provider: z7.string().min(1).describe('Provider slug, e.g. "fred".'),
-  capability: z7.string().min(1).describe(
+var exchangeCallSchema = z8.object({
+  provider: z8.string().min(1).describe('Provider slug, e.g. "fred".'),
+  capability: z8.string().min(1).describe(
     'Capability address as returned by search or discover, e.g. "series/observations".'
   ),
-  version: z7.string().trim().min(1).max(128).optional().describe("Optional published workflow version. Omit to use the latest version."),
-  options: z7.record(z7.string(), z7.any()).optional().describe("Capability options as declared by its contract.")
+  version: z8.string().trim().min(1).max(128).optional().describe("Optional published workflow version. Omit to use the latest version."),
+  options: z8.record(z8.string(), z8.any()).optional().describe("Capability options as declared by its contract.")
 });
-var exchangeCallsSchema = z7.array(exchangeCallSchema).min(1).max(EXCHANGE_MAX_CALLS);
+var exchangeCallsSchema = z8.array(exchangeCallSchema).min(1).max(EXCHANGE_MAX_CALLS);
 function assertExchangeCredential(session) {
   if (hasCredential(session)) return;
   const payload = {
@@ -1707,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.`;
@@ -1722,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: {
@@ -1749,27 +2234,29 @@ Do not retry until acceptance is confirmed.`,
     }
   );
 }
-function throwIfTermsRequired(error, context) {
-  const source = error;
+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 {
     return await run();
-  } catch (error) {
-    throwIfTermsRequired(error, context);
-    throw error;
+  } catch (error2) {
+    throwIfTermsRequired(error2, context);
+    throw error2;
   }
 }
 async function relayExchangeError(run, context) {
   try {
     return await run();
-  } catch (error) {
-    throwIfTermsRequired(error, context);
-    const response = error?.response;
-    if (!response || response.status === 401) throw error;
+  } catch (error2) {
+    throwIfTermsRequired(error2, 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) {
@@ -1779,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: {
@@ -1792,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 } : {}
     });
   }
@@ -1799,14 +2288,14 @@ async function relayExchangeError(run, context) {
 async function postSearchWithFallback(client, body, implicitTools) {
   try {
     return await client.http.post("/v2/search", body);
-  } catch (error) {
-    const response = error?.response;
+  } catch (error2) {
+    const response = error2?.response;
     const unavailable = [
       "Provider discovery requires access and does not support zero data retention.",
       "This endpoint is not enabled for this team.",
       "Exchange is not enabled for this team."
     ].includes(response?.data?.error);
-    if (!implicitTools || response?.status !== 403 || !unavailable) throw error;
+    if (!implicitTools || response?.status !== 403 || !unavailable) throw error2;
     return client.http.post("/v2/search", {
       ...body,
       sources: ["web"],
@@ -1845,10 +2334,9 @@ 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} When a provider matches, prefer it over scraping pages if the task needs the same fields across several entities, provenance, exact figures or timestamps, or a large set of records; execute it through firecrawl_scrape with the returned contract. If web results already answer the question, use them. Before scraping more than one page for the same fields, spend one free firecrawl_find_tools call to check for a provider. 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 \u2014 code behaviour, a library or framework, an API contract, an error message, or a known bug \u2014 firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. Execution with firecrawl_scrape alexandria uses requestId; reuse the returned ID for retries of the same payload, never a new ID to bypass a pending or uncertain 409. 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. Follow the returned terms/show and terms/accept calls through firecrawl_scrape; acceptance requires explicit user authorization for the reviewed version and digest and confirmed:true. Otherwise direct an organization admin to the dashboard URL. Do not repeat successful provider calls just because the client could not display their output. Provide only the required inputs and account for stated network or external side effects.
-${ALEXANDRIA_FEEDBACK_GUIDANCE}`;
+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. Use firecrawl_find_tools to browse the Alexandria catalogue or read a provider's full contract, and firecrawl_scrape with an alexandria body to execute a capability discovered that way; 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_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([
   "firecrawl_search",
   "firecrawl_developer_search",
@@ -1992,17 +2480,31 @@ function invalidOAuthRecoveryPayload() {
     message: INVALID_OAUTH_MESSAGE
   });
 }
-function isCoreCredentialRejection(error) {
-  if (!(error instanceof Error)) return false;
-  const candidate = error;
+function isCoreCredentialRejection(error2) {
+  if (!(error2 instanceof Error)) return false;
+  const candidate = error2;
   return candidate.status === 401 || candidate.response?.status === 401;
 }
 async function runWithCredentialRecovery(run, requestId, session) {
   try {
     return await run();
-  } catch (error) {
-    if (session?.authType !== "api-key" || !isCoreCredentialRejection(error)) {
-      throw error;
+  } 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);
     throw new UserError2(String(payload.message), payload);
@@ -2055,7 +2557,7 @@ function deprecatedExtractPayload() {
     docs_url: "https://docs.firecrawl.dev/developer-guides/usage-guides/choosing-the-data-extractor"
   };
 }
-function emitActionLog(toolName, status, session, error, requestId = randomUUID(), code) {
+function emitActionLog(toolName, status, session, error2, requestId = randomUUID(), code) {
   if (process.env.CLOUD_SERVICE !== "true") return;
   const payload = {
     team_id: session?.teamId,
@@ -2067,7 +2569,7 @@ function emitActionLog(toolName, status, session, error, requestId = randomUUID(
     status,
     request_id: requestId,
     resource: primaryProfile.resourceUrl,
-    ...error ? { error_class: error instanceof Error ? error.name : typeof error } : {},
+    ...error2 ? { error_class: error2 instanceof Error ? error2.name : typeof error2 } : {},
     ...code ? { code } : {}
   };
   console.error("[MCP_ACTION]", JSON.stringify(payload));
@@ -2087,6 +2589,26 @@ function emitActionLog(toolName, status, session, error, 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;
@@ -2156,20 +2678,35 @@ 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 {
         const result = await runTool();
         emitActionLog(tool.name, "success", invocationSession, void 0, requestId);
         return result;
-      } catch (error) {
-        emitActionLog(tool.name, "error", invocationSession, error, requestId);
-        throw error;
+      } catch (error2) {
+        emitActionLog(tool.name, "error", invocationSession, error2, requestId);
+        throw error2;
       }
     }
   };
@@ -2215,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 && {
@@ -2224,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) {
@@ -2253,20 +2828,21 @@ 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;
 }
-function asText3(data) {
+function asText(data) {
   return JSON.stringify(data, null, 2);
 }
-function compactText(data) {
-  return JSON.stringify(data);
-}
 var safeActionTypes = ["wait", "screenshot", "scroll", "scrape"];
 var otherActions = [
   "click",
@@ -2332,10 +2908,10 @@ function transformScrapeParams(args2) {
   delete out.pdfOptions;
   return out;
 }
-var scrapeParamsSchema = z7.object({
-  url: z7.string().url(),
-  formats: z7.array(
-    z7.enum([
+var scrapeParamsSchema = z8.object({
+  url: z8.string().url(),
+  formats: z8.array(
+    z8.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -2349,87 +2925,93 @@ var scrapeParamsSchema = z7.object({
       "audio"
     ])
   ).optional(),
-  jsonOptions: z7.object({
-    prompt: z7.string().optional(),
-    schema: z7.record(z7.string(), z7.any()).optional()
+  jsonOptions: z8.object({
+    prompt: z8.string().optional(),
+    schema: z8.record(z8.string(), z8.any()).optional()
   }).optional(),
-  queryOptions: z7.object({
-    prompt: z7.string().max(1e4),
-    mode: z7.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z8.object({
+    prompt: z8.string().max(1e4),
+    mode: z8.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  screenshotOptions: z7.object({
-    fullPage: z7.boolean().optional(),
-    quality: z7.number().optional(),
-    viewport: z7.object({ width: z7.number(), height: z7.number() }).optional()
+  screenshotOptions: z8.object({
+    fullPage: z8.boolean().optional(),
+    quality: z8.number().optional(),
+    viewport: z8.object({ width: z8.number(), height: z8.number() }).optional()
   }).optional(),
-  parsers: z7.array(z7.enum(["pdf"])).optional(),
-  pdfOptions: z7.object({
-    maxPages: z7.number().int().min(1).max(1e4).optional()
+  parsers: z8.array(z8.enum(["pdf"])).optional(),
+  pdfOptions: z8.object({
+    maxPages: z8.number().int().min(1).max(1e4).optional()
   }).optional(),
-  onlyMainContent: z7.boolean().optional(),
-  redactPII: z7.boolean().optional(),
-  includeTags: z7.array(z7.string()).optional(),
-  excludeTags: z7.array(z7.string()).optional(),
-  waitFor: z7.number().optional(),
+  onlyMainContent: z8.boolean().optional(),
+  redactPII: z8.boolean().optional(),
+  includeTags: z8.array(z8.string()).optional(),
+  excludeTags: z8.array(z8.string()).optional(),
+  waitFor: z8.number().optional(),
   ...SAFE_MODE ? {} : {
-    actions: z7.array(
-      z7.object({
-        type: z7.enum(allowedActionTypes),
-        selector: z7.string().optional(),
-        milliseconds: z7.number().optional(),
-        text: z7.string().optional(),
-        key: z7.string().optional(),
-        direction: z7.enum(["up", "down"]).optional(),
-        script: z7.string().optional(),
-        fullPage: z7.boolean().optional()
+    actions: z8.array(
+      z8.object({
+        type: z8.enum(allowedActionTypes),
+        selector: z8.string().optional(),
+        milliseconds: z8.number().optional(),
+        text: z8.string().optional(),
+        key: z8.string().optional(),
+        direction: z8.enum(["up", "down"]).optional(),
+        script: z8.string().optional(),
+        fullPage: z8.boolean().optional()
       })
     ).optional()
   },
-  mobile: z7.boolean().optional(),
-  skipTlsVerification: z7.boolean().optional(),
-  removeBase64Images: z7.boolean().optional(),
-  location: z7.object({
-    country: z7.string().optional(),
-    languages: z7.array(z7.string()).optional()
+  mobile: z8.boolean().optional(),
+  skipTlsVerification: z8.boolean().optional(),
+  removeBase64Images: z8.boolean().optional(),
+  location: z8.object({
+    country: z8.string().optional(),
+    languages: z8.array(z8.string()).optional()
   }).optional(),
-  storeInCache: z7.boolean().optional(),
-  zeroDataRetention: z7.boolean().optional(),
-  maxAge: z7.number().optional(),
-  lockdown: z7.boolean().optional(),
-  proxy: z7.enum(["basic", "stealth", "enhanced", "auto"]).optional(),
-  profile: z7.object({
-    name: z7.string(),
-    saveChanges: z7.boolean().optional()
+  storeInCache: z8.boolean().optional(),
+  zeroDataRetention: z8.boolean().optional(),
+  maxAge: z8.number().optional(),
+  lockdown: z8.boolean().optional(),
+  proxy: z8.enum(["basic", "stealth", "enhanced", "auto"]).optional(),
+  profile: z8.object({
+    name: z8.string(),
+    saveChanges: z8.boolean().optional()
   }).optional()
 });
+var ALEXANDRIA_IGNORED_SCRAPE_OPTIONS = /* @__PURE__ */ new Set(["toolDetail", "domainTools"]);
 var scrapeToolParamsSchema = scrapeParamsSchema.extend({
-  url: z7.string().url().optional(),
-  timeout: z7.number().int().positive().optional().describe("Execution timeout in milliseconds."),
-  requestId: z7.string().regex(/^[A-Za-z0-9._:-]{1,128}$/).optional().describe(
-    "Alexandria execution ID. Reuse the returned ID for retries of the identical payload, never a new ID to bypass pending or uncertain execution; generated when omitted. For potentially large workflow results, supply and preserve one before execution. Errors relay a code and chargeId: request_in_flight (409) retry the same requestId later; request_unresolved (503) keep the requestId for reconciliation, never mint a new one; duplicate_request (409) the requestId belongs to a different payload; unknown_provider (404), insufficient_credits (402) and billing_unavailable (503) mean nothing executed."
+  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(
+    "Idempotency key bound to one Alexandria execution payload. Generated when omitted and returned with the result."
   ),
-  alexandria: z7.union([exchangeCallSchema, exchangeCallsSchema]).optional().describe(
-    "Execute catalogued Alexandria capabilities instead of scraping a URL. Exactly one of url or alexandria. One {provider, capability, options} object or an array of 1-10, found through firecrawl_search or firecrawl_find_tools. Each call may include version to pin a published workflow; omitting it uses latest. Only timeout also applies at the top level. " + ALEXANDRIA_CONTRACT_GUIDANCE + " Returns per-capability results in data.alexandria with data, records, or an error with a code; check each item even when the outer response succeeds. If a response provides nextTool, follow it to read a large result instead of repeating a successful provider call. Needs an API key on a team with Alexandria enabled. A terms-gated provider returns THIRD_PARTY_DATA_TERMS_REQUIRED (403) with requiresAction.url: follow the returned terms/show and terms/accept calls through this tool, accepting only after explicit user authorization for the reviewed version and digest; an organization admin can instead accept at the dashboard URL. Retry only after confirmed acceptance."
+  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. Requires an API key on a team with Alexandria enabled. Some providers require accepted terms; blocked requests return the applicable requirements."
   ),
-  toolDetail: z7.enum(["compact", "summary", "full"]).optional().describe("URL domain discovery detail: summary by default, compact returns provider/capability/description, full includes contracts."),
-  domainTools: z7.boolean().optional().describe(
-    "URL mode only: include domain-matched Alexandria tools for the page in tools on the returned document."
+  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(
+    "URL mode only: include domain-matched Alexandria tools for the page in tools on the returned document. Ignored with alexandria."
   )
 }).refine(
   (args2) => Boolean(args2.url) !== Boolean(args2.alexandria),
   "Provide exactly one of url or alexandria"
 ).refine(
   (args2) => !args2.alexandria || Object.entries(args2).every(
-    ([key, value]) => key === "alexandria" || key === "requestId" || key === "timeout" || value === void 0
+    ([key, value]) => key === "alexandria" || key === "requestId" || key === "timeout" || // URL-mode discovery options that mean nothing when executing a
+    // provider. Agents carry toolDetail over from firecrawl_search (where
+    // it selects contract detail), so accept and ignore them rather than
+    // failing the call: Codex sent toolDetail on 18 of 315 Alexandria
+    // executions across the AX EXP-058 runs, each one a wasted round trip.
+    ALEXANDRIA_IGNORED_SCRAPE_OPTIONS.has(key) || value === void 0
   ),
   "alexandria cannot be combined with url or other scrape options"
 ).refine(
   (args2) => !args2.requestId || !!args2.alexandria,
   "requestId applies to Alexandria execution only"
 );
-var parseOptionParamsSchema = z7.object({
-  formats: z7.array(
-    z7.enum([
+var parseOptionParamsSchema = z8.object({
+  formats: z8.array(
+    z8.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -2439,48 +3021,48 @@ var parseOptionParamsSchema = z7.object({
       "query"
     ])
   ).optional(),
-  jsonOptions: z7.object({
-    prompt: z7.string().optional(),
-    schema: z7.record(z7.string(), z7.any()).optional()
+  jsonOptions: z8.object({
+    prompt: z8.string().optional(),
+    schema: z8.record(z8.string(), z8.any()).optional()
   }).optional(),
-  queryOptions: z7.object({
-    prompt: z7.string().max(1e4),
-    mode: z7.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z8.object({
+    prompt: z8.string().max(1e4),
+    mode: z8.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  parsers: z7.array(z7.enum(["pdf"])).optional(),
-  pdfOptions: z7.object({
-    maxPages: z7.number().int().min(1).max(1e4).optional()
+  parsers: z8.array(z8.enum(["pdf"])).optional(),
+  pdfOptions: z8.object({
+    maxPages: z8.number().int().min(1).max(1e4).optional()
   }).optional(),
-  onlyMainContent: z7.boolean().optional(),
-  redactPII: z7.boolean().optional(),
-  includeTags: z7.array(z7.string()).optional(),
-  excludeTags: z7.array(z7.string()).optional(),
-  removeBase64Images: z7.boolean().optional(),
-  skipTlsVerification: z7.boolean().optional(),
-  storeInCache: z7.boolean().optional(),
-  zeroDataRetention: z7.boolean().optional(),
-  maxAge: z7.number().optional().describe("Ignored: parse never reuses or stores indexed content."),
-  proxy: z7.enum(["basic", "auto"]).optional()
+  onlyMainContent: z8.boolean().optional(),
+  redactPII: z8.boolean().optional(),
+  includeTags: z8.array(z8.string()).optional(),
+  excludeTags: z8.array(z8.string()).optional(),
+  removeBase64Images: z8.boolean().optional(),
+  skipTlsVerification: z8.boolean().optional(),
+  storeInCache: z8.boolean().optional(),
+  zeroDataRetention: z8.boolean().optional(),
+  maxAge: z8.number().optional().describe("Ignored: parse never reuses or stores indexed content."),
+  proxy: z8.enum(["basic", "auto"]).optional()
 });
 var localParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z7.string().min(1).describe(
+  filePath: z8.string().min(1).describe(
     "Absolute or relative path to a local file to parse. Supported: .html, .htm, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls"
   ),
-  contentType: z7.string().optional().describe(
+  contentType: z8.string().optional().describe(
     "Optional MIME type override. If omitted, the server infers the file kind from the extension."
   )
 });
 var hostedParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z7.string().min(1).optional().describe(
+  filePath: z8.string().min(1).optional().describe(
     "Phase 1 only: path to the local file on the caller/harness machine. Hosted MCP will not read or stat this path; it is used only to produce upload instructions."
   ),
-  uploadRef: z7.string().min(1).optional().describe(
+  uploadRef: z8.string().min(1).optional().describe(
     "Phase 2 only: short-lived upload reference returned by phase 1 after the local PUT upload completes."
   ),
-  contentType: z7.string().optional().describe(
+  contentType: z8.string().optional().describe(
     "Phase 1 MIME type override. If omitted, the server infers it from the file extension without reading the file."
   ),
-  declaredSizeBytes: z7.number().int().positive().optional().describe(
+  declaredSizeBytes: z8.number().int().positive().optional().describe(
     "Optional phase 1 size declaration. Hosted MCP does not stat the file; provide this only if the caller already knows it."
   )
 }).superRefine((value, ctx) => {
@@ -2488,7 +3070,7 @@ var hostedParseParamsSchema = parseOptionParamsSchema.extend({
   const hasUploadRef = typeof value.uploadRef === "string" && value.uploadRef.length > 0;
   if (hasFilePath === hasUploadRef) {
     ctx.addIssue({
-      code: z7.ZodIssueCode.custom,
+      code: z8.ZodIssueCode.custom,
       message: "Hosted firecrawl_parse requires exactly one of filePath (phase 1) or uploadRef (phase 2).",
       path: hasFilePath && hasUploadRef ? ["uploadRef"] : ["filePath"]
     });
@@ -2541,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) : {}
@@ -2557,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;
@@ -2609,7 +3193,7 @@ async function executeHostedParse(args2, session, log, origin) {
     );
   }
   if (!hasCredential(session) && !isKeylessMode(session)) {
-    return asText3({
+    return asText({
       success: false,
       mode: "hosted-upload-ref-auth-required",
       message: "Hosted firecrawl_parse requires an authenticated Firecrawl session or keyless eligibility before a local file upload URL can be minted. Connect a Firecrawl account, provide an API key, or use keyless hosted MCP while eligible, then call firecrawl_parse again."
@@ -2639,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(
@@ -2647,8 +3232,9 @@ async function executeHostedParse(args2, session, log, origin) {
     }
     const uploadHeaders = upload.headers && Object.keys(upload.headers).length > 0 ? upload.headers : (upload.method ?? "PUT").toUpperCase() === "POST" ? {} : { "Content-Type": contentType };
     const uploadForCommand = { ...upload, headers: uploadHeaders };
-    return asText3({
+    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: {
@@ -2683,7 +3269,7 @@ async function executeHostedParse(args2, session, log, origin) {
     session,
     origin
   );
-  return asText3(parseJson);
+  return asText(parseJson);
 }
 var scrapeTool = {
   name: "firecrawl_scrape",
@@ -2697,14 +3283,15 @@ var scrapeTool = {
     // Does not modify, delete, or write to external websites.
   },
   description: `
-Scrape one URL and return its content: markdown by default, or HTML, links, screenshots, branding data, a targeted answer, or JSON matching a supplied schema. Use it when the request identifies a page and needs its content or defined fields. Use \`firecrawl_search\` when additional web sources are needed, \`firecrawl_map\` to list a site's URLs, and \`firecrawl_crawl\` for a set of pages.
+Scrape one URL and return its content: markdown by default, or HTML, links, screenshots, branding data, a targeted answer, or JSON matching a supplied schema. Use it when the request identifies a page and needs its content or defined fields. Use \`firecrawl_search\` when additional web sources are needed; on an authenticated session, \`firecrawl_map\` lists a site's URLs and \`firecrawl_crawl\` collects a set of pages.
 
 Firecrawl may serve recently indexed content; set \`maxAge: 0\` for a live fetch or a smaller \`maxAge\` to bound staleness. A successful response does not by itself confirm the page is still current. Browser actions can change the live page when interactive actions are enabled. Authenticated responses can include a \`metadata.scrapeId\` for optional scrape feedback.
 
-On an authenticated session with Alexandria access, if you are about to scrape the same fields from several pages, first run \`firecrawl_search\` with \`sources\` unset (or \`firecrawl_find_tools\`): a matching Alexandria provider returns those fields as typed records in one call. Keyless sessions have no provider matches; scrape directly.
+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: pass \`alexandria\` instead of \`url\` to execute catalogued capabilities; the \`alexandria\` and \`requestId\` parameters describe batching, retries, errors and provider terms. Alexandria results include a \`feedbackTool\` pointer: after the task, report how the catalogue served the website through \`firecrawl_feedback\` with endpoint \`alexandria\` (free, no job ID).
+Alexandria mode, on an authenticated session with Alexandria access: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`.
 `,
+  outputSchema: scrapeOutputSchema,
   parameters: scrapeToolParamsSchema,
   execute: async (args2, { session, log, client: mcpClient }) => {
     const origin = requestOrigin(mcpClient, session);
@@ -2719,7 +3306,9 @@ Alexandria mode: pass \`alexandria\` instead of \`url\` to execute catalogued ca
       log.info("Executing Alexandria capabilities", {
         count: Array.isArray(alexandria) ? alexandria.length : 1
       });
-      return executeExchangeCalls(session, alexandria, suppliedRequestId, options.timeout, origin);
+      return structuredJsonText(
+        await executeExchangeCalls(session, alexandria, suppliedRequestId, options.timeout, origin)
+      );
     }
     const transformed = transformScrapeParams(
       options
@@ -2740,20 +3329,26 @@ Alexandria mode: pass \`alexandria\` instead of \`url\` to execute catalogued ca
         },
         session
       );
-      return asText3(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 asText3(res);
+    return structuredText(res);
   }
 };
-server.addTool(scrapeTool);
+server.addTool({
+  ...scrapeTool,
+  _meta: { "anthropic/alwaysLoad": true }
+});
 server.addTool({
   name: "firecrawl_map",
   annotations: {
@@ -2770,28 +3365,33 @@ Enumerate URLs indexed under one website through Firecrawl without fetching each
 
 Returns matching URLs rather than page bodies. Retrieve one page with \`firecrawl_scrape\`; collect content across multiple pages with \`firecrawl_crawl\`. Authenticated responses can include an \`id\` for optional map feedback.
 `,
-  parameters: z7.object({
-    url: z7.string().url(),
-    search: z7.string().optional(),
-    sitemap: z7.enum(["include", "skip", "only"]).optional(),
-    includeSubdomains: z7.boolean().optional(),
-    limit: z7.number().optional(),
-    ignoreQueryParameters: z7.boolean().optional()
+  outputSchema: mapOutputSchema,
+  parameters: z8.object({
+    url: z8.string().url(),
+    search: z8.string().optional(),
+    sitemap: z8.enum(["include", "skip", "only"]).optional(),
+    includeSubdomains: z8.boolean().optional(),
+    limit: z8.number().optional(),
+    ignoreQueryParameters: z8.boolean().optional()
   }),
   execute: async (args2, { session, log, client: mcpClient }) => {
     const { url, ...options } = args2;
     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)
-    });
-    return asText3(res);
+    const res = await sdkResultWithAgentHints(
+      client,
+      () => client.map(String(url), {
+        ...cleaned,
+        origin: requestOrigin(mcpClient, session)
+      })
+    );
+    return structuredText(res);
   }
 });
 server.addTool({
   name: "firecrawl_search",
+  _meta: { "anthropic/alwaysLoad": true },
   annotations: {
     title: "Firecrawl web search",
     readOnlyHint: true,
@@ -2806,11 +3406,12 @@ Search web, news, or image sources and return ranked results with query-relevant
 
 ${ALEXANDRIA_SEARCH_LEAD}
 
-Tool matches are discovery, not executed data: execute one through \`firecrawl_scrape\` with an \`alexandria\` body, or read its full contract with \`firecrawl_find_tools\`. After an Alexandria task, call firecrawl_feedback once per website with endpoint "alexandria" (free, no job ID).
+On an authenticated session, tool matches describe available capabilities; \`firecrawl_find_tools\` returns their contracts and \`firecrawl_scrape\` with an \`alexandria\` body executes a selected capability. Keyless sessions get no Alexandria matches in data.tools.
 
 For a programming question, add \`categories: ["developer"]\`; its hits return in \`data.web\` with \`category: "developer"\`. \`categories: ["research"]\` restricts web results to research-affiliated websites; the \`firecrawl_research_*\` tools are a separate surface over paper abstracts and full text (PubMed, bioRxiv, medRxiv, arXiv). Query operators, domain filters, \`categories\`, \`toolDetail\` and \`scrapeOptions\` are described on their parameters. Returns source-type result groups and usage metadata. Authenticated responses can include an \`id\` for optional search feedback.
 `,
-  parameters: z7.object({
+  outputSchema: searchOutputSchema,
+  parameters: z8.object({
     ...searchToolBaseFields,
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional().describe("Attach page content for web results in the same call. These fetches ignore maxAge, so use firecrawl_scrape when you need a live fetch. scrapeOptions fetches web pages, never Alexandria provider tools.")
   }).refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE).refine(
@@ -2847,7 +3448,7 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
       const json = await keylessPost("/v2/search", searchBody, session);
       const keylessResponse = { ...json ?? {} };
       delete keylessResponse.id;
-      return compactText(keylessResponse);
+      return structuredCompact(keylessResponse);
     }
     const client = getClient(session);
     const postSearch = () => postSearchWithFallback(
@@ -2857,7 +3458,7 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
     );
     const context = { tool: "firecrawl_search" };
     const httpRes = exchangeSource ? await relayExchangeError(postSearch, context) : await relayTermsRequired(postSearch, context);
-    return compactText(httpRes?.data ?? {});
+    return structuredCompact(httpRes?.data ?? {});
   }
 });
 async function executeExchangeCalls(session, alexandria, suppliedRequestId, timeout, origin = requestOrigin(void 0, session)) {
@@ -2895,11 +3496,11 @@ async function executeExchangeCalls(session, alexandria, suppliedRequestId, time
       randomUUID(),
       alexandriaFeedbackAvailable(session) && alexandriaCallsWarrantFeedback(calls) ? { feedbackTool: ALEXANDRIA_FEEDBACK_HINT } : {}
     );
-  } catch (error) {
-    if (error?.response?.status === 401) throw error;
+  } catch (error2) {
+    if (error2?.response?.status === 401) throw error2;
     throw new UserError2(
-      `${error instanceof Error ? error.message : String(error)} Request ID: ${requestId}. Reuse this ID only with the identical payload.`,
-      { ...error instanceof UserError2 ? error.extras : {}, requestId }
+      `${error2 instanceof Error ? error2.message : String(error2)} Request ID: ${requestId}. Reuse this ID only with the identical payload.`,
+      { ...error2 instanceof UserError2 ? error2.extras : {}, requestId }
     );
   }
 }
@@ -2912,15 +3513,16 @@ var findToolsTool = {
     destructiveHint: false,
     idempotentHint: true
   },
-  description: "Browse Alexandria data providers and workflows or read a selected contract. Alexandria covers " + ALEXANDRIA_CATALOGUE_VERTICALS + ": typed, sourced records through published contracts. Prefer normal firecrawl_search for a data task; it already returns matching providers. Use this tool when the contract you need was not returned in full, to browse a category when search found nothing, or before scraping the same fields from several pages. Discovery is free. Use query for semantic discovery or urls to find providers for a website. With no arguments, browse categories, then providers and tools. Inspect a selected contract before executing through firecrawl_scrape; reuse contracts already returned. Follow nextTool for further discovery or pagination. Discovery does not execute providers. Use firecrawl_search when you also need web results. Results include a feedbackTool pointer: after the task, report how the catalogue served the website through firecrawl_feedback with endpoint alexandria, including when nothing covered it (free, no job ID).",
+  description: "Browse Alexandria data providers and workflows or read a selected contract. Alexandria covers " + ALEXANDRIA_CATALOGUE_VERTICALS + ": typed, sourced records through published contracts. Prefer normal firecrawl_search for a data task; it already returns matching providers. Use this tool when the contract you need was not returned in full, to browse a category when search found nothing, or before scraping the same fields from several pages. Discovery is free. Use query for semantic discovery or urls to find providers for a website. With no arguments, browse categories, then providers and tools. Contracts describe the inputs and outputs for execution through firecrawl_scrape. nextTool identifies further discovery or pagination. Discovery does not execute providers. Use firecrawl_search when you also need web results.",
+  outputSchema: findToolsOutputSchema,
   parameters: findToolsSchema,
   execute: async (args2, { session, client: mcpClient }) => {
     const origin = requestOrigin(mcpClient, session);
     let options;
     try {
       options = findToolsOptions(args2);
-    } catch (error) {
-      throw new UserError2(error instanceof Error ? error.message : String(error));
+    } catch (error2) {
+      throw new UserError2(error2 instanceof Error ? error2.message : String(error2));
     }
     if (options.level === "categories") {
       assertExchangeCredential(session);
@@ -2940,25 +3542,26 @@ var findToolsTool = {
       }));
       const page = { level: "categories", items, total: rows.length };
       if (offset + options.limit < rows.length) page.nextTool = { name: "firecrawl_find_tools", arguments: { level: "categories", limit: options.limit, offset: offset + options.limit } };
-      return compactText(withAlexandriaFeedbackHint(withFindToolsNavigation({ success: true, data: { creditsCost: 0, alexandria: [{ provider: "firecrawl", capability: "find-tools", creditsCost: 0, data: page }] } }), alexandriaFeedbackAvailable(session)));
+      return structuredCompact(withAlexandriaFeedbackHint(withFindToolsNavigation({ success: true, data: { creditsCost: 0, alexandria: [{ provider: "firecrawl", capability: "find-tools", creditsCost: 0, data: page }] } }), alexandriaFeedbackAvailable(session)));
     }
     const result = await executeExchangeCalls(session, { provider: "firecrawl", capability: "find-tools", options }, void 0, void 0, origin);
-    return compactText(withFindToolsNavigation(JSON.parse(result)));
+    return structuredCompact(withFindToolsNavigation(JSON.parse(result)));
   }
 };
 server.addTool(findToolsTool);
 var SEARCH_SURFACE_SCRAPE_DESCRIPTION = `
 Scrape one URL and return its content, or execute catalogued Alexandria capabilities. URL mode returns markdown by default, or HTML, links, screenshots, branding data, a targeted answer, or JSON matching a supplied schema, plus page metadata. Firecrawl may serve recently indexed content; set \`maxAge: 0\` for a live fetch. A successful response does not by itself confirm the page is still current. Browser actions can change the live page when interactive actions are enabled, and a named browser profile can load saved session data and overwrite its stored state.
 
-Before scraping the same fields from several pages, first run \`firecrawl_search\` with \`sources\` unset (or \`firecrawl_find_tools\`): a matching Alexandria provider returns those fields as typed records in one call.
+\`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: pass \`alexandria\` instead of \`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,
+  _meta: { "anthropic/alwaysLoad": true },
   description: SEARCH_SURFACE_SCRAPE_DESCRIPTION
 };
-var SEARCH_SURFACE_FIND_TOOLS_DESCRIPTION = "Browse Alexandria data providers and workflows or read a selected contract. Alexandria covers " + ALEXANDRIA_CATALOGUE_VERTICALS + ": typed, sourced records through published contracts. Prefer normal firecrawl_search for a data task; it already returns matching providers. Use this tool when the contract you need was not returned in full, to browse a category when search found nothing, or before scraping the same fields from several pages. Discovery is free. Use query for semantic discovery or urls to find providers for a website. With no arguments, browse categories, then providers and tools. Inspect a selected contract before executing through firecrawl_scrape; reuse contracts already returned. Follow nextTool for further discovery or pagination. Discovery does not execute providers. Use firecrawl_search when you also need web results.";
+var SEARCH_SURFACE_FIND_TOOLS_DESCRIPTION = "Browse Alexandria data providers and workflows or read a selected contract. Alexandria covers " + ALEXANDRIA_CATALOGUE_VERTICALS + ": typed, sourced records through published contracts. Prefer normal firecrawl_search for a data task; it already returns matching providers. Use this tool when the contract you need was not returned in full, to browse a category when search found nothing, or before scraping the same fields from several pages. Discovery is free. Use query for semantic discovery or urls to find providers for a website. With no arguments, browse categories, then providers and tools. Contracts describe the inputs and outputs for execution through firecrawl_scrape. nextTool identifies further discovery or pagination. Discovery does not execute providers. Use firecrawl_search when you also need web results.";
 var searchSurfaceFindToolsTool = {
   ...findToolsTool,
   description: SEARCH_SURFACE_FIND_TOOLS_DESCRIPTION
@@ -3024,6 +3627,7 @@ async function keylessPost(path2, body, session, originOverride) {
     }
   }
   const headers = {
+    ...AGENT_HINTS_HEADERS,
     ...originHeaders(origin),
     "Content-Type": "application/json"
   };
@@ -3043,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;
@@ -3067,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();
@@ -3091,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) {
@@ -3109,17 +3719,17 @@ async function waitForCrawlCompletionWithOrigin(client, jobId, origin, pollInter
     );
   }
 }
-var feedbackIssueSchema = z7.string().trim().min(1).max(80).regex(
+var feedbackIssueSchema = z8.string().trim().min(1).max(80).regex(
   /^[a-z0-9][a-z0-9_-]*$/,
   "Issue codes must use lowercase letters, numbers, underscores, or hyphens"
 );
-var valuableSourceSchema = z7.object({
-  url: z7.string().url(),
-  reason: z7.string().max(1e3).optional()
+var valuableSourceSchema = z8.object({
+  url: z8.string().url(),
+  reason: z8.string().max(1e3).optional()
 });
-var missingContentSchema = z7.object({
-  topic: z7.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
-  description: z7.string().max(2e3).optional()
+var missingContentSchema = z8.object({
+  topic: z8.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
+  description: z8.string().max(2e3).optional()
 });
 var FEEDBACK_DISABLED_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
 function feedbackEnvEnabled(...keys) {
@@ -3157,24 +3767,25 @@ Records schema-validated quality feedback for a prior \`firecrawl_search\` UUID
 
 Eligibility is limited to successful searches within the feedback age window. The record is idempotent per search ID. Eligible first feedback for a search can refund 1 credit; refunds are subject to the team's daily cap. The response reports whether a refund was applied, along with submission and daily-cap status.
 `,
-    parameters: z7.object({
-      searchId: z7.string().uuid("searchId must be the UUID returned by firecrawl_search"),
-      rating: z7.enum(["good", "bad", "partial"]),
-      valuableSources: z7.array(
-        z7.object({
-          url: z7.string().url(),
-          reason: z7.string().max(1e3).optional()
+    outputSchema: feedbackOutputSchema,
+    parameters: z8.object({
+      searchId: z8.string().uuid("searchId must be the UUID returned by firecrawl_search"),
+      rating: z8.enum(["good", "bad", "partial"]),
+      valuableSources: z8.array(
+        z8.object({
+          url: z8.string().url(),
+          reason: z8.string().max(1e3).optional()
         })
       ).max(50).optional(),
-      missingContent: z7.array(
-        z7.object({
-          topic: z7.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
-          description: z7.string().max(2e3).optional()
+      missingContent: z8.array(
+        z8.object({
+          topic: z8.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
+          description: z8.string().max(2e3).optional()
         })
       ).max(20).optional().describe(
         "Array of specific pieces of content the agent expected to find but did not. One entry per distinct topic. Each entry has a short `topic` and optional longer `description`."
       ),
-      querySuggestions: z7.string().max(2e3).optional()
+      querySuggestions: z8.string().max(2e3).optional()
     }),
     execute: async (args2, { session, log, client: mcpClient }) => {
       const origin = requestOrigin(mcpClient, session);
@@ -3201,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"
       };
@@ -3234,15 +3846,16 @@ Eligibility is limited to successful searches within the feedback age window. Th
           status: response.status,
           feedbackErrorCode: parsed?.feedbackErrorCode
         });
-        return asText3({
+        return structuredText({
           success: false,
           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 asText3(parsed);
+      return structuredText(parsed);
     }
   });
 }
@@ -3273,20 +3886,21 @@ For an Alexandria session, set endpoint to \`alexandria\`, omit jobId, and provi
 
 Returns submission status, feedback ID, and accounting fields.
 `,
-    parameters: z7.object({
-      endpoint: z7.enum(["search", "scrape", "parse", "map", "alexandria"]),
-      jobId: z7.string().uuid("jobId must be the UUID returned by Firecrawl").optional(),
+    outputSchema: feedbackOutputSchema,
+    parameters: z8.object({
+      endpoint: z8.enum(["search", "scrape", "parse", "map", "alexandria"]),
+      jobId: z8.string().uuid("jobId must be the UUID returned by Firecrawl").optional(),
       ...alexandriaFeedbackFields,
-      rating: z7.enum(["good", "bad", "partial"]),
-      issues: z7.array(feedbackIssueSchema).max(20).optional(),
-      tags: z7.array(feedbackIssueSchema).max(20).optional(),
-      note: z7.string().max(4e3).optional(),
-      valuableSources: z7.array(valuableSourceSchema).max(50).optional(),
-      missingContent: z7.array(missingContentSchema).max(50).optional(),
-      querySuggestions: z7.string().max(2e3).optional(),
-      url: z7.string().url().optional(),
-      pageNumbers: z7.array(z7.number().int().positive()).max(100).optional(),
-      metadata: z7.record(z7.string(), z7.unknown()).optional()
+      rating: z8.enum(["good", "bad", "partial"]),
+      issues: z8.array(feedbackIssueSchema).max(20).optional(),
+      tags: z8.array(feedbackIssueSchema).max(20).optional(),
+      note: z8.string().max(4e3).optional(),
+      valuableSources: z8.array(valuableSourceSchema).max(50).optional(),
+      missingContent: z8.array(missingContentSchema).max(50).optional(),
+      querySuggestions: z8.string().max(2e3).optional(),
+      url: z8.string().url().optional(),
+      pageNumbers: z8.array(z8.number().int().positive()).max(100).optional(),
+      metadata: z8.record(z8.string(), z8.unknown()).optional()
     }).superRefine((value, ctx) => {
       if (value.endpoint === "alexandria") {
         const parsed = alexandriaSessionFeedbackSchema.safeParse(value);
@@ -3320,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"
       };
@@ -3368,15 +3983,16 @@ Returns submission status, feedback ID, and accounting fields.
           status: response.status,
           feedbackErrorCode: parsed?.feedbackErrorCode
         });
-        return asText3({
+        return structuredText({
           success: false,
           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 asText3(parsed);
+      return structuredText(parsed);
     }
   });
 }
@@ -3396,27 +4012,28 @@ Start a multi-page crawl at a website URL, poll it to a terminal state, and retu
 
 Crawl results can be large; use conservative limits when full-site coverage is unnecessary. Webhooks and interactive scrape actions are unavailable in safe mode. Returns the crawl ID, status, and page data.
 `,
-  parameters: z7.object({
-    url: z7.string(),
-    prompt: z7.string().optional(),
-    excludePaths: z7.array(z7.string()).optional(),
-    includePaths: z7.array(z7.string()).optional(),
-    maxDiscoveryDepth: z7.number().optional(),
-    sitemap: z7.enum(["skip", "include", "only"]).optional(),
-    limit: z7.number().optional(),
-    allowExternalLinks: z7.boolean().optional(),
-    allowSubdomains: z7.boolean().optional(),
-    crawlEntireDomain: z7.boolean().optional(),
-    delay: z7.number().optional(),
-    maxConcurrency: z7.number().optional(),
+  parameters: z8.object({
+    url: z8.string(),
+    prompt: z8.string().optional(),
+    excludePaths: z8.array(z8.string()).optional(),
+    includePaths: z8.array(z8.string()).optional(),
+    maxDiscoveryDepth: z8.number().optional(),
+    sitemap: z8.enum(["skip", "include", "only"]).optional(),
+    limit: z8.number().optional(),
+    allowExternalLinks: z8.boolean().optional(),
+    allowSubdomains: z8.boolean().optional(),
+    crawlEntireDomain: z8.boolean().optional(),
+    delay: z8.number().optional(),
+    maxConcurrency: z8.number().optional(),
     ...SAFE_MODE ? {} : {
-      webhook: z7.string().optional(),
-      webhookHeaders: z7.record(z7.string(), z7.string()).optional()
+      webhook: z8.string().optional(),
+      webhookHeaders: z8.record(z8.string(), z8.string()).optional()
     },
-    deduplicateSimilarURLs: z7.boolean().optional(),
-    ignoreQueryParameters: z7.boolean().optional(),
+    deduplicateSimilarURLs: z8.boolean().optional(),
+    ignoreQueryParameters: z8.boolean().optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }),
+  outputSchema: crawlOutputSchema,
   execute: async (args2, { session, log, client: mcpClient }) => {
     const origin = requestOrigin(mcpClient, session);
     const { url, ...options } = args2;
@@ -3443,7 +4060,7 @@ Crawl results can be large; use conservative limits when full-site coverage is u
     });
     const crawlId = started?.data?.id;
     if (!crawlId) {
-      return asText3(started?.data ?? {});
+      return structuredText(started?.data ?? {});
     }
     const res = await waitForCrawlCompletionWithOrigin(
       client,
@@ -3452,7 +4069,7 @@ Crawl results can be large; use conservative limits when full-site coverage is u
       pollInterval,
       timeout
     );
-    return asText3(res);
+    return structuredText(res);
   }
 });
 server.addTool({
@@ -3469,7 +4086,8 @@ server.addTool({
   description: `
 Retrieve the current status, progress, and available results for an existing crawl ID. This only reads Firecrawl job state and does not start or modify the crawl.
 `,
-  parameters: z7.object({ id: z7.string() }),
+  outputSchema: crawlOutputSchema,
+  parameters: z8.object({ id: z8.string() }),
   execute: async (args2, {
     session,
     client: mcpClient
@@ -3481,7 +4099,7 @@ Retrieve the current status, progress, and available results for an existing cra
       id,
       requestOrigin(mcpClient, session)
     );
-    return asText3(res);
+    return structuredText(res);
   }
 });
 server.addTool({
@@ -3495,13 +4113,14 @@ server.addTool({
   description: `
 Deprecated compatibility entry point. Use firecrawl_scrape once per known URL with formats: ["json"] and jsonOptions containing the prompt and schema. Use firecrawl_agent for multi-source research when the URLs are not known or the data spans several sites.
 `,
-  parameters: z7.object({
-    urls: z7.array(z7.string()),
-    prompt: z7.string().optional(),
-    schema: z7.record(z7.string(), z7.any()).optional(),
-    allowExternalLinks: z7.boolean().optional(),
-    enableWebSearch: z7.boolean().optional(),
-    includeSubdomains: z7.boolean().optional()
+  outputSchema: deprecatedToolOutputSchema,
+  parameters: z8.object({
+    urls: z8.array(z8.string()),
+    prompt: z8.string().optional(),
+    schema: z8.record(z8.string(), z8.any()).optional(),
+    allowExternalLinks: z8.boolean().optional(),
+    enableWebSearch: z8.boolean().optional(),
+    includeSubdomains: z8.boolean().optional()
   }),
   canList: () => false,
   beforeValidate: () => {
@@ -3517,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: {
@@ -3529,32 +4171,80 @@ 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.
 `,
-  parameters: z7.object({
-    prompt: z7.string().min(1).max(1e4),
-    urls: z7.array(z7.string().url()).optional(),
-    schema: z7.record(z7.string(), z7.any()).optional()
-  }),
+  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(),
+    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,
       origin: requestOrigin(mcpClient, session)
     });
-    return asText3(res);
+    return structuredText(res);
   }
 });
 server.addTool({
@@ -3573,7 +4263,8 @@ Retrieve progress or final results for a \`firecrawl_agent\` job ID. A \`process
 
 Returns job status, progress information, and result data when completed.
 `,
-  parameters: z7.object({ id: z7.string() }),
+  outputSchema: agentStatusOutputSchema,
+  parameters: z8.object({ id: z8.string() }),
   execute: async (args2, { session, log, client: mcpClient }) => {
     const client = getClient(session);
     const { id } = args2;
@@ -3582,7 +4273,7 @@ Returns job status, progress information, and result data when completed.
       `/v2/agent/${encodeURIComponent(id)}`,
       originHeaders(requestOrigin(mcpClient, session))
     );
-    return asText3(res?.data ?? {});
+    return structuredText(res?.data ?? {});
   }
 });
 server.addTool({
@@ -3601,13 +4292,14 @@ Open or reuse a live browser session to navigate a page, click controls, fill fi
 
 This acts on the live site, so actions such as form submission can create persistent external side effects. Returns execution output, stdout/stderr, exit status, and session viewing URLs.
 `,
-  parameters: z7.object({
-    scrapeId: z7.string().trim().min(1).optional(),
-    url: z7.string().trim().url().optional(),
-    prompt: z7.string().trim().min(1).optional(),
-    code: z7.string().trim().min(1).optional(),
-    language: z7.enum(["bash", "python", "node"]).optional(),
-    timeout: z7.number().min(1).max(300).optional(),
+  outputSchema: interactOutputSchema,
+  parameters: z8.object({
+    scrapeId: z8.string().trim().min(1).optional(),
+    url: z8.string().trim().url().optional(),
+    prompt: z8.string().trim().min(1).optional(),
+    code: z8.string().trim().min(1).optional(),
+    language: z8.enum(["bash", "python", "node"]).optional(),
+    timeout: z8.number().min(1).max(300).optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }).refine((data) => Boolean(data.scrapeId) !== Boolean(data.url), {
     message: "Provide either 'url' (interact directly) or 'scrapeId' (reuse a previous scrape), not both."
@@ -3639,14 +4331,14 @@ This acts on the live site, so actions such as form submission can create persis
       });
       scrapeId = scraped?.metadata?.scrapeId;
       if (!scrapeId) {
-        return asText3({
+        return structuredText({
           error: "Could not open an interact session: the scrape did not return a scrapeId. Try firecrawl_scrape first, then pass its scrapeId.",
           url
         });
       }
     }
     if (!scrapeId) {
-      return asText3({
+      return structuredText({
         error: "Could not open an interact session: missing scrapeId.",
         url
       });
@@ -3660,15 +4352,15 @@ This acts on the live site, so actions such as form submission can create persis
     if (timeout != null) interactArgs.timeout = timeout;
     const res = await client.interact(activeScrapeId, interactArgs);
     if (openedFromUrl && res && typeof res === "object" && !Array.isArray(res)) {
-      return asText3({
+      return structuredText({
         ...res,
         scrapeId: activeScrapeId
       });
     }
     if (openedFromUrl) {
-      return asText3({ scrapeId: activeScrapeId, result: res });
+      return structuredText({ scrapeId: activeScrapeId, result: res });
     }
-    return asText3(res);
+    return structuredText(res);
   }
 });
 server.addTool({
@@ -3685,8 +4377,9 @@ server.addTool({
   description: `
 Stop the live interact session associated with a \`scrapeId\` and release its resources. Returns a success confirmation.
 `,
-  parameters: z7.object({
-    scrapeId: z7.string()
+  outputSchema: interactStopOutputSchema,
+  parameters: z8.object({
+    scrapeId: z8.string()
   }),
   execute: async (args2, { session, log, client: mcpClient }) => {
     const client = getClient(session);
@@ -3696,7 +4389,7 @@ Stop the live interact session associated with a \`scrapeId\` and release its re
       `/v2/scrape/${encodeURIComponent(scrapeId)}/interact`,
       originHeaders(requestOrigin(mcpClient, session))
     );
-    return asText3(res?.data ?? {});
+    return structuredText(res?.data ?? {});
   }
 });
 server.addTool({
@@ -3717,11 +4410,14 @@ Local MCP reads \`filePath\` from the server filesystem. Hosted MCP uses two cal
 
 Set \`redactPII\` to request redaction of personally identifiable information in the returned content. \`zeroDataRetention\` requires an eligible authenticated account; omit it for anonymous keyless use. Returns upload instructions for hosted phase one or parsed document content for the final call. Authenticated final responses can include a \`data.metadata.scrapeId\` for optional parse feedback.
 `,
+  outputSchema: parseOutputSchema,
   parameters: parseParamsSchema,
   execute: async (args2, { session, log, client: mcpClient }) => {
     const origin = requestOrigin(mcpClient, session);
     if (process.env.CLOUD_SERVICE === "true") {
-      return executeHostedParse(args2, session, log, origin);
+      return structuredJsonText(
+        await executeHostedParse(args2, session, log, origin)
+      );
     }
     const apiUrl = process.env.FIRECRAWL_API_URL;
     if (!apiUrl) {
@@ -3748,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}`;
@@ -3766,20 +4465,28 @@ 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 {
-      return asText3(JSON.parse(responseText));
+      return structuredText(JSON.parse(responseText));
     } catch {
-      return responseText;
+      return withStructured(responseText, { raw: responseText });
     }
   }
 });
 function registerMarketplaceSearchTool(registrar, getClientFn) {
   registrar.addTool({
     name: "firecrawl_search",
+    _meta: { "anthropic/alwaysLoad": true },
     annotations: {
       title: "Firecrawl web search",
       readOnlyHint: true,
@@ -3795,7 +4502,8 @@ ${ALEXANDRIA_SEARCH_INSTRUCTIONS}
 
 Returns result groups in \`data\` and an operation \`id\`.
 `,
-    parameters: z7.object({ ...searchToolBaseFields }).strict().refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE).refine(
+    outputSchema: searchOutputSchema,
+    parameters: z8.object({ ...searchToolBaseFields }).strict().refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE).refine(
       searchQueryIsValid,
       "A query is required. Use firecrawl_find_tools to browse the catalogue."
     ),
@@ -3846,7 +4554,7 @@ Returns result groups in \`data\` and an operation \`id\`.
       );
       const context = { tool: "firecrawl_search" };
       const httpRes = exchangeSource ? await relayExchangeError(postSearch, context) : await relayTermsRequired(postSearch, context);
-      return compactText(httpRes?.data ?? {});
+      return structuredCompact(httpRes?.data ?? {});
     }
   });
 }
@@ -3918,10 +4626,10 @@ if (searchProfileEnabled) {
         stateless: true
       }
     });
-  } catch (error) {
+  } catch (error2) {
     console.error(
       `[search-profile] failed to start on port ${searchProfile.port}; the full surface is unaffected`,
-      error
+      error2
     );
   }
 }