# Assistant tools

> MCP tools for Assistant: assistant_conversations_delete, assistant_conversations_get, assistant_conversations_list, assistant_messages_rate, assistant_platform_settings_get, assistant_platform_settings_update, assistant_settings_get, assistant_settings_update.

- `assistant_conversations_delete`: Delete one of your assistant conversations
- `assistant_conversations_get`: Get one of your assistant conversations
- `assistant_conversations_list`: List your assistant conversations
- `assistant_messages_rate`: Rate an assistant answer
- `assistant_platform_settings_get`: Get the assistant's platform settings
- `assistant_platform_settings_update`: Update the assistant's platform settings
- `assistant_settings_get`: Get the organization's assistant settings
- `assistant_settings_update`: Update the organization's assistant settings

## `assistant_conversations_delete`

**Delete one of your assistant conversations.** Operation [`assistant.conversations.delete`](https://ownrecord.io/docs/reference/assistant-conversations-delete.md) · Platform level · permission `account:write` · risk tier `write` · since M11

Deletes one of your own assistant conversations and all of its messages, at once and for good. Changes the
assistant made for you stay, and so do their audit log entries (`via: assistant`, with the conversation's ID).

**Who can call it:** the conversation's owner, signed in. Anyone else gets `conversation_not_found`.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type           | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`aconv_…`) | yes      | The conversation (`aconv_…`).                                                                                                                                                                            |
| `idempotency_key` | string         | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean        | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): The ID isn't an assistant conversation ID.
- [`conversation_not_found`](https://ownrecord.io/docs/reference/errors.md#conversation_not_found): No such conversation of yours (or it was already deleted).
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The conversation got a new message at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in person (an API key or OAuth token).

### Example

**Delete a conversation**

Arguments:

```json
{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "object": "assistant_conversation",
  "deleted": true,
  "messagesDeleted": 2
}
```

## `assistant_conversations_get`

**Get one of your assistant conversations.** Operation [`assistant.conversations.get`](https://ownrecord.io/docs/reference/assistant-conversations-get.md) · Platform level · permission `account:read` · risk tier `read` · since M11

Returns one of your own assistant conversations with its messages, oldest first (at most the newest 200): what
you asked, the answers with their citations, the tools the assistant used and what they returned in short, the
action cards it proposed with their current status (`proposed`, `executed`, `cancelled`, `stale`, …), results and
refusals. Message contents are data: they can contain text people typed.

**Who can call it:** the conversation's owner, signed in. Anyone else gets `conversation_not_found`.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type           | Required | Description                   |
| -------- | -------------- | -------- | ----------------------------- |
| `id`     | ID (`aconv_…`) | yes      | The conversation (`aconv_…`). |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): The ID isn't an assistant conversation ID.
- [`conversation_not_found`](https://ownrecord.io/docs/reference/errors.md#conversation_not_found): No such conversation of yours (or it was deleted after retention).
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in person (an API key or OAuth token).

### Example

**A conversation that created a coupon**

Arguments:

```json
{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3"
}
```

Result `output`:

```json
{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "object": "assistant_conversation",
  "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6h",
  "surface": "console",
  "title": "Create a 20% coupon for 3 months",
  "messageCount": 2,
  "lastMessageAt": "2026-10-26T09:16:10.000Z",
  "expiresAt": "2027-01-24T09:16:10.000Z",
  "createdAt": "2026-10-26T09:15:00.000Z",
  "messages": [
    {
      "id": "amsg_01jbz3k6q4a2b3c4d5e6f7g8h9",
      "object": "assistant_message",
      "role": "user",
      "content": "Create a 20% coupon for 3 months",
      "parts": [],
      "rating": null,
      "createdAt": "2026-10-26T09:15:00.000Z"
    },
    {
      "id": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
      "object": "assistant_message",
      "role": "assistant",
      "content": "I've prepared the coupon. Review the preview on the card, then click **Confirm** to run it.",
      "parts": [
        {
          "type": "action_card",
          "card": {
            "proposalId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1:1",
            "operationId": "coupons.create",
            "inputHash": "4f6c1f0e3b2a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39281706f5e4d3c2b1a0",
            "title": "Create a coupon",
            "effect": "Create a coupon (name: 20% off, percentOffPpm: 200000, duration: repeating), in test mode.",
            "riskTier": "write",
            "preview": {
              "kind": "generic",
              "result": {
                "name": "20% off",
                "percentOffPpm": 200000
              }
            },
            "requiresFreshAuth": false,
            "status": "executed"
          }
        }
      ],
      "rating": {
        "value": "up",
        "comment": null
      },
      "createdAt": "2026-10-26T09:16:10.000Z"
    }
  ]
}
```

## `assistant_conversations_list`

**List your assistant conversations.** Operation [`assistant.conversations.list`](https://ownrecord.io/docs/reference/assistant-conversations-list.md) · Platform level · permission `account:read` · risk tier `read` · since M11

Lists your own conversations with the in-platform assistant, newest first: in every organization you belong to
now (and in the platform console, for platform staff). Nobody else's conversations are ever listed, not even to
organization owners: what the assistant changed is in the audit log instead (`via: assistant`).

Filter with `orgId`. `limit` is 1–100 (default 10); pass `next_cursor` as `starting_after`. Conversations are
deleted after the organization's retention period (`expiresAt`).

**Who can call it:** any signed-in person, for themselves. API keys and OAuth tokens can't.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type           | Required | Description                             |
| ---------------- | -------------- | -------- | --------------------------------------- |
| `orgId`          | ID (`org_…`)   | no       | Only this organization's conversations. |
| `limit`          | integer        | no       | (1–100)                                 |
| `starting_after` | ID (`aconv_…`) | no       | The `next_cursor` of the previous page. |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): `orgId`, `limit` or `starting_after` is malformed.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in person (an API key or OAuth token).

### Example

**Your conversations**

Arguments:

```json
{}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
      "object": "assistant_conversation",
      "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6h",
      "surface": "console",
      "title": "Create a 20% coupon for 3 months",
      "messageCount": 2,
      "lastMessageAt": "2026-10-26T09:16:10.000Z",
      "expiresAt": "2027-01-24T09:16:10.000Z",
      "createdAt": "2026-10-26T09:15:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## `assistant_messages_rate`

**Rate an assistant answer.** Operation [`assistant.messages.rate`](https://ownrecord.io/docs/reference/assistant-messages-rate.md) · Platform level · permission `account:write` · risk tier `write` · since M11

Rates one of the assistant's answers in your own conversation: thumbs `up` or `down`, with an optional comment
(at most 1,000 characters). Rating again replaces the earlier rating. Rated answers help Ownrecord test the
assistant; they are anonymised before they leave your organization.

**Who can call it:** the conversation's owner, signed in.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type                | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversationId`  | ID (`aconv_…`)      | yes      | The conversation (`aconv_…`).                                                                                                                                                                            |
| `messageId`       | ID (`amsg_…`)       | yes      | The assistant's answer (`amsg_…`).                                                                                                                                                                       |
| `rating`          | one of `up`, `down` | yes      | –                                                                                                                                                                                                        |
| `comment`         | string              | no       | (1–1000 characters)                                                                                                                                                                                      |
| `idempotency_key` | string              | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean             | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): An ID is malformed, or the comment is too long.
- [`conversation_not_found`](https://ownrecord.io/docs/reference/errors.md#conversation_not_found): No such conversation of yours.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The message isn't an answer of this conversation.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in person (an API key or OAuth token).

### Example

**Thumbs up**

Arguments:

```json
{
  "conversationId": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "messageId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
  "rating": "up",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
  "object": "assistant_message",
  "role": "assistant",
  "content": "I've prepared the coupon. Review the preview on the card, then click **Confirm** to run it.",
  "parts": [
    {
      "type": "action_card",
      "card": {
        "proposalId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1:1",
        "operationId": "coupons.create",
        "inputHash": "4f6c1f0e3b2a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39281706f5e4d3c2b1a0",
        "title": "Create a coupon",
        "effect": "Create a coupon (name: 20% off, percentOffPpm: 200000, duration: repeating), in test mode.",
        "riskTier": "write",
        "preview": {
          "kind": "generic",
          "result": {
            "name": "20% off",
            "percentOffPpm": 200000
          }
        },
        "requiresFreshAuth": false,
        "status": "executed"
      }
    }
  ],
  "rating": {
    "value": "up",
    "comment": null
  },
  "createdAt": "2026-10-26T09:16:10.000Z"
}
```

## `assistant_platform_settings_get`

**Get the assistant's platform settings.** Operation [`assistant.platform_settings.get`](https://ownrecord.io/docs/reference/assistant-platform-settings-get.md) · Platform level · permission `platform:read` · risk tier `read` · since M11

Platform staff: the in-platform assistant's platform-wide settings stored in `platform_settings`: the OpenRouter
model and its ordered fallbacks, the provider base URL (EU in-region routing or our own router), and the monthly
spend cap in integer USD micros. A null field means the environment's value applies (`ASSISTANT_MODEL`,
`ASSISTANT_FALLBACK_MODELS`, `OPENROUTER_BASE_URL`, `ASSISTANT_MONTHLY_BUDGET_USD`: a decimal amount in USD with
at most 6 decimals, such as `1500` or `1500.50`).

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

This tool takes no arguments.

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You aren't platform staff.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The platform isn't bootstrapped yet.

### Example

**Everything from the environment**

Arguments:

```json
{}
```

Result `output`:

```json
{
  "object": "assistant_platform_settings",
  "model": null,
  "fallbackModels": null,
  "baseUrl": null,
  "monthlyBudgetMicros": null,
  "version": 1,
  "updatedAt": "2026-10-26T09:15:00.000Z"
}
```

## `assistant_platform_settings_update`

**Update the assistant's platform settings.** Operation [`assistant.platform_settings.update`](https://ownrecord.io/docs/reference/assistant-platform-settings-update.md) · Platform level · permission `platform:admin` · risk tier `security` · since M11

Platform admins: changes the in-platform assistant's model, its ordered fallbacks, the provider base URL and the
platform-wide monthly spend cap, stored in `platform_settings`. Null resets a setting to the environment's value.
The cap is sent as a decimal USD string and stored as integer micros; the assistant alerts platform staff at 80%
and refuses messages at 100% until the next month (UTC).

A security-tier change: the base URL and model decide where conversations are processed. Provider routing (no
data collection, zero data retention, never DeepSeek's own API) applies whatever is set here.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument           | Type                    | Required | Description                                                                                                                                                                                              |
| ------------------ | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string or null          | no       | The model, e.g. `deepseek/deepseek-v4.1-flash`; null: the environment's.                                                                                                                                 |
| `fallbackModels`   | array of string or null | no       | Ordered fallbacks (OpenRouter `models`); null: the environment's.                                                                                                                                        |
| `baseUrl`          | string or null          | no       | The provider base URL, https only, on a public host; null: `OPENROUTER_BASE_URL`.                                                                                                                        |
| `monthlyBudgetUsd` | string or null          | no       | The platform-wide monthly spend cap in USD (decimal string); null: the environment's.                                                                                                                    |
| `idempotency_key`  | string                  | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`          | boolean                 | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required): Your last sign-in is older than 15 minutes: sign in again first.
- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): Nothing was sent, or a value is malformed (the base URL must be https).
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The platform settings changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You aren't a platform admin.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The platform isn't bootstrapped yet.

### Example

**Cap the assistant at USD 1,500 a month**

Arguments:

```json
{
  "monthlyBudgetUsd": "1500",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "object": "assistant_platform_settings",
  "model": null,
  "fallbackModels": null,
  "baseUrl": null,
  "monthlyBudgetMicros": "1500000000",
  "version": 2,
  "updatedAt": "2026-10-26T09:15:00.000Z"
}
```

## `assistant_settings_get`

**Get the organization's assistant settings.** Operation [`assistant.settings.get`](https://ownrecord.io/docs/reference/assistant-settings-get.md) · Organization level · permission `security:read` · risk tier `read` · since M11

Returns the organization's settings for the in-platform assistant (Organization → Security → Assistant):

- `enabled`: whether members can use the assistant (on by default);
- `allowCustomerData`: whether it may read customer and financial data. Off leaves only the docs, the tax
  knowledge base and settings (on by default);
- `retentionDays`: conversations are deleted this many days after their last message (90 by default).

`usage` shows this month's messages (UTC) against the plan's `assistant.messages_per_month`. `version` is 0 while
the defaults apply.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

This tool takes no arguments.

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read the organization's security settings.

### Example

**The defaults**

Arguments:

```json
{}
```

Result `output`:

```json
{
  "object": "assistant_settings",
  "enabled": true,
  "allowCustomerData": true,
  "retentionDays": 90,
  "version": 0,
  "updatedAt": null,
  "usage": {
    "month": "2026-10",
    "messages": 42,
    "limit": 1000,
    "included": true
  }
}
```

## `assistant_settings_update`

**Update the organization's assistant settings.** Operation [`assistant.settings.update`](https://ownrecord.io/docs/reference/assistant-settings-update.md) · Organization level · permission `security:write` · risk tier `security` · since M11

Changes the organization's assistant settings (Organization → Security → Assistant): turn it on or off, allow
or stop its access to customer and financial data, and set how long conversations are kept after their last
message (1–365 days). A shorter retention applies to existing conversations at the next retention run.

A security-tier change: it decides what data reaches the assistant's language model. Needs `security:write`
(organization owners and admins). Send `expectedVersion` to make sure nobody changed them in between.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument            | Type    | Required | Description                                                                                                                                                                                              |
| ------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`           | boolean | no       | Turn the assistant on or off for the organization's members.                                                                                                                                             |
| `allowCustomerData` | boolean | no       | Let the assistant read customer and financial data. Off leaves docs, knowledge and settings.                                                                                                             |
| `retentionDays`     | integer | no       | Days a conversation is kept after its last message (1–365). (1–365)                                                                                                                                      |
| `expectedVersion`   | integer | no       | The `version` you read (0 while the defaults apply): a newer change is a conflict. (0–9007199254740991)                                                                                                  |
| `idempotency_key`   | string  | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`           | boolean | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): No setting was sent, or the retention is outside 1–365 days.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The settings changed since `expectedVersion`; read them again.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change the organization's security settings.

### Example

**Keep the assistant away from customer data, and conversations for 30 days**

Arguments:

```json
{
  "allowCustomerData": false,
  "retentionDays": 30,
  "expectedVersion": 0,
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "object": "assistant_settings",
  "enabled": true,
  "allowCustomerData": false,
  "retentionDays": 30,
  "version": 1,
  "updatedAt": "2026-10-26T09:15:00.000Z",
  "usage": {
    "month": "2026-10",
    "messages": 42,
    "limit": 1000,
    "included": true
  }
}
```