# MCP tools

Source: https://docs.getdeeprecall.com/reference/mcp-tools/

> Exact inputs and behavior for recall, ask, remember, and forget.

Deep Recall exposes four MCP tools over Streamable HTTP. Inputs reject unknown fields.

Successful tool results include a JSON text content block and `structuredContent` with the same payload. Errors are sanitized; inspect `isError` instead of treating every tool response as success.

## recall

Search without answer generation. Requires `memory:read`.

| Field             | Type                     | Default or limit                                                 |
| ----------------- | ------------------------ | ---------------------------------------------------------------- |
| `query`           | string, required         | Trimmed, 1–2,000 characters                                      |
| `top_k`           | integer                  | 20; range 1–50                                                   |
| `types`           | array                    | Empty; unique `fact`, `episode`, `foresight`                     |
| `tags`            | string array             | Empty; up to 50 unique tags, 1–100 characters each               |
| `expand_entities` | boolean                  | `false`                                                          |
| `at`              | ISO datetime with offset | Optional evaluation time                                         |
| `session_id`      | UUID                     | Optional                                                         |
| `agent_id`        | UUID                     | Optional legacy field; cannot override authenticated attribution |

```json
{ "query": "November launch decisions", "top_k": 5, "types": ["fact", "foresight"] }
```

Returns `at`, `memories`, and `total`. Hits include stored content and supporting metadata. Ready image sources may include access-bearing `image_url` values that expire after one hour; recall again for a fresh link. Treat these links as private.

## ask

Generate a grounded answer with memory citations. Requires `memory:read`.

| Field        | Type                     | Default or limit                                                 |
| ------------ | ------------------------ | ---------------------------------------------------------------- |
| `question`   | string, required         | Trimmed, 1–4,000 characters                                      |
| `top_k`      | integer                  | 30; range 1–50                                                   |
| `max_tokens` | positive integer         | Optional                                                         |
| `at`         | ISO datetime with offset | Optional                                                         |
| `session_id` | UUID                     | Optional                                                         |
| `agent_id`   | UUID                     | Optional legacy field; cannot override authenticated attribution |

```json
{ "question": "Why did we choose email invitations?", "top_k": 10 }
```

Returns `answer`, `at`, `based_on` memory IDs, source `memories`, and model/usage metadata. Citations must support the answer. Do not invent evidence when grounding is empty.

## remember

Queue a save. Requires `memory:write`.

| Field     | Type             | Limit                         |
| --------- | ---------------- | ----------------------------- |
| `content` | string, required | Trimmed, 1–100,000 characters |

```json
{
  "content": "For the November launch we chose email invitations because customers already use that channel."
}
```

Returns `job_id` and `status`, normally `queued`. This is **content only**: do not send structured candidates, timestamps, tags, confidence, or entity fields. The REST save contract differs. See [save and verify](/agents/save-and-verify/).

## forget

Suppress or permanently delete one identified memory. Requires `memory:write`.

| Field         | Type           | Default or limit                                                         |
| ------------- | -------------- | ------------------------------------------------------------------------ |
| `memory_id`   | UUID, required | Existing memory owned by the user                                        |
| `hard`        | boolean        | `false` for recoverable suppression                                      |
| `reason_code` | string         | `other`; one of `duplicate`, `incorrect`, `private`, `outdated`, `other` |

```json
{ "memory_id": "00000000-0000-4000-8000-000000000001", "reason_code": "outdated" }
```

The ID above is illustrative; use an ID returned by the service. Returns `action`, `memory_id`, and `message`. Suppression is recoverable through the human Restore action. `hard: true` is permanent and requires the user’s explicit intent.

Pinning, restoring, export, document upload, account settings, and job-status polling are not additional MCP tools. Use their supported first-party surfaces.