From d27fbec0e8de9ff5301043bef72e9626e4cc5884 Mon Sep 17 00:00:00 2001
From: "firecrawl-spring[bot]"
 <254786068+firecrawl-spring[bot]@users.noreply.github.com>
Date: Thu, 5 Feb 2026 16:59:14 +0000
Subject: [PATCH] docs(scrape): add JSON format guidance for token limit issues

- Remove outdated 'use extract' recommendation from scrape tool description
- Add Token Limit Issues section explaining how to use JSON format
- Add JSON format example with schema and prompt for structured extraction

This helps users who encounter 'tokens exceeds maximum allowed tokens' errors
by guiding them to use the JSON format which returns only the specific data
they need instead of the full page content.

Co-Authored-By: leonardogrig <leo@sideguide.dev>
---
 src/index.ts | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index 1151f8c..44593a1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -264,11 +264,11 @@ const scrapeParamsSchema = z.object({
 server.addTool({
   name: 'firecrawl_scrape',
   description: `
-Scrape content from a single URL with advanced options. 
+Scrape content from a single URL with advanced options.
 This is the most powerful, fastest and most reliable scraper tool, if available you should always default to using this tool for any web scraping needs.
 
 **Best for:** Single page content extraction, when you know exactly which page contains the information.
-**Not recommended for:** Multiple pages (use batch_scrape), unknown page (use search), structured data (use extract).
+**Not recommended for:** Multiple pages (use batch_scrape), unknown page (use search).
 **Common mistakes:** Using scrape for a list of URLs (use batch_scrape instead). If batch scrape doesnt work, just use scrape and call it multiple times.
 **Other Features:** Use 'branding' format to extract brand identity (colors, fonts, typography, spacing, UI components) for design analysis or style replication.
 **Prompt Example:** "Get the content of the page at https://example.com."
@@ -285,6 +285,29 @@ This is the most powerful, fastest and most reliable scraper tool, if available
 \`\`\`
 **Performance:** Add maxAge parameter for 500% faster scrapes using cached data.
 **Returns:** Markdown, HTML, or other formats as specified.
+**Token Limit Issues:** If you encounter "tokens exceeds maximum allowed tokens" errors or the scraped content is too large, use the JSON format with a schema to extract only the specific data you need. This dramatically reduces output size by returning structured data instead of the full page content.
+**JSON Format Example:**
+\`\`\`json
+{
+  "name": "firecrawl_scrape",
+  "arguments": {
+    "url": "https://example.com/product",
+    "formats": [{
+      "type": "json",
+      "prompt": "Extract the product details from this page",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "price": { "type": "number" },
+          "description": { "type": "string" }
+        },
+        "required": ["name", "price"]
+      }
+    }]
+  }
+}
+\`\`\`
 ${
   SAFE_MODE
     ? '**Safe Mode:** Read-only content extraction. Interactive actions (click, write, executeJavascript) are disabled for security.'