fix(search-surface): say when to use firecrawl_search and firecrawl_scrape

MA
4d ago
+10-10

Why

On the search surface (/v2/mcp-search), which backs the Claude connector listing, the firecrawl_search and firecrawl_scrape descriptions said what each tool returns but not which requests it serves. Neither description told Claude to reach for firecrawl_scrape when a user pastes a URL, and the search description did not say how to read a result page, even though this surface's firecrawl_search returns no page content. The connector directory policy asks that each tool description say what the tool does and when it should be invoked.

The full surface already carries these "Use it when" lines. This brings the same guidance to the search-surface copies, worded for that surface's tool set.

Summary

Text only, two descriptions in src/service/search-surface.ts. Tool names, titles, annotations, input and output schemas, server instructions, the tool list, and the full-surface copy in src/server.ts are unchanged.

firecrawl_search, first paragraph. Added after the first sentence:

Use it when a request needs current or web information, or to list businesses, people, products, jobs or events with websites, prices or contacts.

and extended the result sentence:

Each web result is a title, URL, and description; use firecrawl_scrape on a result URL to read the full page.

firecrawl_scrape, first paragraph. Added after the first sentence:

Use it when the user gives a URL, or names a page or PDF (find its URL with firecrawl_search first), and wants it read or summarized, or wants prices, specs, contact details or a table from it; also use it to read a search result in full.

URL mode needs a URL, so a page the user only names goes through search first.

The operator, category, gov, Alexandria and billing guidance is kept as is. Neither line names or compares with any other tool or app, and both describe only requests the user makes.

Served surface (contract snapshots): only the firecrawl_search and firecrawl_scrape definition hashes change, on the hosted search primary and companion snapshots. Every other snapshot is unchanged. Description lengths are 1,929 (search) and 1,124 (scrape) characters, inside the 2,048-character cap.

Test Plan

  • tsc --noEmit clean
  • pnpm run lint clean
  • pnpm test: 367 of 367 pass, including the search-profile description assertions and the description budget test
  • Contract snapshots regenerated with UPDATE_CONTRACT_SNAPSHOTS=1; the regenerated tool definitions differ from main only in the two description fields
  • After deploy, tools/list on /v2/mcp-search shows the new descriptions

Summary by cubic

Adds usage guidance to the firecrawl_search and firecrawl_scrape descriptions on the search surface so Claude knows when to invoke each tool.

  • firecrawl_search now says it should be used for current or web information and business/people/product listings, and points clients to firecrawl_scrape on a result URL to read the full page.
  • firecrawl_scrape now says it should be used when a user provides a URL, or names a page or PDF whose URL must first be located via firecrawl_search, and wants it read, summarized, or extracted from.
  • Contract snapshots refresh; only the two tool definition hashes change.