fix(find-tools): say capabilities take the address, not the id
firecrawl_find_tools lists each tool with id: "apps-apple-com/apps/app", provider: "apps-apple-com" and capability: "apps/app". The capabilities parameter says "Exact capability IDs", so an agent holding an id passes it and gets invalid_option; discovery only accepts the address (apps/app), scoped by providers.
This describes both parameters by the listing field they take, with an example. Descriptions only; no behaviour change.
Evidence
I benchmarked description variants with an agent loop behind a stdio proxy in front of firecrawl-mcp@3.29.1 that replaced only the descriptions. Firecrawl responses were recorded once and replayed, so every variant saw the same data. Tasks were lookups on Alexandria-covered pages: the page scrape was refused and the matching catalogue items were shown, id included, with no ready-made call.
This PR's wording, 12 lookup tasks × 3 repeats (re-run 2026-10-15 after the review rewording):
| Model | Text | First contract lookup right | id passed as a capability |
|---|---|---|---|
| GPT-6 Luna | current | 21/28 | 8 |
| GPT-6 Luna | this PR | 26/26 | 0 |
| GPT-6.1 Sol | current | 5/30 | 28 |
| GPT-6.1 Sol | this PR | 32/32 | 0 |
The pre-review wording ("Capability addresses, as in each listed tool's capability field") ran in the same batch and did the same (Luna 29/29, Sol 30/30, no id passed), as it had on 2026-10-14 (Luna 15/25 → 27/27, Sol 12/30 → 34/34).
An earlier version of the capabilities text also said "not its provider-prefixed id". It did the same over 19 tasks × 3 repeats (Luna 14/30 → 33/33, Sol 21/42 → 47/47). Combined with the description change in the draft #537, it did the same across 15 more models from 10 labs (table there). Naming the field turned out to be enough, so the warning was dropped.
Caveats
- The mistake needs an agent that has an
idbut no ready-made call.firecrawl_search(toolDetail: "summary"/"full") andfirecrawl_scrape(domainTools: true) listidalongside a rawnext. Agents that followednextToolfromfind_toolslistings, or came from compact search results (noid), were right with the current text too. So the production rate is lower than the table. - Exchange's
invalid_optionnow names the fix, so most agents recover after one extra call. A few gave up and scraped instead. - The final wording was checked on Luna and Sol only.
Tests
Contract snapshots regenerated with UPDATE_CONTRACT_SNAPSHOTS=1; only these two descriptions and the find_tools definition hash change. pnpm test: 168/168 pass.
🤖 Generated with Claude Code