> ## Documentation Index
> Fetch the complete documentation index at: https://docs.the40thieves.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# record_retrieval_feedback

> Report which retrieved chunks actually helped.

Report which retrieved chunks actually helped. CALL THIS after you act on a search result: feedback (-1|0|+1) = was this the right chunk to return for that query. Stamp the chunks you genuinely used, not every hit, and stamp -1 when a confidently-returned chunk was wrong — a negative is worth more than silence. This is the only signal separating a chunk that gets RETRIEVED from one that gets USED: it feeds the ACT-R activation recompute, so stamping is what makes later retrieval better, and not stamping leaves ranking blind. Judge the RETRIEVAL, not your task: whether the task went well is a different question this tool deliberately no longer accepts. Several chunks at once: send verdicts: \[\{chunk\_id, feedback}, ...] (1-50 items), applied in one transaction. Otherwise send chunk\_id + feedback for one chunk. Send one form or the other, never both. Each target is your most recent retrieval event(s) for that chunk (last\_n, default 1, applies to every item). Returns `updated`; when that is 0 it also returns `reason` — `session_scope` (you own retrievals for this chunk, none in the current scope) or `no_owned_retrievals` (nothing of yours matches), so a no-op is never silent. A batch returns `results`, one \{chunk\_id, updated, reason?} per verdict. You may only stamp retrievals your own caller produced; an unidentified caller cannot stamp, and admin:workspace crosses both that and the session scope.

| | |
| - | - |
| **Domain** | knowledge |
| **Scopes** | `write:workspace` |
| **Access** | write |
| **Tags** | `writes`, `domain:knowledge`, `experiential` |
| **Profile** | core, full |

## Annotations

| Annotation | Value |
| - | - |
| Read-only | no |
| Destructive | no |
| Idempotent | no |
| Accepts an idempotency key | no |

`Idempotent` is the advisory MCP `idempotentHint`. `Destructive` is also `yes` for a tool that
asks for confirmation only on some calls.

## Confirmation (human in the loop)

No human confirmation is required to call this tool.

## Input

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `chunk_id` | `string` | | — | Single form: the chunk to stamp. Send chunk\_id + feedback together, or verdicts, never both. length ≥ 1 |
| `feedback` | `integer` | | — | Single form: -1, 0 or +1 for chunk\_id. Send it with chunk\_id. range -1–1 |
| `verdicts` | `object[]` | | — | Batch form (1-50 items): one \{chunk\_id, feedback} per chunk, all applied in one transaction. Send verdicts OR chunk\_id + feedback, never both. items 1–50 |
| `verdicts[].chunk_id` | `string` | with parent | — | length ≥ 1 |
| `verdicts[].feedback` | `integer` | with parent | — | range -1–1 |
| `session_id` | `string` | | — | Session scope for the stamp. Applies to every verdict in a batch. |
| `last_n` | `integer` | | `1` | How many of each chunk's most recent retrievals to stamp (default 1). Applies to every verdict in a batch. range 1–50 |

## Output

| Field | Type | Always present | Description |
| - | - | - | - |
| `available` | `boolean` | yes | — |
| `message` | `string` | | — |
| `chunk_id` | `string` | | — |
| `updated` | `integer` | | range ≥ -9007199254740991 |
| `reason` | `enum` | | One of: `"session_scope"`, `"no_owned_retrievals"` |
| `results` | `object[]` | | — |
| `results[].chunk_id` | `string` | with parent | — |
| `results[].updated` | `integer` | with parent | range ≥ -9007199254740991 |
| `results[].reason` | `enum` | | One of: `"session_scope"`, `"no_owned_retrievals"` |

## Related tools

Other tools in the `knowledge` domain: [`add_observation`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/add_observation/), [`audit_provenance`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/audit_provenance/), [`close_goal`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/close_goal/), [`commit_capture`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/commit_capture/), [`commit_wiki_page`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/commit_wiki_page/), [`create_entity`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/create_entity/), [`delete_entity`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/delete_entity/), [`diagnose_retrieval`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/diagnose_retrieval/), [`draft_wiki_page`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/draft_wiki_page/), [`end_session`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/end_session/), [`enqueue_capture`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/enqueue_capture/), [`episode_stats`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/episode_stats/), [`explain_answer`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/explain_answer/), [`find_existing_page`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/find_existing_page/), [`gap_report`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/gap_report/), [`get_entity`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/get_entity/), [`get_session_traces`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/get_session_traces/), [`knowledge_challenge`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/knowledge_challenge/), [`link_entities`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/link_entities/), [`lint_wiki`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/lint_wiki/), [`list_capture_queue`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/list_capture_queue/), [`list_contradictions`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/list_contradictions/), [`list_goals`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/list_goals/), [`note_quality_report`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/note_quality_report/), [`plur_get`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/plur_get/), [`plur_recall`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/plur_recall/), [`plur_recall_hybrid`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/plur_recall_hybrid/), [`plur_similarity_search`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/plur_similarity_search/), [`query_entity_graph`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/query_entity_graph/), [`reflect`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/reflect/), [`rename_entity`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/rename_entity/), [`session_bootstrap`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/session_bootstrap/), [`set_goal`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/set_goal/), [`start_session`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/start_session/), [`unlink_entities`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/unlink_entities/), [`update_observation`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/update_observation/), [`vault_context`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/vault_context/), [`vault_graph_search`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/vault_graph_search/), [`work_episode_chain`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/work_episode_chain/), [`work_episodes`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/work_episodes/), [`work_forget`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/work_forget/), [`work_result`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/work_result/), [`work_search`](https://docs.the40thieves.dev/reliquary-tc/tools/reference/work_search/).

Back to the [tool catalog](https://docs.the40thieves.dev/reliquary-tc/tools/tool-catalog.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.