Merge pull request #154 from firecrawl/docs/json-format-token-limit-guidance

docs(scrape): add JSON format guidance for token limit issues

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.'