Natural alexandria search

beta-skills/firecrawl-alexandria/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: firecrawl-alexandria
-description: Use for explicitly requested Firecrawl Alexandria beta tool discovery or provider execution, including Find Tools, provider-backed search, and structured third-party data. Requires an authorized Firecrawl API key; does not replace normal web search or scraping.
+description: Use with Firecrawl beta search when natural web results include Alexandria tools, when the user explicitly wants tools for a task or website, or when executing a discovered provider tool. Search normally, inspect matching contracts, and execute through Scrape. Find Tools is the catalogue meta tool. Requires an authorized Firecrawl API key.
 ---
 
 # Alexandria Beta
@@ -9,77 +9,84 @@ Use the beta CLI explicitly on every invocation: `npx firecrawl-cli@alexandria`.
 
 Use `FIRECRAWL_API_KEY` or existing Firecrawl login credentials. Never print credentials. Installing the beta is not authorization: the API enforces team and provider access.
 
-## Discover Before Executing
+## Natural search first
 
-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.
-
-### 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:
+Start with the user's actual question, including the location, marketplace, and constraints. Do not rewrite an ordinary research question into a request for APIs or tools. Default search returns web results and relevant Alexandria tools together, with domain matching enabled:
 
 ```sh
-npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --domain-tools --json
+npx firecrawl-cli@alexandria search "homes for sale in Lower Haight San Francisco" --json -o .firecrawl/homes.json
 ```
 
-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:
+Read both `data.web` and `data.tools`. Tools are discovery results, not fetched provider data. Use useful web results directly; when a returned tool fits, inspect its contract and execute it through `scrape --alexandria`. Search never automatically executes provider tools, including with `--scrape` (which fetches web page content).
 
-```sh
-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
-```
+A complete contract returned by search needs no additional discovery call. Check country/marketplace, rental versus sale, individual-record versus aggregate coverage, required inputs, `creditsCost`, `perRecord`, and access requirements. Use returned lookup tools to resolve record IDs; never invent them. A related domain or topic does not establish coverage. If no candidate fits, use web results or ordinary URL scrape instead of walking the entire catalogue.
 
-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.
+`--sources web` opts out of Alexandria. `--sources web --domain-tools` includes tools for web-result domains. `--no-domain-tools` disables domain matching but does not remove semantic Alexandria results when that source is selected. Keep the normal default unless the user requests a narrower source.
 
-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.
+## Explicit requests for tools: search then the Find Tools meta tool
 
-When only semantic tool matches are needed, narrow the same search to the Alexandria source:
+For “find tools that can look up company filings,” search only tool capabilities:
 
 ```sh
-npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --sources alexandria --json
+npx firecrawl-cli@alexandria search "tools to search company filings" --sources alexandria --json
 ```
 
-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.
+Then use `find-tools` when the user wants a set of tools for a returned provider, a known website, or a specific contract. It is a meta tool: it lists tools and their inputs, without executing them. The CLI sends `firecrawl/find-tools` through the same Scrape API used for every provider execution. Do not call Exchange endpoints directly.
 
-### Progressive catalogue discovery
+```sh
+# Known website: discover its providers, without fetching the URL
+npx firecrawl-cli@alexandria find-tools https://www.zillow.com --json
 
-When the provider is unknown or a result exposes more groups/tools, narrow the catalogue progressively instead of loading every contract:
+# After discovery identifies zillow: list its tools, compactly
+npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"level":"tools","limit":100}' --json
 
-```sh
-npx firecrawl-cli@alexandria find-tools --options '{"level":"providers"}' --json
+# Inspect only the selected contract
+npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"capabilities":["properties/locations"],"level":"tools","expand":["options","response"]}' --json
 ```
 
-Inspect the compact results and follow the relevant returned `next` request with `find-tools --request '<returned request JSON>'`. 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.
+`find-tools` accepts URLs and catalogue selectors, not a free-text query. Use Alexandria-only search for natural-language tool intent. Valid catalogue selectors: `urls`, `providers`, `categories`, `groups`, `capabilities`. Valid `level` values: `providers`, `groups`, `tools` (not `capabilities`). `limit` accepts 1–100 and defaults to 5; use 100 for an explicitly requested broad tool list. Follow pagination only if more results are needed. Add `examples` to `expand` only when inputs remain unclear.
+
+Items are at `data.alexandria[i].data.items`; each call has its own envelope. A returned `next` is a complete request for the same meta tool:
 
-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.
+```sh
+npx firecrawl-cli@alexandria find-tools --request '<returned next request JSON>' --json
+```
 
-### Optional tool discovery alongside a scrape
+Pass that request unchanged; do not combine `--request` with URL/filter arguments. The equivalent explicit meta-tool execution is:
 
 ```sh
-npx firecrawl-cli@alexandria scrape https://www.zillow.com --domain-tools --json
+npx firecrawl-cli@alexandria scrape --alexandria firecrawl/find-tools --options '{"providers":["zillow"],"level":"tools","limit":100}' --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.
+An empty URL lookup means no visible provider matched that domain. A semantic match can still target a different country or unsupported segment. Never make an unrelated paid probe to test coverage.
 
-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 '<returned request JSON>'`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution.
+## Execute through Scrape
 
-## Search → Inspect → Scrape
+After inspecting a fitting contract, run it through the normal scrape command:
 
-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.
+```sh
+npx firecrawl-cli@alexandria scrape --alexandria zillow/properties/locations --options '{"query":"800 Haight Street San Francisco","count":3}' --json
+```
 
-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.
+This resolves an address; it does not itself return nearby rental prices. Continue only with supported capabilities and returned identifiers.
 
-For example, after discovery confirms Zillow's address lookup contract:
+For an existing URL, ordinary scrape can optionally return related tools alongside the page:
 
 ```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
+npx firecrawl-cli@alexandria scrape https://www.zillow.com --domain-tools --json
 ```
 
-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.
+This discovers tools without executing them. On access refusal, report it rather than repeatedly retrying or bypassing the gate.
+
+## Read receipts and failures
+
+- Search: `creditsUsed` and `id` at the top level.
+- URL scrape: `metadata.creditsUsed` in its JSON output.
+- Meta-tool/provider calls: `data.creditsCost` plus `data.alexandria[i].creditsCost`; inspect each call's `error` too.
+- Tool prices are `creditsCost` and `perRecord`, not a `pricing` field. Do not assume every tool has the same price.
+- Save JSON and stderr separately. `2>&1` mixes Request ID lines into JSON and breaks parsing.
+- Team balance deltas include concurrent users and tests. Attribute spend from receipts, and reconcile the full time window before alleging overbilling.
+- Empty provider results may still be billed. A successful HTTP envelope is not proof the task returned usable records.
 
 ## Execute Within The User's Budget
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-cli",
-  "version": "1.23.4-alexandria-beta.4",
+  "version": "1.23.4-alexandria-beta.5",
   "publishConfig": {
     "tag": "alexandria"
   },

skills/firecrawl-search/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools:
 
 # firecrawl search
 
-Web search with optional content scraping. Returns search results as JSON, optionally with full page content.
+Search naturally using the user’s actual question. In the Alexandria beta, default search returns web results plus relevant Alexandria tools, with optional web content scraping.
 
 ## Quick start
 
@@ -30,6 +30,16 @@ Run `firecrawl search --help` for the full option list.
 
 **Done when:** results are saved under `.firecrawl/`, verified non-empty, processed for the request, and one feedback event is sent within the time window (unless opted out).
 
+## Alexandria in normal search
+
+The beta defaults to `web,alexandria` with domain-tool matching on. Preserve the user's location, marketplace, and constraints in the query; do not turn normal research into an artificial tool-discovery query. Inspect `data.web` and `data.tools` from the same response.
+
+A tool match is not executed data. If it fits the task, read its inputs, coverage, `creditsCost`/`perRecord`, and access requirements in the JSON. Execute it with `firecrawl scrape --alexandria <provider/capability> --options '<input JSON>'`. All provider execution goes through Scrape; `search --scrape` only fetches web result content, not provider tools.
+
+Use `find-tools` only for an explicitly requested tool set or a missing contract. It runs the `firecrawl/find-tools` meta tool through Scrape and never executes the tools it discovers. It accepts URLs or catalogue selectors; for “tools that can do X,” first use `search "X" --sources alexandria`, then narrow the returned providers with `find-tools --options '{"providers":["<returned-provider>"],"level":"tools","limit":100}'`.
+
+If no returned tool covers the country/market/segment or required inputs, continue with ordinary web results. Do not exhaust the catalogue or pay for adjacent tools just to probe coverage. `--sources web` explicitly opts out of Alexandria; `--sources web --domain-tools` retains domain matches only.
+
 ## Tips
 
 - **`--highlights` on by default:** results are query-relevant excerpts, not full-page snippets. Use `--no-highlights` for the original snippets.