docs(api): document Find Tools in the v2 OpenAPI spec

[claude]

Requested by Micah Stairs · Slack thread

Before: The SDKs call Find Tools as POST /v2/scrape with alexandria: {provider: "firecrawl", capability: "find-tools", options}. The OpenAPI spec did not say this. It had no Find Tools example, no schema for its options, and no schema for its result page.

After: The alexandria property description on POST /scrape now tells readers how to call Find Tools and that it is free. The endpoint has two named request examples: "Scrape a URL" (first, so it stays the default) and "Find Tools". In the rendered spec, alexandria.options shows two choices: "Find Tools options" (query, urls, providers, categories, groups, capabilities, level, expand, limit, offset) and "Capability options". In the response, the result data also shows two choices: "Find Tools result" (level, items, total, next) and "Capability response".

How: I added two schemas, FindToolsOptions and FindToolsData. AlexandriaCall.options and the success data of AlexandriaResult now use anyOf to reference them. The second choice in each anyOf accepts any value, so everything that was valid before is still valid. The find-tools capability runs in Exchange, so its source is not in firecrawl/firecrawl. I took the fields from the code that calls it:

• apps/api/src/search/alexandria.ts:57-89: the API calls firecrawl/find-tools with query, providers, capabilities, level, expand, and limit. It requires creditsCost: 0, and it parses data.items against the tool contract schemas.
• apps/api/src/services/alexandria/contracts.ts:51-79: tool item fields (provider, capability, name, description, creditsCost, perRecord, plus options and response when expanded, and next).
• apps/api/src/controllers/v2/scrape-alexandria.ts:24-28,230-234: the alexandria body and the data.alexandria[] response envelope.
• apps/js-sdk/firecrawl/src/v2/methods/tools.ts:118-128 and apps/js-sdk/firecrawl/src/v2/types.ts:875-898: FindToolsOptions and FindToolsData (level is providers, groups, or tools; items have id, name, next, execute; next is an AlexandriaCall or null).
• apps/python-sdk/firecrawl/v2/client.py:285-303 and apps/python-sdk/firecrawl/v2/types.py:1096-1100: the same call and shape.
• firecrawl-mcp-server/src/alexandria.ts:40-62: query and urls options.

I did not add bounds (such as a limit maximum) or defaults, because the server code that sets them is not in these repos. Find Tools has no toolDetail option: expand controls the detail level. I did not change DiscoveredTool, requiresAction, or search toolDetail. No localized files changed.

Validation: python3 -m json.tool passes. npx @apidevtools/swagger-cli@4 validate api-reference/v2-openapi.json reports the spec as valid. scripts/check-extraction-hostile-markdown.sh passes. scripts/check-locale-api-literals.sh fails, but it fails the same way on main (see the comment below). I did not run mint locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LKCJJgeohVR5dnd1MDBzAR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
firecrawl	🟢 Ready	View Preview	Oct 2, 2026, 2:08 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

The check "Locale literals and extraction-hostile markdown" fails at the step "Keep API literals untranslated" (scripts/check-locale-api-literals.sh). This PR does not cause the failure.

• The script fails the same way on main at d8ab99e. The cause is probably the locadex translations in docs(locadex): update translations on main #1500.
• Some of the reported lines: es/features/change-tracking.mdx:44 (seguimientoDeCambios), es/webhooks/events.mdx:67 (rastreo.iniciado), pt-BR/v0/sdks/node.mdx:66 (dadosRaspados).
• This PR changes only an English source file (api-reference/v2-openapi.json) and adds no findings.
• No fix exists yet. CLAUDE.md gives localized files to the translation pipeline, so this PR does not edit them.

---

Generated by Claude Code