Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: baseScrapeOptions
diff --git a/apps/api/src/search/alexandria.test.ts b/apps/api/src/search/alexandria.test.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.py
index 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"] == expected
payload = 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 == NEXT
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index 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 policy
profile: 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 events
Returns:
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 None
if 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 filter
location: 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.py
index 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]] = None
credits_cost: int = Field(alias="creditsCost")
id: Optional[str] = None
name: str
@@ -2268,6 +2270,7 @@ class SearchRequest(BaseModel):
query: str
domain_tools: Optional[bool] = Field(default=None, alias="domainTools")
+ tool_detail: Optional[Literal["summary", "full"]] = Field(default=None, alias="toolDetail")
sources: Optional[List[SourceOption]] = None
categories: Optional[List[CategoryOption]] = None
include_domains: Optional[List[str]] = None
diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.py
index 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[st
scrape_data["location"] = value
else:
scrape_data["location"] = value.model_dump(exclude_none=True)
+ elif key == "tool_detail":
+ scrape_data["toolDetail"] = value
elif key == "domain_tools":
# Only ever sent when explicitly enabled; never emit `false`.
if value: