From 5bbf8ab2dc11fa367fe6e7093976d5b4f58944fb Mon Sep 17 00:00:00 2001 From: Gaurav Date: Sat, 5 Sep 2026 19:07:52 +0530 Subject: [PATCH 1/2] docs(developer-index): document the `web:` id prefix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Search API replies to `/v2/search/developer` include a fifth id prefix — `web:` — for open web pages returned alongside the four curated kinds (`doc:`, `issue:`, `pull_request:`, `readme:`). The skill enumerated only the curated four, so an agent following the "scope last" guidance and satisfying the "quote and cite" rule could mistake a `web:` result for a curated primary source. Add `web:` to the enumerated prefix list, mark it as an open web page rather than a curated artifact, and note that the way to keep only curated results is to pass `types=["doc","issue","pull_request","readme"]` (`types=["web"]` is rejected with a 400). Fixes #213 --- skills/firecrawl-developer-index/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/firecrawl-developer-index/SKILL.md b/skills/firecrawl-developer-index/SKILL.md index 6a18efd58b..0f3758b05a 100644 --- a/skills/firecrawl-developer-index/SKILL.md +++ b/skills/firecrawl-developer-index/SKILL.md @@ -14,7 +14,7 @@ There is **no fixed recipe**. Read the question, decide what kind it is, and cho - HTTP: **`GET|POST https://api.firecrawl.dev/v2/search/developer`** MCP: **`firecrawl_developer_search(query, k?, skills?)`** CLI: **`firecrawl developer [--limit ]`** - Ranked results over the whole index. Each carries `id` (`issue:owner/repo#123`), `url`, and the **matched passages in markdown**, so tables and code blocks survive. The artifact kind is the `id` prefix: `doc:`, `issue:`, `pull_request:`, or `readme:`. + Ranked results over the whole index. Each carries `id` (`issue:owner/repo#123`), `url`, and the **matched passages in markdown**, so tables and code blocks survive. The artifact kind is the `id` prefix: `doc:`, `issue:`, `pull_request:`, or `readme:` for curated index entries, and `web:` for an open web page returned alongside them — not a curated artifact, and not something you can request or exclude by name. To keep only curated results, pass `types=["doc","issue","pull_request","readme"]`. The default first move for a developer question. It is the only surface that returns the passages, which is what lets you answer instead of pointing at a page. `k` / `--limit` is 1–100 and defaults to 10. `skills="only"` (HTTP/MCP only) restricts the search to agent-skill files. Keyless; send `Authorization: Bearer $FIRECRAWL_API_KEY` for higher rate limits. From c8e383dd6fa82aacbdd6aa6481e0dabf0d7e30ff Mon Sep 17 00:00:00 2001 From: Gaurav Date: Sun, 6 Sep 2026 00:05:49 +0530 Subject: [PATCH 2/2] docs(developer-index): note types default also returns web: results MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address cubic review on #218: the earlier line 17 change said passing `types=["doc","issue","pull_request","readme"]` "keeps only curated results", but the Filters section right below still described the same enumeration as the default — the workaround read as redundant. Update the Filters `types` bullet to state plainly that when `types` is unset the response also carries `web:` results, and that passing an explicit list is the only way to exclude them. Keeps the section consistent with the new line 17 note and with the reported behaviour in #213. --- skills/firecrawl-developer-index/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/firecrawl-developer-index/SKILL.md b/skills/firecrawl-developer-index/SKILL.md index 0f3758b05a..5b8b05d3e0 100644 --- a/skills/firecrawl-developer-index/SKILL.md +++ b/skills/firecrawl-developer-index/SKILL.md @@ -33,7 +33,7 @@ There is **no fixed recipe**. Read the question, decide what kind it is, and cho Only the HTTP surface takes these. On `GET`, pass `types=issue,pull_request` or repeat the parameter; on `POST`, pass arrays. All are optional. -- `types` — which of `doc`, `issue`, `pull_request`, `readme` to search. Defaults to all four. Narrowing here is the cheapest way to sharpen a query. +- `types` — which of `doc`, `issue`, `pull_request`, `readme` to search. When unset the request also returns `web:` results alongside the four curated kinds; passing an explicit list is the only way to exclude them. Narrowing here is also the cheapest way to sharpen a query. - `repos` (`owner/name`) scopes the repository half, meaning `issue`, `pull_request`, and `readme`; `sources` (documentation source ids, at most 20) scopes the documentation half, meaning `doc`. Passing both **unions** the halves rather than intersecting them. Both echo back in the response with `indexed: true|false` — that is how you tell "not in the index" from "found nothing". - A filter that cannot match any requested `type` is a `400`, not an empty list: `repos` with no repository type in `types`, or `sources` without `doc`. - `passages` (1–5, default 1) is the _maximum_ passages per result, not a guarantee. Raise it when one page is clearly the right page but the first passage is the wrong part of it.