From 4a0490713e7f77b1740b5c091e1e5cf24cebec2b Mon Sep 17 00:00:00 2001 From: Developers Digest <124798203+developersdigest@users.noreply.github.com> Date: Tue, 15 Sep 2026 08:29:53 -0400 Subject: [PATCH 1/5] Document Alexandria search-to-scrape agent workflow --- beta-skills/firecrawl-alexandria/SKILL.md | 64 ++++++++++++++++++++--- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/beta-skills/firecrawl-alexandria/SKILL.md b/beta-skills/firecrawl-alexandria/SKILL.md index f07c3fb647..e872ff2073 100644 --- a/beta-skills/firecrawl-alexandria/SKILL.md +++ b/beta-skills/firecrawl-alexandria/SKILL.md @@ -11,15 +11,65 @@ Use `FIRECRAWL_API_KEY` or existing Firecrawl login credentials. Never print cre ## Discover Before Executing +Default to search with domain-tool discovery enabled. In this beta, plain `search` sends both `web` and `alexandria` sources with `domainTools: true`. Use `--domain-tools` explicitly in agent examples so this remains clear, including when selecting only web results. + +### Search and discover tools for result domains + +```sh +npx firecrawl-cli@alexandria search "Zillow homes for sale in Austin" --domain-tools --json +``` + +Inspect the web results and returned tool contracts. Domain-tool discovery finds tools for the domains in those results. It does not execute the tools. If using `--sources web`, keep `--domain-tools` to retain domain lookup; `--sources web` alone opts out of Alexandria discovery. + +### Semantic tool lookup + +When the task describes a capability rather than a known URL, search the Alexandria source: + +```sh +npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --sources alexandria --json +``` + +Describe the data capability in the discovery query; keep exact street addresses, record IDs, and other execution arguments for the selected tool. For example, discover "residential property prices near an address", then resolve the user's address using the returned lookup contract. Do not claim rental support if the contract only supports for-sale listings. + +This is semantic tool discovery, not a provider execution. Read the returned providers and capabilities rather than guessing a provider from a keyword. + +### Lookup tools for a known domain + ```sh -npx firecrawl-cli@alexandria search "GDP" --json -npx firecrawl-cli@alexandria find-tools --options '{"providers":["fred"]}' --pretty -npx firecrawl-cli@alexandria find-tools https://example.com --pretty +npx firecrawl-cli@alexandria find-tools https://www.zillow.com --pretty +npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"level":"tools"}' --pretty ``` -Search defaults to web results plus Alexandria tools and domain-tool discovery. Inspect both; discovery does not execute the returned provider tools. Use `--sources web` for web-only search or `--sources alexandria` for tool-only discovery. Search itself can consume credits. For URL scraping with related tool discovery, use `scrape https://example.com --domain-tools --json` after the same beta prefix. +`find-tools` looks up URLs, providers, groups, and tool contracts. Use semantic `search --sources alexandria` for a natural-language query; do not pass a search phrase as a URL to `find-tools`. + +### Optional tool discovery alongside a scrape + +```sh +npx firecrawl-cli@alexandria scrape https://www.zillow.com --domain-tools --json +``` + +Enable `--domain-tools` when a URL scrape should also return related tool contracts and the team has access. If the API refuses the feature, report the access requirement; do not repeatedly retry. A normal URL scrape does not enable this automatically. Inspect the complete JSON for both scraped content and tool metadata; discovering a tool does not execute it. Search and URL scraping can consume credits. + +Read returned `data.tools` contracts and any tool metadata before choosing a provider/capability. Use their exact input schema, pricing and access requirements; never invent options or assume a provider is free. Follow returned Find Tools requests with `find-tools --request ''`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution. + +## Search → Inspect → Scrape + +Use the two discovery paths above inside this skill. Choose semantic lookup for a capability described in words, or domain lookup when a relevant website is known. Default search combines web results, semantic tools, and domain tools. + +1. Search once and inspect the returned tool identities and descriptions. A related topic alone does not mean the tool can answer the question. +2. Fetch only the selected provider's or capability's contract with `find-tools`. Omit `expand` for compact results; request `"expand":["options","response"]` only for the selected capability. Load examples only when needed. +3. Check coverage, required inputs, credits, and terms. Use the provider's lookup tool to obtain IDs; never invent an ASIN, zpid, store ID, or opportunity ID. +4. Execute the chosen tool through `scrape --alexandria`, using the exact capability and options returned by discovery. Check per-call errors and receipts before describing the result as successful. +5. If no tool covers the task, stop catalogue execution and use ordinary web search or URL scraping. Do not make a paid call merely to see whether an unrelated tool might work. + +For example, after discovery confirms Zillow's address lookup contract: + +```sh +npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"capabilities":["properties/locations"],"level":"tools","expand":["options","response"]}' --json +npx firecrawl-cli@alexandria scrape --alexandria zillow/properties/locations --options '{"query":"800 Haight Street San Francisco","count":3}' --json +``` -Read the returned `data.tools` contracts before choosing a provider/capability. Use their exact input schema, pricing and access requirements; never invent options or assume a provider is free. Follow returned Find Tools requests with `find-tools --request ''`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution. +This resolves an address; it does not itself return nearby rental prices. Continue only with supported capabilities and identifiers actually returned by the tool. If a prerequisite lookup is unavailable, explain the missing input instead of guessing it. ## Execute Within The User's Budget @@ -28,10 +78,10 @@ Obtain approval before paid execution unless the user has already authorized the Once the discovered contract confirms the capability and options: ```sh -npx firecrawl-cli@alexandria scrape --alexandria fred/series/observations --options '{"series_id":"GDP"}' --request-id gdp-beta-1 --json +npx firecrawl-cli@alexandria scrape --alexandria fred/series/observations --options '{"series_id":"GDP"}' --json ``` -Choose a new unique request ID for each new logical execution; the ID above is only an example. Preserve the ID printed on stderr and reuse it only for identical retries, including options and call order. For batches, repeat `--alexandria` and pair each call with a positional `--options` object (maximum 10 calls). +The CLI generates request IDs automatically. Preserve the ID printed on stderr and reuse it only for identical retries, including options and call order. For batches, repeat `--alexandria` and pair each call with a positional `--options` object (maximum 10 calls). Inspect the full response, including `data.alexandria`, per-call errors and any credit/charge receipt. A successful HTTP response does not guarantee every call succeeded. Preserve receipts and request IDs in the result summary. From 6209ca02425eeb0804740e76be97d93e8dcdd063 Mon Sep 17 00:00:00 2001 From: Developers Digest <124798203+developersdigest@users.noreply.github.com> Date: Tue, 15 Sep 2026 08:59:28 -0400 Subject: [PATCH 2/5] Document progressive discovery in Alexandria skill --- beta-skills/firecrawl-alexandria/SKILL.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/beta-skills/firecrawl-alexandria/SKILL.md b/beta-skills/firecrawl-alexandria/SKILL.md index e872ff2073..029468a78d 100644 --- a/beta-skills/firecrawl-alexandria/SKILL.md +++ b/beta-skills/firecrawl-alexandria/SKILL.md @@ -42,6 +42,18 @@ npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"leve `find-tools` looks up URLs, providers, groups, and tool contracts. Use semantic `search --sources alexandria` for a natural-language query; do not pass a search phrase as a URL to `find-tools`. +### Progressive catalogue discovery + +When the provider is unknown or a result exposes more groups/tools, narrow the catalogue progressively instead of loading every contract: + +```sh +npx firecrawl-cli@alexandria find-tools --options '{"level":"providers"}' --json +``` + +Inspect the compact results and follow the relevant returned `next` request with `find-tools --request ''`. Pass the complete request object unchanged, including its provider, capability, and options. Continue through the relevant provider, group, and tool results; use returned pagination requests when needed. Do not combine `--request` with URL or filter arguments. + +Once a capability fits the task, request only its contract with `--options`, including the returned provider/capability IDs, `"level":"tools"`, and `"expand":["options","response"]`. Add `"examples"` only if the schema needs clarification. Progressive discovery is catalogue navigation, not semantic search or provider execution; use `search --sources alexandria` when starting from a natural-language capability. + ### Optional tool discovery alongside a scrape ```sh @@ -54,7 +66,7 @@ Read returned `data.tools` contracts and any tool metadata before choosing a pro ## Search → Inspect → Scrape -Use the two discovery paths above inside this skill. Choose semantic lookup for a capability described in words, or domain lookup when a relevant website is known. Default search combines web results, semantic tools, and domain tools. +Keep the entire discovery-to-execution workflow in this skill. Choose semantic lookup for a capability described in words, domain lookup when a relevant website is known, or progressive discovery to browse and narrow the catalogue. Default search combines web results, semantic tools, and domain tools. 1. Search once and inspect the returned tool identities and descriptions. A related topic alone does not mean the tool can answer the question. 2. Fetch only the selected provider's or capability's contract with `find-tools`. Omit `expand` for compact results; request `"expand":["options","response"]` only for the selected capability. Load examples only when needed. From 2f23a121459f396225e1b3c5453a628044885cfd Mon Sep 17 00:00:00 2001 From: Developers Digest <124798203+developersdigest@users.noreply.github.com> Date: Tue, 15 Sep 2026 09:06:08 -0400 Subject: [PATCH 3/5] Teach semantic and known-domain discovery together --- beta-skills/firecrawl-alexandria/SKILL.md | 28 +++++++++++------------ 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/beta-skills/firecrawl-alexandria/SKILL.md b/beta-skills/firecrawl-alexandria/SKILL.md index 029468a78d..e796189094 100644 --- a/beta-skills/firecrawl-alexandria/SKILL.md +++ b/beta-skills/firecrawl-alexandria/SKILL.md @@ -13,34 +13,32 @@ Use `FIRECRAWL_API_KEY` or existing Firecrawl login credentials. Never print cre Default to search with domain-tool discovery enabled. In this beta, plain `search` sends both `web` and `alexandria` sources with `domainTools: true`. Use `--domain-tools` explicitly in agent examples so this remains clear, including when selecting only web results. -### Search and discover tools for result domains +### Semantic search with domain discovery + +Start with a capability query and keep domain-tool discovery enabled. Default search combines semantic Alexandria tool matches with web results and tools for those result domains: ```sh -npx firecrawl-cli@alexandria search "Zillow homes for sale in Austin" --domain-tools --json +npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --domain-tools --json ``` -Inspect the web results and returned tool contracts. Domain-tool discovery finds tools for the domains in those results. It does not execute the tools. If using `--sources web`, keep `--domain-tools` to retain domain lookup; `--sources web` alone opts out of Alexandria discovery. - -### Semantic tool lookup - -When the task describes a capability rather than a known URL, search the Alexandria source: +If the user names a website, include that context in the same discovery workflow and look up its URL directly when you need its tool contracts: ```sh -npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --sources alexandria --json +npx firecrawl-cli@alexandria search "Zillow homes for sale and property price history" --domain-tools --json +npx firecrawl-cli@alexandria find-tools https://www.zillow.com --pretty ``` -Describe the data capability in the discovery query; keep exact street addresses, record IDs, and other execution arguments for the selected tool. For example, discover "residential property prices near an address", then resolve the user's address using the returned lookup contract. Do not claim rental support if the contract only supports for-sale listings. +The domain in the query provides context; it is not a strict provider filter. `--domain-tools` discovers tools for domains in the web results. Use `find-tools` with the known URL to inspect that domain even if it does not appear in those results. Inspect the returned matches before making another discovery call; skip the URL lookup when search already returned the needed contract. -This is semantic tool discovery, not a provider execution. Read the returned providers and capabilities rather than guessing a provider from a keyword. +Describe the data capability in the discovery query; keep exact street addresses, record IDs, and other execution arguments for the selected tool. For example, discover "residential property prices near an address", then resolve the user's address using the returned lookup contract. Do not claim rental support if the contract only supports for-sale listings. -### Lookup tools for a known domain +When only semantic tool matches are needed, narrow the same search to the Alexandria source: ```sh -npx firecrawl-cli@alexandria find-tools https://www.zillow.com --pretty -npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"level":"tools"}' --pretty +npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --sources alexandria --json ``` -`find-tools` looks up URLs, providers, groups, and tool contracts. Use semantic `search --sources alexandria` for a natural-language query; do not pass a search phrase as a URL to `find-tools`. +If selecting only web results, use `--sources web --domain-tools` to retain domain discovery; `--sources web` alone opts out. `find-tools` accepts URLs and catalogue selectors, not a natural-language search phrase. Both semantic and domain discovery return tool information without executing provider tools. Read the returned providers and capabilities rather than guessing a provider from a keyword. ### Progressive catalogue discovery @@ -66,7 +64,7 @@ Read returned `data.tools` contracts and any tool metadata before choosing a pro ## Search → Inspect → Scrape -Keep the entire discovery-to-execution workflow in this skill. Choose semantic lookup for a capability described in words, domain lookup when a relevant website is known, or progressive discovery to browse and narrow the catalogue. Default search combines web results, semantic tools, and domain tools. +Use semantic search with domain discovery as the shared entry point, incorporating any known website as described above. Continue with progressive discovery when the returned catalogue needs narrowing, then inspect and execute the selected tool. 1. Search once and inspect the returned tool identities and descriptions. A related topic alone does not mean the tool can answer the question. 2. Fetch only the selected provider's or capability's contract with `find-tools`. Omit `expand` for compact results; request `"expand":["options","response"]` only for the selected capability. Load examples only when needed. From 5326646298f62b3caf3be6fbedbe41e4d395ae6e Mon Sep 17 00:00:00 2001 From: Developers Digest <124798203+developersdigest@users.noreply.github.com> Date: Tue, 15 Sep 2026 09:07:39 -0400 Subject: [PATCH 4/5] Bump Alexandria beta to ship consolidated skill --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 60ab3a13e4..bf7bceeca4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "firecrawl-cli", - "version": "1.23.4-alexandria-beta.2", + "version": "1.23.4-alexandria-beta.4", "publishConfig": { "tag": "alexandria" }, From c88c96611bbe6c8d07bdbe799d28a0df7ee622bc Mon Sep 17 00:00:00 2001 From: Developers Digest <124798203+developersdigest@users.noreply.github.com> Date: Tue, 15 Sep 2026 09:13:45 -0400 Subject: [PATCH 5/5] Update beta-skills/firecrawl-alexandria/SKILL.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> --- beta-skills/firecrawl-alexandria/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beta-skills/firecrawl-alexandria/SKILL.md b/beta-skills/firecrawl-alexandria/SKILL.md index e796189094..7b30202faf 100644 --- a/beta-skills/firecrawl-alexandria/SKILL.md +++ b/beta-skills/firecrawl-alexandria/SKILL.md @@ -60,7 +60,7 @@ npx firecrawl-cli@alexandria scrape https://www.zillow.com --domain-tools --json Enable `--domain-tools` when a URL scrape should also return related tool contracts and the team has access. If the API refuses the feature, report the access requirement; do not repeatedly retry. A normal URL scrape does not enable this automatically. Inspect the complete JSON for both scraped content and tool metadata; discovering a tool does not execute it. Search and URL scraping can consume credits. -Read returned `data.tools` contracts and any tool metadata before choosing a provider/capability. Use their exact input schema, pricing and access requirements; never invent options or assume a provider is free. Follow returned Find Tools requests with `find-tools --request ''`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution. +Read returned tool contracts and any tool metadata before choosing a provider/capability; search and URL-scrape responses expose these as `data.tools`, while `find-tools` responses are under `data.alexandria`. Use their exact input schema, pricing and access requirements; never invent options or assume a provider is free. Follow returned Find Tools requests with `find-tools --request ''`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution. ## Search → Inspect → Scrape