Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(alexandria): Add configurable tool discovery detail (#4704)
Developers Digest3e192916b659
diff --git a/apps/api/src/controllers/v2/scrape.ts b/apps/api/src/controllers/v2/scrape.tsindex 69dee92b6..0c3aa1eb5 100644--- a/apps/api/src/controllers/v2/scrape.ts+++ b/apps/api/src/controllers/v2/scrape.ts@@ -706,6 +706,7 @@ export async function scrapeController(? await discoverTools({teamId: req.auth.team_id,+ toolDetail: req.body.toolDetail,urls: [...new Set([diff --git a/apps/api/src/controllers/v2/search-schema.test.ts b/apps/api/src/controllers/v2/search-schema.test.tsindex 5b91617ca..769c48c30 100644--- a/apps/api/src/controllers/v2/search-schema.test.ts+++ b/apps/api/src/controllers/v2/search-schema.test.ts@@ -2,6 +2,17 @@ import { describe, expect, it } from "vitest";import { searchRequestSchema } from "./types";describe("searchRequestSchema highlights", () => {+ it.each(["summary", "full"])("accepts %s tool detail", toolDetail => {+ expect(+ searchRequestSchema.parse({ query: "records", toolDetail }).toolDetail,+ ).toBe(toolDetail);+ });+ it("rejects unknown tool detail", () => {+ expect(+ searchRequestSchema.safeParse({ query: "records", toolDetail: "all" })+ .success,+ ).toBe(false);+ });it("preserves an omitted value for integration and rollout selection", () => {const request = searchRequestSchema.parse({ query: "firecrawl" });diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.tsindex f4b30fbbd..982b2107e 100644--- a/apps/api/src/controllers/v2/search.ts+++ b/apps/api/src/controllers/v2/search.ts@@ -391,6 +391,7 @@ async function searchControllerInner(scrapeOptions: req.body.scrapeOptions,highlights: req.body.highlights,domainTools: req.body.domainTools,+ toolDetail: req.body.toolDetail,timeout: req.body.timeout,},{diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex 1ff4ef484..cc4e49ae1 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -1131,6 +1131,7 @@ const scrapeRequestSchemaBase = baseScrapeOptions.extend({integration: integrationSchema.optional().transform(val => val || null),zeroDataRetention: z.boolean().optional(),domainTools: z.boolean().optional(),+ toolDetail: z.enum(["summary", "full"]).optional(),__agentInterop: z.object({auth: z.string(),@@ -2410,6 +2411,7 @@ export const searchRequestSchema = z// whether generated highlights are returned or only run in shadow mode.highlights: z.boolean().optional(),domainTools: z.boolean().optional(),+ toolDetail: z.enum(["summary", "full"]).optional(),__searchPreviewToken: z.string().optional(),threatProtection: threatProtectionOverrideSchema.optional(),scrapeOptions: baseScrapeOptionsdiff --git a/apps/api/src/search/alexandria.test.ts b/apps/api/src/search/alexandria.test.tsnew file mode 100644index 000000000..fc5014ec4--- /dev/null+++ b/apps/api/src/search/alexandria.test.ts@@ -0,0 +1,146 @@+import { describe, it, expect, vi, beforeEach } from "vitest";+import { discoverTools } from "./alexandria";+import { exchangeRequest } from "../services/alexandria/client";+vi.mock("../services/alexandria/client", () => ({ exchangeRequest: vi.fn() }));+const request = vi.mocked(exchangeRequest);+const logger = { warn: vi.fn() } as any;+const next = {+ provider: "firecrawl",+ capability: "find-tools",+ options: {+ providers: ["sample"],+ capabilities: ["records/search"],+ expand: ["options", "response", "examples"],+ },+};+const tool = {+ provider: "sample",+ capability: "records/search",+ name: "Records",+ description: "Search records",+ creditsCost: 5,+ perRecord: false,+ options: [{ name: "query", type: "string" }],+ response: { about: "Records", key: "records", fields: [] },+ example: { query: "test" },+ next,+};+const input = { teamId: "team", query: "records", limit: 5, timeoutMs: 10000 };+beforeEach(() => vi.clearAllMocks());+it.each([undefined, "summary", "full"] as const)(+ "supports %s discovery detail",+ async toolDetail => {+ request.mockResolvedValue({+ status: 200,+ body: { success: true, creditsCost: 0, data: { items: [tool] } },+ });+ const result = await discoverTools({ ...input, toolDetail }, logger);+ expect(request).toHaveBeenCalledTimes(1);+ expect(request.mock.calls[0][0].body).toMatchObject({+ provider: "firecrawl",+ capability: "find-tools",+ options: {+ query: "records",+ expand:+ toolDetail === "full" ? ["options", "response", "examples"] : [],+ },+ });+ expect(result.items[0]).toMatchObject({+ id: "sample/records/search",+ matchedBy: ["semantic"],+ });+ if (toolDetail === "full")+ expect(result.items[0]).toMatchObject({+ options: tool.options,+ response: tool.response,+ });+ else {+ expect(result.items[0]).toMatchObject({ next });+ for (const field of ["options", "response", "example"])+ expect(result.items[0]).not.toHaveProperty(field);+ }+ },+);+it("keeps a warning when discovery fails", async () => {+ request.mockResolvedValue({ status: 503, body: {} });+ const result = await discoverTools(input, logger);+ expect(result.items).toEqual([]);+ expect(result.warning).toBeTruthy();+});+it.each([undefined, "full"] as const)(+ "deduplicates semantic and domain tools with %s detail",+ async toolDetail => {+ request.mockImplementation(async args =>+ args.path === "/v1/skills/resolve"+ ? {+ status: 200,+ body: {+ skills: [+ {+ id: "sample",+ matchedDomains: ["example.com"],+ domainCapabilities: { "example.com": ["records/search"] },+ },+ ],+ },+ }+ : {+ status: 200,+ body: { success: true, creditsCost: 0, data: { items: [tool] } },+ },+ );+ const result = await discoverTools(+ { ...input, toolDetail, urls: ["https://example.com/records"] },+ logger,+ );+ expect(result.items).toHaveLength(1);+ expect(result.items[0]).toMatchObject({+ matchedBy: ["semantic", "domain"],+ matchedUrls: ["https://example.com/records"],+ next,+ });+ if (toolDetail === "full")+ expect(result.items[0]).toMatchObject({+ options: tool.options,+ response: tool.response,+ });+ else expect(result.items[0]).not.toHaveProperty("options");+ expect(+ request.mock.calls+ .filter(([args]) => args.path === "/v1/retrieve")+ .map(([args]) => (args.body as any).options.expand),+ ).toEqual(+ toolDetail === "full"+ ? [next.options.expand, next.options.expand]+ : [[], []],+ );+ },+);++it("keeps tools when optional navigation is absent, extended or malformed", async () => {+ const variants = [+ undefined,+ { ...next, label: "Inspect" },+ { provider: "firecrawl" },+ ];+ request.mockResolvedValue({+ status: 200,+ body: {+ success: true,+ creditsCost: 0,+ data: {+ items: variants.map((next, i) => ({+ ...tool,+ capability: `records/${i}`,+ next,+ })),+ },+ },+ });+ const result = await discoverTools(input, logger);+ expect(result.items).toHaveLength(3);+ expect(result.warning).toBeUndefined();+ expect(result.items[1].next).toMatchObject({ ...next, label: "Inspect" });+ expect(result.items[0].next).toBeUndefined();+ expect(result.items[2].next).toBeUndefined();+});diff --git a/apps/api/src/search/alexandria.ts b/apps/api/src/search/alexandria.tsindex 21f0eff0b..dc1a30e37 100644--- a/apps/api/src/search/alexandria.ts+++ b/apps/api/src/search/alexandria.ts@@ -3,6 +3,7 @@ import type { Logger } from "winston";import { exchangeRequest } from "../services/alexandria/client";import {toolSchema,+ toolSummarySchema,type DiscoveredTool,} from "../services/alexandria/contracts";@@ -36,6 +37,7 @@ export function isToolsOnlySearch(export async function discoverTools(input: {teamId: string;+ toolDetail?: "summary" | "full";query?: string;urls?: string[];limit: number;@@ -63,7 +65,10 @@ export async function discoverTools(options: {...options,level: "tools",- expand: ["options", "response", "examples"],+ expand:+ input.toolDetail === "full"+ ? ["options", "response", "examples"]+ : [],limit: Math.min(input.limit, 24),},},@@ -74,12 +79,16 @@ export async function discoverTools(.object({success: z.literal(true),creditsCost: z.literal(0),- data: z.object({ items: z.array(toolSchema) }),+ data: z.object({+ items: z.array(+ input.toolDetail === "full" ? toolSchema : toolSummarySchema,+ ),+ }),}).parse(result.body).data.items;};const merge = (- tool: z.infer<typeof toolSchema>,+ tool: z.infer<typeof toolSchema> | z.infer<typeof toolSummarySchema>,source: "semantic" | "domain",urls: string[] = [],) => {@@ -108,81 +117,8 @@ export async function discoverTools(};if (input.query) {try {- const result = await exchangeRequest({- teamId: input.teamId,- path: `/v1/discover?q=${encodeURIComponent(input.query)}&limit=${Math.min(input.limit, 24)}`,- timeoutMs: remaining(),- });- if (result.status !== 200)- throw new Error("Semantic discovery unavailable");- const hits = z- .object({- capabilities: z.array(- z.object({- provider: z.string(),- address: z.string(),- cohorts: z.array(z.string()).default([]),- }),- ),- })- .parse(result.body)- .capabilities.slice(0, Math.min(input.limit, 24));- // Four concurrent contract lookups, preserving semantic rank.- for (let i = 0; i < hits.length; i += 4) {- const contracts = await Promise.all(- hits.slice(i, i + 4).map(async hit => {- try {- if (!hit.cohorts.length)- return (- await lookup({- providers: [hit.provider],- capabilities: [hit.address],- })- )[0];- const parts = [- hit.cohorts[0],- hit.provider,- ...hit.address.split("/"),- ];- if (- parts.some(part => !/^[a-zA-Z0-9_-][a-zA-Z0-9._-]*$/.test(part))- )- throw new Error("Invalid tool identifier");- const contract = await exchangeRequest({- teamId: input.teamId,- path: `/v1/discover/${parts.map(encodeURIComponent).join("/")}`,- timeoutMs: remaining(),- });- if (contract.status !== 200)- throw new Error("Tool contract unavailable");- const body = z- .object({- label: z.string(),- whenToUse: z.string(),- returns: z.unknown(),- })- .passthrough()- .parse(contract.body);- const tool = toolSchema.parse({- ...body,- name: body.label,- description: body.whenToUse,- response: body.returns,- });- if (- tool.provider !== hit.provider ||- tool.capability !== hit.address- )- throw new Error("Tool identity mismatch");- return tool;- } catch {- failed = true;- return undefined;- }- }),- );- for (const tool of contracts) if (tool) merge(tool, "semantic");- }+ for (const tool of await lookup({ query: input.query }))+ merge(tool, "semantic");} catch (error) {failed = true;logger.warn("Semantic tool discovery unavailable", { error });diff --git a/apps/api/src/search/execute.ts b/apps/api/src/search/execute.tsindex d5517c431..2e14eae95 100644--- a/apps/api/src/search/execute.ts+++ b/apps/api/src/search/execute.ts@@ -45,6 +45,7 @@ interface SearchOptions {scrapeOptions?: ScrapeOptions;highlights?: boolean;domainTools?: boolean;+ toolDetail?: "summary" | "full";timeout: number;}@@ -252,6 +253,7 @@ export async function executeSearch() {const discovery = await discoverTools({+ toolDetail: options.toolDetail,teamId,limit,query: wantsTools ? query : undefined,diff --git a/apps/api/src/services/alexandria/contracts.ts b/apps/api/src/services/alexandria/contracts.tsindex 58a6fcf3d..61d1676b9 100644--- a/apps/api/src/services/alexandria/contracts.ts+++ b/apps/api/src/services/alexandria/contracts.ts@@ -68,7 +68,19 @@ export const toolSchema = z.passthrough(),}).passthrough();-export type DiscoveredTool = z.infer<typeof toolSchema> & {+export const toolSummarySchema = toolSchema+ .omit({ options: true, response: true })+ .strip()+ .extend({+ next: callSchema.passthrough().optional().catch(undefined),+ attribution: z.unknown().optional(),+ recordsPerUnit: z.number().positive().optional(),+ zeroDataRetentionCreditsCost: credits.optional(),+ });+export type DiscoveredTool = (+ | z.infer<typeof toolSchema>+ | z.infer<typeof toolSummarySchema>+) & {id: string;matchedBy: ("semantic" | "domain")[];matchedUrls: string[];diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/tools.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/tools.unit.test.tsindex 4439b9c64..7ee596903 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/tools.unit.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/tools.unit.test.ts@@ -150,6 +150,10 @@ afterAll(async () => {});describe("Alexandria contracts and execution", () => {+ test.each(["summary", "full"] as const)("forwards %s discovery detail", async toolDetail => {+ await client.search("records", { toolDetail });+ expect(sent.at(-1)?.body).toMatchObject({ toolDetail });+ });test("returns complete unified tools and warning beside web results", async () => {const result = await client.search("podcasts", {sources: ["web", { type: "alexandria" }],diff --git a/apps/js-sdk/firecrawl/src/v2/methods/search.ts b/apps/js-sdk/firecrawl/src/v2/methods/search.tsindex 6302f140f..495e9d95e 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/search.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/search.ts@@ -27,6 +27,7 @@ function prepareSearchPayload(req: SearchRequest): Record<string, unknown> {const payload: Record<string, unknown> = {query: req.query,};+ if (req.toolDetail != null) payload.toolDetail = req.toolDetail;if (req.domainTools != null) payload.domainTools = req.domainTools;if (req.sources) payload.sources = req.sources;if (req.categories) payload.categories = req.categories;diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 5b8cf7ab3..736f62917 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -285,8 +285,10 @@ export interface ScrapeOptions {};integration?: string;origin?: string;- /** Include domain-matched Alexandria contracts for this URL in `tools`. Default off. */+ /** Include domain-matched Alexandria tools for this URL in `tools`. Default off. */domainTools?: boolean;+ /** Tool summaries by default; full includes input/output contracts. */+ toolDetail?: "summary" | "full";}export type RedactPIIEntity =@@ -358,6 +360,7 @@ export type ParseOptions = Omit<| "lockdown"| "proxy"| "threatProtection"+ | "toolDetail"> & {formats?: ParseFormatOption[];proxy?: "basic" | "auto";@@ -826,6 +829,7 @@ export interface SearchData {/** A complete tool contract returned by semantic or contextual discovery. */export interface DiscoveredTool {+ next?: AlexandriaCall;id?: string;provider: string;capability: string;@@ -833,7 +837,7 @@ export interface DiscoveredTool {description: string;creditsCost: number;perRecord: boolean;- options: Array<{+ options?: Array<{name: string;type: string;required?: boolean;@@ -970,8 +974,10 @@ export interface CategoryOption {export interface SearchRequest {query: string;- /** Include domain-matched contracts in tools alongside semantic matches. */+ /** Include domain-matched tools in tools alongside semantic matches. */domainTools?: boolean;+ /** Tool summaries by default; full includes input/output contracts. */+ toolDetail?: "summary" | "full";sources?: Array<"web" | "news" | "images" | "alexandria"| { type: "web" | "news" | "images" | "alexandria" }@@ -998,7 +1004,7 @@ export interface SearchRequest {timeout?: number; // ms/** Generate query-relevant highlights for search results. Defaults to true. */highlights?: boolean;- scrapeOptions?: ScrapeOptions;+ scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;/*** Enterprise search options. Use `["zdr"]` for end-to-end Zero Data* Retention or `["anon"]` for anonymized search. Must be enabled for@@ -1027,7 +1033,7 @@ export interface CrawlOptions {delay?: number | null;maxConcurrency?: number | null;webhook?: string | WebhookConfig | null;- scrapeOptions?: ScrapeOptions | null;+ scrapeOptions?: Omit<ScrapeOptions, "toolDetail"> | null;regexOnFullURL?: boolean;zeroDataRetention?: boolean;integration?: string;@@ -1051,7 +1057,7 @@ export interface CrawlJob {}export interface BatchScrapeOptions {- options?: ScrapeOptions;+ options?: Omit<ScrapeOptions, "toolDetail">;webhook?: string | WebhookConfig;appendToId?: string;ignoreInvalidURLs?: boolean;@@ -1201,7 +1207,7 @@ export interface MonitorScrapeTarget {id?: string;type: "scrape";urls: string[];- scrapeOptions?: ScrapeOptions;+ scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;}export interface MonitorCrawlTarget {@@ -1209,7 +1215,7 @@ export interface MonitorCrawlTarget {type: "crawl";url: string;crawlOptions?: CrawlOptions;- scrapeOptions?: ScrapeOptions;+ scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;}export interface MonitorSearchTarget {diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_tools.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_tools.pyindex 712d98f83..ca0e22c9b 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_tools.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_tools.py@@ -37,7 +37,7 @@ async def test_search_and_progressive_lookup(async_client, monkeypatch):try:async def post(url, **kwargs): return httpx.Response(200,json=payload(kwargs['json']))monkeypatch.setattr(client._v2_client.async_http_client._client,'post',post)- search=await client.search('podcasts',sources=['alexandria'],domain_tools=True)+ search=await client.search('podcasts',sources=['alexandria'],domain_tools=True,tool_detail='full')found=await client.find_tools(providers=['particle'],limit=2)result=await client.scrape(alexandria=found.items[0]['next'],request_id='walk-1')with pytest.raises(ValueError, match='URL cannot be empty'):@@ -46,7 +46,7 @@ async def test_search_and_progressive_lookup(async_client, monkeypatch):await client._v2_client.async_http_client.close()else:monkeypatch.setattr('requests.post',lambda url,**kwargs:response(200,payload(kwargs['json'])))- search=client.search('podcasts',sources=['alexandria'],domain_tools=True)+ search=client.search('podcasts',sources=['alexandria'],domain_tools=True,tool_detail='full')found=client.find_tools(providers=['particle'],limit=2)result=client.scrape(alexandria=found.items[0]['next'],request_id='walk-1')with pytest.raises(ValueError, match='URL cannot be empty'):@@ -57,6 +57,7 @@ async def test_search_and_progressive_lookup(async_client, monkeypatch):assert search.tools[1].when_to_use=='Analyst ratings for a ticker'assert search.tools[1].label=='Ratings'assert calls[0]['domainTools'] is True+ assert calls[0]['toolDetail'] == 'full'assert calls[-1]['alexandria']==[NEXT]assert 'request_id' not in calls[-1]assert result.request_id=='walk-1'@@ -210,3 +211,14 @@ async def test_alexandria_transport_timeout(async_client, timeout, expected):assert client.post.call_args.kwargs["timeout"] == expectedpayload = client.post.call_args.args[1]assert payload.get("timeout") == timeout+[email protected]('detail', ['summary', 'full'])+def test_discovery_detail_serialization(detail):+ from firecrawl.v2.types import ScrapeOptions, SearchRequest, DiscoveredTool+ from firecrawl.v2.utils.validation import prepare_scrape_options+ from firecrawl.v2.methods.search import _prepare_search_request+ assert prepare_scrape_options(ScrapeOptions(tool_detail=detail))['toolDetail'] == detail+ assert _prepare_search_request(SearchRequest(query='records', tool_detail=detail))['toolDetail'] == detail+ summary = {key:value for key,value in TOOL.items() if key not in ('options','response','examples')}+ summary['next'] = NEXT+ assert DiscoveredTool(**summary).next == NEXTdiff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex ad8b6e4e1..f1904d3c0 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -184,6 +184,7 @@ class FirecrawlClient:audit_metadata: Optional[AuditMetadata] = None,integration: Optional[str] = None,domain_tools: Optional[bool] = None,+ tool_detail: Optional[Literal["summary", "full"]] = None,) -> Union[Document, AlexandriaScrapeData]:"""Scrape a single URL and return the document.@@ -211,6 +212,7 @@ class FirecrawlClient:lockdown: Serve only previously cached results; never make outbound requests. Returns 404 SCRAPE_LOCKDOWN_CACHE_MISS on cache miss.threat_protection: Enterprise per-request override of the team's threat protection policyprofile: Browser profile for persistent state (e.g. {"name": "my-profile", "saveChanges": True})+ tool_detail: "summary" (default) returns compact tool summaries; "full" includes contracts when domain discovery is enabled.audit_metadata: Metadata to include in SIEM logging eventsReturns:Document@@ -242,8 +244,9 @@ class FirecrawlClient:audit_metadata=audit_metadata,integration=integration,domain_tools=domain_tools,+ tool_detail=tool_detail,).items() if v is not None}- ) if any(v is not None for v in [formats, headers, include_tags, exclude_tags, only_main_content, timeout, wait_for, mobile, parsers, actions, location, skip_tls_verification, remove_base64_images, fast_mode, use_mock, block_ads, proxy, max_age, store_in_cache, lockdown, threat_protection, profile, audit_metadata, integration, domain_tools]) else None+ ) if any(v is not None for v in [formats, headers, include_tags, exclude_tags, only_main_content, timeout, wait_for, mobile, parsers, actions, location, skip_tls_verification, remove_base64_images, fast_mode, use_mock, block_ads, proxy, max_age, store_in_cache, lockdown, threat_protection, profile, audit_metadata, integration, domain_tools, tool_detail]) else Noneif alexandria is not None:if url is not None or auto_resume is not None or (options and set(options.model_dump(exclude_none=True, exclude_unset=True)) - {"timeout", "integration"}):raise ValueError("alexandria cannot be combined with URL scrape options")@@ -468,6 +471,7 @@ class FirecrawlClient:*,sources: Optional[List[SourceOption]] = None,domain_tools: Optional[bool] = None,+ tool_detail: Optional[Literal["summary", "full"]] = None,categories: Optional[List[CategoryOption]] = None,include_domains: Optional[List[str]] = None,exclude_domains: Optional[List[str]] = None,@@ -488,6 +492,7 @@ class FirecrawlClient:Args:query: Search query string+ tool_detail: "summary" (default) returns compact tool summaries with a follow-up request; "full" includes contracts immediately.limit: Maximum number of results to return (default: 5)tbs: Time-based search filterlocation: Location string for search@@ -509,6 +514,7 @@ class FirecrawlClient:query=query,sources=sources,domain_tools=domain_tools,+ tool_detail=tool_detail,categories=categories,include_domains=include_domains,exclude_domains=exclude_domains,diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 9d367ee27..cd02c6084 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -929,6 +929,7 @@ class ScrapeOptions(BaseModel):# Enables Alexandria domain-tool discovery/execution for this scrape.# Omitted from the serialized request entirely when unset or False.domain_tools: Optional[bool] = Field(default=None, alias="domainTools")+ tool_detail: Optional[Literal["summary", "full"]] = Field(default=None, alias="toolDetail")model_config = {"populate_by_name": True}@@ -1068,6 +1069,7 @@ class ExchangeSearchResult(BaseModel):class DiscoveredTool(ExchangeSearchResult):+ next: Optional[Dict[str, Any]] = Nonecredits_cost: int = Field(alias="creditsCost")id: Optional[str] = Nonename: str@@ -2268,6 +2270,7 @@ class SearchRequest(BaseModel):query: strdomain_tools: Optional[bool] = Field(default=None, alias="domainTools")+ tool_detail: Optional[Literal["summary", "full"]] = Field(default=None, alias="toolDetail")sources: Optional[List[SourceOption]] = Nonecategories: Optional[List[CategoryOption]] = Noneinclude_domains: Optional[List[str]] = Nonediff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.pyindex 6397e8d54..093aa2ce2 100644--- a/apps/python-sdk/firecrawl/v2/utils/validation.py+++ b/apps/python-sdk/firecrawl/v2/utils/validation.py@@ -814,6 +814,8 @@ def prepare_scrape_options(options: Optional[ScrapeOptions]) -> Optional[Dict[stscrape_data["location"] = valueelse:scrape_data["location"] = value.model_dump(exclude_none=True)+ elif key == "tool_detail":+ scrape_data["toolDetail"] = valueelif key == "domain_tools":# Only ever sent when explicitly enabled; never emit `false`.if value: