docs(ask): drop usage from /support/ask response + neutralize example diagnosis

[devhims]

Summary

Two changes on the /support/ask docs to keep the published contract honest:

1. Drop usage from the /support/ask response

Token usage is captured server-side for telemetry but not returned to callers — companion change in support-agent removes it from the AnswerEnvelope. The docs were promising a usage object that won't actually be there. Updates:

• api-reference/v2-openapi.json — drop usage from the AskResponse schema.
• api-reference/endpoint/ask.mdx — drop the usage row from the response fields table.
• features/ask.mdx — drop the usage line from the /support/ask example payload.

/support/docs-search keeps its usage field — that endpoint still returns it (different envelope shape, different code path).

2. Replace the fabricated example diagnosis

The previous example in features/ask.mdx looked like real Firecrawl guidance:

{
  "answer": "Your crawl is hitting a robots.txt disallow on /products/*. The fix is to add the allowBackwardCrawling parameter.",
  "fixParameters": { "allowBackwardCrawling": true },
  "validation": {
    "tested": true,
    "result": "success",
    "evidence": "validateScrape with allowBackwardCrawling:true returned 12,403 chars vs 0 baseline."
  }
}

The agent generates each answer / fixParameters / validation.evidence per request, from the caller's specific job logs — there's no canonical "robots.txt → allowBackwardCrawling" mapping in the agent. Showing this example invites readers (and downstream LLMs reading the docs) to apply it to unrelated failures even though it's a snapshot from one particular run.

Replaced with neutral <...> placeholders and an explicit one-liner clarifying that the example shows the shape, not a real diagnosis:

{
  "answer": "<2-4 sentence prose diagnosis of the issue plus the recommended fix.>",
  "confidence": "high",
  "fixParameters": { "<param>": "<value>" },
  "validation": {
    "tested": true,
    "result": "success",
    "evidence": "<short summary of the validation tool call the agent ran to confirm the fix>"
  },
  "feedback": null,
  "durationMs": 18432
}

The actual answer, fixParameters, and validation.evidence are produced per request by the agent based on your specific run; the example above shows the response shape, not a real diagnosis.

Companion PRs

• firecrawl/support-agent#4 — drop usage from the AnswerEnvelope interface (source of truth).
• firecrawl/firecrawl-web#2096 — drop usage from the playground Debug modal's validation schema.
• firecrawl/cli#108 — drop usage from the CLI's AskResponse type.
• firecrawl/firecrawl-mcp-server#228 — drop usage from the firecrawl_ask tool's Returns description.

Test plan

• Mintlify renders the response example without the usage line.
• OpenAPI-generated reference page no longer shows usage under AskResponse.
• The example block in features/ask.mdx reads as obviously templated (<...> placeholders) rather than as factual guidance.

🤖 Generated with Claude Code

---

[mintlify]

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

Project	Status	Preview	Updated (UTC)
firecrawl	🟢 Ready	View Preview	May 7, 2026, 2:31 PM

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

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.