Fit search and scrape descriptions under Claude Code's 2,048-character cap, routing copy first

[rakshith48]

Claude Code truncates each tool description at 2,048 characters. On main the Alexandria copy starts at character 1,530 of 4,943 in firecrawl_search and 1,273 of 4,499 in firecrawl_scrape, so most of it never reaches the model. This PR puts the copy that changed agent behaviour in the AX runs first, and moves mechanics onto the parameters they describe.

	main	this PR
firecrawl_search	4,943 (Alexandria at 1,530)	1,747 (Alexandria at 259)
firecrawl_scrape	4,499 (Alexandria at 1,273)	1,465
/v2/mcp-search firecrawl_scrape	~3,350	< 1,500
server instructions, Alexandria paragraph	starts at 1,454	starts at 709, ends inside 2,048

What stays in the first lines, and why

From the EXP-052/053/055/056 runs in firecrawl/agent-experience:

• The noun "Alexandria" with its verticals. Naming the capability was the only thing that moved routing (9/11 provider-fit queries on both lanes vs 0–5/11). A tool rename did nothing, so firecrawl_find_tools is unchanged.
• The sources opt-out. PR Alexandria routing copy: name the catalogue, keep search as the front door, make sources opt-out explicit #424's wording moved Codex from supplying sources on 291/291 searches to omitting it on roughly a third to half of calls. It stays on the sources parameter and now also sits in the search description's first lines.
• Scrape reads first as "one URL, returns the page". EXP-055 found Codex sends single-page reads to Exa because Firecrawl's scrape tool reads as heavy. The scrape-first pointer to search stays; it is the only copy that reaches known-URL tasks.
• Search stays the front door. firecrawl_find_tools still says "Prefer normal firecrawl_search".

Moved, not dropped

• query: search operators. includeDomains / excludeDomains: their own descriptions. scrapeOptions: the maxAge note and "never provider tools".
• alexandria: batch shape, version pinning, contract reading (required inputs, requiresOneOf, response.key, pagination), per-item errors, nextTool, access, and the terms flow.
• requestId: retry rules and the error codes.
• The firecrawl_feedback pointer stays in both the search and scrape descriptions, shortened.

Tests

New tests/mcp-description-budget.test.mjs (every full-surface tool ≤ 2,048; the Alexandria lead, sources opt-out and scrape-first pointer are present; scrape opens with the single-URL framing). The search-surface test checks every tool there ≤ 2,048. The smoke test checks the Alexandria paragraph, scrape-first rule and sources rule sit in the first 2,048 characters of the server instructions, and moved-text assertions now read the parameter descriptions. Suite 120/120. Version 3.25.4.

An AX sim comparing this build against main on the 11 provider-fit tester queries, both lanes, is running; results will be posted here.

🤖 Generated with Claude Code

---

Summary by cubic

Fits firecrawl_search and firecrawl_scrape descriptions under Claude Code's 2,048-character cap so the Alexandria routing copy reaches the model. The copy that changed agent behavior in the AX runs now leads each description; mechanics move onto the parameters they describe. firecrawl_search drops from 4,943 to 1,747 characters and firecrawl_scrape from 4,499 to 1,465.

• The Alexandria lead (verticals, provider-over-scrape rule, sources opt-out) now sits in the search description's first lines; scrape opens with "Scrape one URL and return its content" and keeps the scrape-first pointer.
• Query operators, domain filters, maxAge, retry rules, error codes, batch shape, and provider terms move onto the query, includeDomains, excludeDomains, scrapeOptions, alexandria, and requestId parameters.
• Server instructions reorder the Alexandria paragraph ahead of the research and developer boilerplate so it lands inside the cap; those mechanics now live on the search description and requestId parameter instead.
• Adds tests/helpers/description-budget.mjs with a shared cap constant and tests/mcp-description-budget.test.mjs; the search-surface and smoke tests pin every description under 2,048 characters and the routing copy inside the window. Suite passes 120/120; version bumped to 3.25.4.

^{Written for commit 88d7e1d. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 6 files

<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 5 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>

[rakshith48]

AX sim result (EXP-057): nothing broke. 11 provider-fit tester queries × Claude Code and Codex, prompt names Alexandria, main 55c1f99 vs this PR at 88d7e1d, 44 traces, digests verified on every trace.

	main	this PR
Claude: executed a provider	10/11	10/11
Codex: executed a provider	10/11	10/11
Codex: searches keeping Alexandria matches (sources omitted or incl. alexandria)	13/78	26/118
Codex: traces with at least one such search	9/11	11/11
Claude: searches keeping matches	5/17	7/21

Execution is identical per query in both lanes (the same ten execute; sodermalm-housing has no provider). All differences are within noise at n = 11; the named prompt saturates execution, so this is a non-inferiority check. Findings: firecrawl/agent-experience#845.

🤖 Generated with Claude Code

[Max17190]

lgtm!