fix(mcp): clarify Alexandria execution and feedback metadata

[Max17190]

Why

Alexandria metadata combines capability descriptions with directions to execute providers, retry requests, accept provider terms, and submit feedback after a task. Describe the capability contracts and authorization requirements clearly. Keep optional feedback beside results and in its dedicated tool, where it is relevant to the completed task.

Summary

• Revise the full/account and search-profile descriptions and initialization guidance, plus the alexandria and requestId parameter descriptions.
• Preserve identical-payload request identity, pending/unresolved error semantics, explicit authorization for the reviewed terms version and digest, and confirmed:true.
• Remove Alexandria feedback directions from selection metadata. Keep the optional feedback pointer in returned results and the dedicated feedback tool; align the README with this entry point.
• Retain the condensed descriptions already on main. The observed app description below still contains the older duplicated execution paragraph.
• Clarify that web-only sources can still return domain-matched tools when requested, and that provider contract fields vary by capability.
• Extend existing metadata tests across full, account, and search profiles, with focused checks of Alexandria descriptions, parameters, and authorization safeguards.

The changes are limited to metadata and README wording, an unused guidance constant, and tests. Runtime handlers, validation rules, registered tools, and safety annotations are unchanged.

Description comparison

The baseline below is the production app metadata observed on September 23, 2026, with the app wrapper removed. It differs from the condensed source already on main. The proposed descriptions reflect this branch's tools/list definitions.

Current observed production tool descriptions

firecrawl_scrape

Retrieve and extract content from one supplied URL through Firecrawl. Use this when the request identifies a page and needs its content or defined fields. It can return markdown, HTML, links, screenshots, branding data, a targeted answer, or JSON matching a supplied schema; JSON is useful when the requested result has defined fields, while markdown preserves readable page content.

This tool operates on a known page. For a set of pages use `firecrawl_crawl`, and to discover page URLs use `firecrawl_map` or `firecrawl_search`. Options include JavaScript render delay, cache age, main-content filtering, PII redaction, and lockdown cache-only retrieval. Browser actions may change the live page when interactive actions are enabled.

Firecrawl may reuse recently indexed content instead of refetching the page, and the reuse window varies by domain. Set `maxAge: 0` to force a live fetch, or a smaller `maxAge` to bound how stale reused content may be. A successful response does not by itself confirm that the state it describes is still current.

Returns the selected content formats and page metadata. 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.
Alexandria mode: pass `alexandria` (one `{provider, capability, options}` object or an array of 1-10) instead of `url` to execute catalogued Alexandria capabilities found through `firecrawl_search` sources `alexandria` or `firecrawl_find_tools`. The optional requestId identifies one logical execution: reuse the returned ID for retries of the identical payload, never a new ID to bypass pending or uncertain execution. Each call may include version to pin a published workflow; omitting it uses latest. Only timeout also applies at the top level in this mode. Returns per-capability results in `data.alexandria`, including `data`, `records`, or an `error` with a code. Check each item for errors even when the outer response is successful. Alexandria needs an API key on a team with Alexandria enabled.
Alexandria mode: pass `alexandria` (one `{provider, capability, options}` object or an array of 1-10) instead of `url` to execute catalogued Alexandria capabilities found through `firecrawl_search` sources `alexandria` or `firecrawl_find_tools`. The optional requestId identifies one logical execution: reuse the returned ID for retries of the identical payload, never a new ID to bypass pending or uncertain execution. Each call may include version to pin a published workflow; omitting it uses latest. Only timeout also applies at the top level in this mode. Returns per-capability results in `data.alexandria`, including `data`, `records`, or an `error` with a code. Check each item for errors even when the outer response is successful. Alexandria needs an API key on a team with Alexandria enabled. 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).

For potentially large workflow results, supply and preserve a top-level requestId before execution. If a response provides nextTool, follow its instructions to access the result without repeating a successful provider call.

URL mode only: set `domainTools: true` to also return domain-matched Alexandria tools for the page in `tools` on the returned document.

Alexandria 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. A terms-gated Alexandria provider returns `THIRD_PARTY_DATA_TERMS_REQUIRED` (403) with `requiresAction.url`: follow the returned terms/show and terms/accept calls through this tool, only accepting after explicit user authorization for the reviewed version and digest. An organization admin can alternatively accept at the dashboard URL. Retry only after confirmed acceptance.

firecrawl_search

Search web, news, or image sources and return ranked results. Operators include quoted phrases, `-term`, `site:host`, `inurl:term`, `intitle:term`, and `related:host`; the set is non-exhaustive. `includeDomains` and `excludeDomains` are mutually exclusive hostname filters; categories limit results to GitHub, research, PDF, or developer sources.

For a programming question, add `categories: ["developer"]`. It searches an index of repositories, GitHub issues, merged pull requests, repository READMEs, and curated documentation sites, and returns the hits in `data.web` with `category: "developer"`.

`categories: ["research"]` restricts these web results to research-affiliated websites and returns page snippets. The `firecrawl_research_*` tools are a separate surface that searches paper abstracts and full text across biomedical (PubMed, bioRxiv, medRxiv) and arXiv literature.

Each web result is a title, URL, and description, not the page. Add `scrapeOptions` to attach page content in the same call; those fetches ignore `maxAge`, so use `firecrawl_scrape` when you need a live fetch. Returns source-type result groups and usage metadata. Authenticated responses can include an `id` for optional search feedback.

Start with the user’s actual question and constraints. Authenticated search returns matching Alexandria providers beside web results; prefer a provider over page scraping when the task needs the same fields across several entities, provenance, exact figures, or many records, and use web results when they already answer the question. Authenticated search defaults to web + semantic Alexandria tools + domain-matched tools. Keyless search defaults to web only. Alexandria is Firecrawl's catalogue of data providers and workflows across 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; providers return typed, sourced records through published contracts. Coverage varies; discover current tools rather than assuming one exists. Semantic discovery matches the data you need to capabilities even without a provider website in the web results. Domain matching connects result websites to tools that may fetch richer details, related records or collections beyond the linked page. Inspect coverage and required inputs; a matching domain alone does not guarantee a fit. 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. Use sources: ["alexandria"] for semantic tools only, sources: ["web"] for web only, or sources: ["web"], domainTools: true for web plus domain tools. domainTools: false disables domain matching. Results in data.tools describe available tools, not executed data. Search defaults to toolDetail: "compact", returning only provider, capability and description; "summary" adds metadata and navigation. Inspect selected tools with firecrawl_find_tools using their providers and capabilities plus expand:["options","response"]; request examples only when the input shape is unclear. Batch related contract inspections and reuse complete contracts. Alternatively set toolDetail: "full" for contracts upfront. On the full MCP surface, firecrawl_find_tools supports semantic query lookup and is the list equivalent: {} lists categories; {categories:["<category-id>"]} lists providers; {providers:["<provider-id>"]} lists compact tools; adding capabilities:["<capability-id>"] expands the selected contract. Avoid expanding the entire catalogue. Read required inputs and requiresOneOf groups (at least one member per group), example.request/example.response when present, and response.key in the selected contract. 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. Execute through firecrawl_scrape with alexandria:{provider,capability,options}. Search scrapeOptions fetches web pages, never provider tools. Use web results when sufficient, tools when they offer a direct route to deeper data. 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.

firecrawl_find_tools

Browse Alexandria data providers and workflows or read a selected contract. Alexandria covers 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: 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).

firecrawl_feedback

Submit concise quality feedback for a completed search, scrape, parse, or map job. Provide the endpoint, job ID, rating, and relevant issue codes or small contextual fields; omit large page contents and raw outputs.

For an Alexandria session, set endpoint to `alexandria`, omit jobId, and provide requestedWebsite (url and requestedFunctionality), rationale, and rating. Optional providerFeedback and capabilityFeedback describe gaps or errors. Capability issues: new_capability_request (requires requestedFunctionality), missing_capability, insufficient_functionality, incorrect_result, execution_error, other. Alexandria feedback has no job-age deadline and no credit refund.

Returns submission status, feedback ID, and accounting fields.

Proposed full/account tool descriptions

firecrawl_scrape

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, `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, on an authenticated session with Alexandria access: `alexandria` selects catalogued capability execution and is mutually exclusive with `url`; the `alexandria` and `requestId` parameters describe batching, retries, errors and provider terms.

firecrawl_search

Search web, news, or image sources and return ranked results with query-relevant highlights. Each web result is a title, URL, and description; use `firecrawl_scrape` on a result URL when the excerpt is not enough.

Authenticated search also returns matching Alexandria data providers in data.tools (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). 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. A search with sources: ["web"] omits semantic provider discovery; domainTools: true can still return website-matched tools. Web-only results use domainTools: false.

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.

firecrawl_find_tools

Browse Alexandria data providers and workflows or read a selected contract. Alexandria covers 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: 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.

Proposed execution and request-identity parameter descriptions

alexandria

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. 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. 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. nextTool identifies access to retained results without repeating a successful provider call. Requires an API key on a team with Alexandria enabled. THIRD_PARTY_DATA_TERMS_REQUIRED (403) means execution is blocked by provider terms, with requiresAction.url for review by an organization admin. Through this tool, terms/show displays the agreement and terms/accept records acceptance; acceptance requires explicit user authorization for the reviewed version and digest and confirmed:true. A data request does not authorize acceptance. Provider execution remains blocked until acceptance is confirmed.

requestId

Identifies one logical Alexandria execution; generated when omitted and returned with the result. Repeated attempts of the identical payload require the same ID. A new ID cannot reconcile a pending or uncertain execution. A caller-supplied ID supports recovery if no response is received. Errors relay a code and may include chargeId. request_in_flight (409) means the execution is pending; request_unresolved (503) requires reconciliation under the same ID; duplicate_request (409) means the ID belongs to a different payload; unknown_provider (404), insufficient_credits (402) and billing_unavailable (503) mean nothing executed.

Test Plan

• pnpm test: all 121 tests passed, including the build.
• pnpm exec tsc --noEmit: passed.
• pnpm exec eslint src/index.ts src/alexandria-feedback.ts: passed.
• Lint of src/alexandria.ts reports the same pre-existing unused expand binding at line 97 as main; baseline and branch diagnostics were compared and are identical.
• Compared the emitted 27-tool catalogue with main: validation schemas and safety annotations are identical after excluding description fields.
• Verified all emitted tool descriptions fit the existing size limit.
• git diff --check: passed.
• Verified a live web-only search can return domain-matched tools with domainTools: true, and a selected research contract omits requiresOneOf and a cursor input.

Publication verification

After deployment, refresh the connector's registered metadata and verify the descriptions delivered to a new session. Client approval behavior still requires an end-to-end check with the updated metadata and the relevant approval settings; unit and integration tests do not establish warning removal.

Plugin skills are distributed separately from this repository. The matching skill wording is updated in firecrawl/cli#281; a plugin version containing that skill is needed for consistent behavior.

[cubic-dev-ai]

All reported issues were addressed across 3 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 6 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Confidence score: 4/5

• In src/alexandria.ts, the firecrawl_search description omits key billing distinctions, so full-profile users may be unclear about which searches incur per-request charges; document the billing semantics, including that Alexandria-only discovery is free.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/alexandria.ts">

<violation number="1" location="src/alexandria.ts:108">
P2: The `firecrawl_search` tool description still omits billing semantics, so full-profile users cannot tell that web, developer, and research searches are billed per request, Alexandria-only discovery is free, and scrape execution uses URL or listed capability pricing. Add that guidance here.

(Based on your team's feedback about search billing semantics.)</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The firecrawl_search tool description still omits billing semantics, so full-profile users cannot tell that web, developer, and research searches are billed per request, Alexandria-only discovery is free, and scrape execution uses URL or listed capability pricing. Add that guidance here.

(Based on your team's feedback about search billing semantics.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/alexandria.ts, line 108:

<comment>The `firecrawl_search` tool description still omits billing semantics, so full-profile users cannot tell that web, developer, and research searches are billed per request, Alexandria-only discovery is free, and scrape execution uses URL or listed capability pricing. Add that guidance here.

(Based on your team's feedback about search billing semantics.) </comment>

<file context>
@@ -105,4 +105,4 @@ export function withFindToolsNavigation(envelope: any) {
 
 export const ALEXANDRIA_SEARCH_INSTRUCTIONS =
-  'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only, or sources: ["web"] with domainTools: false for web only. 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.';
+  '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.';
</file context>

[Max17190]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@Max17190 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 existing issue remains and no new issues found across 10 files

Confidence score: 4/5

• In src/alexandria.ts, the firecrawl_search description omits that web, developer, and research searches are billed per request while Alexandria-only discovery is free, so full-profile users may be unclear about charges — document these billing semantics.

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from a previous review of this commit.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>