Send structured feedback on a previous `firecrawl_search` result. **Call this immediately after a search where you used the results** so we can improve search quality and refund 1 credit (search costs 2).
Pass the `searchId` returned by `firecrawl_search` (the `id` field on the response) and tell us:
- **rating** — overall result quality: `good`, `partial`, or `bad`.
- **valuableSources** — which result URLs were actually useful, and a short reason why.
- **missingContent** — **the most important field.** An ARRAY of specific pieces of content you expected to find but didn't. One entry per missing piece, each with a short `topic` and an optional longer `description`. Examples: `{"topic":"enterprise pricing","description":"no pricing tier table for the Enterprise plan was returned"}`, `{"topic":"API rate limits"}`, `{"topic":"comparison vs competitors"}`. **Be specific** — these aggregate across teams and tell us what to index next. Do not pack multiple topics into one entry.
- **querySuggestions** — how the query or response shape could be improved (e.g. "would have liked official docs first", "should boost github.com").
**Substantive-feedback requirement** (zero-effort feedback is rejected with HTTP 400):
- `good` — must include at least one `valuableSources` entry
- `partial` — must include `valuableSources` or at least one `missingContent` entry
- `bad` — must include at least one `missingContent` entry or `querySuggestions`
**Time window:** Feedback must be submitted within ~2 minutes of the search. Beyond that, the call returns HTTP 409 with `feedbackErrorCode: "FEEDBACK_WINDOW_EXPIRED"` — do not retry, just move on. Same goes for any 4xx response: do not retry-loop.
**Behaviors:**
- Idempotent per `searchId`. Re-submitting for the same id returns `alreadySubmitted: true` with `creditsRefunded: 0`.
- Refund only applies to billable searches; preview teams are blocked.
- Failed searches cannot receive feedback (the search itself already returned an error you can act on).
- **Daily refund cap (per team, per UTC day, default 100 credits).** Once a team's `creditsRefundedToday` reaches `dailyRefundCap`, the response returns `dailyCapReached: true` with `creditsRefunded: 0`. The feedback is still recorded for search-quality improvement — only the credit refund is gated. **Stop calling this tool for the rest of the UTC day** when you see `dailyCapReached: true`.
**When to call:** Right after processing a search result. If the result didn't help, send rating `bad` with a clear `missingContent` — that is just as valuable as a `good` rating.
**Usage Example (good rating with valuable sources + missing content):**
```json
{
"name": "firecrawl_search_feedback",
"arguments": {
"searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
"rating": "good",
"valuableSources": [
{ "url": "https://docs.firecrawl.dev/features/search", "reason": "Most up-to-date description of /search." }
],
"missingContent": [
{ "topic": "Pricing for the search endpoint", "description": "No pricing tier table for /search specifically." },
{ "topic": "Rate limits", "description": "Per-team RPS for /search not documented." }
],
"querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
}
}
```
**Usage Example (bad rating, what was missing):**
```json
{
"name": "firecrawl_search_feedback",
"arguments": {
"searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
"rating": "bad",
"missingContent": [
{ "topic": "Recent benchmarks", "description": "All results were >12 months old." },
{ "topic": "Comparison vs Algolia" }
]
}
}
```
**Returns:** `{ success, feedbackId, creditsRefunded, creditsRefundedToday, dailyRefundCap, dailyCapReached?, alreadySubmitted?, warning? }` JSON.
