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

# Discord tools

> Reference all twelve Discord tools the agent uses for embeds, pings, file sending, forks, reminders, and chains.

ollim-bot gives the agent twelve Discord tools for sending messages, sending files, managing forks, reporting findings, scheduling reminders, and scheduling follow-ups — all without direct access to the Discord API.

The agent also has access to a docs server — a remote server at [`docs.ollim.ai/mcp`](https://docs.ollim.ai/mcp) that lets it look up its own documentation and architecture.

## Output tools

These tools send visible messages to the Discord channel.

### `discord_embed`

Available in all contexts. Send a rich embed message with optional action buttons.

| Parameter     | Type    | Required | Default  | Description                                                                                              |
| ------------- | ------- | -------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `title`       | string  | Yes      | —        | Embed title                                                                                              |
| `description` | string  | No       | —        | Embed body text                                                                                          |
| `color`       | string  | No       | `"blue"` | `blue` (info), `green` (success), `red` (urgent), `yellow` (warning), `purple` (fork)                    |
| `fields`      | array   | No       | `[]`     | Objects with `name` (string, required), `value` (string, required), `inline` (boolean, optional)         |
| `buttons`     | array   | No       | `[]`     | Objects with `label` (string, required), `action` (string, required), `style` (string, optional). Max 5. |
| `critical`    | boolean | No       | `false`  | Bypasses per-session limit, busy check, and ping budget when `true`                                      |

**Button actions** follow a `type:payload` format:

| Action                 | Description                     |
| ---------------------- | ------------------------------- |
| `task_done:<task_id>`  | Mark a Google Task as complete  |
| `task_del:<task_id>`   | Delete a Google Task            |
| `event_del:<event_id>` | Delete a Google Calendar event  |
| `dismiss:`             | Delete the embed message        |
| `agent:<prompt>`       | Send a prompt back to the agent |

**Button styles:** `success`, `danger`, `primary`, `secondary`.

**Availability:** Main session, interactive forks, and background forks. In background forks, the embed is blocked if `allow-ping` is `false`, the user is mid-conversation (unless `critical` is `true`), or the [ping budget](/scheduling/ping-budget) is exhausted. A source tag (`bg` or `fork`) is added to the embed footer when not in the main session.

### `ping_user`

Background-fork-only. Send a plain text alert prefixed with `[bg]`.

| Parameter  | Type    | Required | Default | Description                                                         |
| ---------- | ------- | -------- | ------- | ------------------------------------------------------------------- |
| `message`  | string  | Yes      | —       | The message to send                                                 |
| `critical` | boolean | No       | `false` | Bypasses per-session limit, busy check, and ping budget when `true` |

**Availability:** Background forks only. Not available in the main session or interactive forks. Subject to the same `allow-ping`, busy check, and ping budget gates as `discord_embed`.

### `send_file`

Available in all contexts. Send a file from the local filesystem as a Discord DM attachment — documents, images, logs, or any file you need. Max 25 MB (Discord limit).

| Parameter   | Type    | Required | Default | Description                                                           |
| ----------- | ------- | -------- | ------- | --------------------------------------------------------------------- |
| `file_path` | string  | Yes      | —       | Path to the file (absolute or `~/...`)                                |
| `message`   | string  | No       | —       | Optional message to accompany the file                                |
| `critical`  | boolean | No       | `false` | Set `true` only when the user would be devastated if they missed this |

The tool validates that the path points to an existing regular file via `path.is_file()`, supports tilde expansion, and enforces Discord's 25 MB size limit.

**Availability:** Main session, interactive forks, and background forks. In **background forks**, the tool is blocked if `allow-ping` is `false`, subject to the [ping budget](/scheduling/ping-budget), and prefixes messages with `[bg]`.

<Note>
  All three output tools register the message so that replies are correctly routed back to the fork that sent them.
</Note>

## Fork management tools

These tools control [interactive fork](/core-usage/forks) lifecycle.

### `enter_fork`

Start an interactive fork branching from the main session.

| Parameter      | Type    | Required | Default                                                               | Description                                  |
| -------------- | ------- | -------- | --------------------------------------------------------------------- | -------------------------------------------- |
| `topic`        | string  | No       | —                                                                     | Optional topic label for the fork            |
| `idle_timeout` | integer | No       | [`fork_idle_timeout`](/configuration/reference#runtime-configuration) | Minutes before the idle timeout prompt fires |

**Availability:** Main session only. Returns an error if already inside any fork (interactive or background). The fork interrupts the current agent turn immediately.

### `save_context`

Request to promote the current interactive fork to the main session. Instead of executing directly, this tool sends a yellow confirmation embed to Discord with three buttons:

| Button             | Style   | Action                                   |
| ------------------ | ------- | ---------------------------------------- |
| **Confirm**        | Green   | Promotes the fork to the main session    |
| **Report Instead** | Blurple | Switches to report mode                  |
| **Dismiss**        | Grey    | Deletes the embed and continues the fork |

The save only happens when you click **Confirm** — the agent cannot assume the save succeeded. This prevents unintended saves when the agent calls the tool proactively.

Takes no parameters.

**Availability:** Interactive forks only. Returns an error in background forks or the main session.

<Warning>
  Most forks don't qualify — see [exit strategies](/core-usage/forks#exit-strategies)
  for when to use this vs. other options.
</Warning>

### `report_updates`

Report a summary from the current fork to the main session. The summary is injected into the next main-session interaction via `pending_updates.json`.

| Parameter | Type   | Required | Default | Description                     |
| --------- | ------ | -------- | ------- | ------------------------------- |
| `message` | string | Yes      | —       | Short summary of what was found |

<Tabs>
  <Tab title="Interactive fork">
    Sets the exit action to `REPORT`. The fork is discarded after the agent finishes responding — further tool calls delay the exit.
  </Tab>

  <Tab title="Background fork">
    Appends the update and marks the fork as reported. The fork continues running. Blocked if `update-main-session` is set to `blocked` in the background fork config.
  </Tab>
</Tabs>

**Availability:** Interactive forks and background forks. Returns an error in the main session.

### `exit_fork`

Exit the current interactive fork. The fork is discarded and the main session resumes. No context is preserved.

Takes no parameters.

**Availability:** Interactive forks only. Returns an error in background forks or the main session.

## Reminder tools

These tools manage [reminders](/scheduling/reminders) — one-shot time-based prompts. Available in the main session, interactive forks, and background forks.

### `add_reminder`

Schedule a one-shot reminder. Provide either `delay_minutes` or `run_at` — not both.

| Parameter       | Type    | Required | Default | Description                                                                                                   |
| --------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `prompt`        | string  | Yes      | —       | Instructions for the agent at fire time                                                                       |
| `delay_minutes` | integer | No       | —       | Fire in N minutes from now                                                                                    |
| `run_at`        | string  | No       | —       | ISO datetime (e.g. `2026-03-13T15:00`). Uses bot timezone if no offset.                                       |
| `description`   | string  | No       | `""`    | Short summary shown in the reminder list                                                                      |
| `foreground`    | boolean | No       | `false` | Use only when the user wants to watch tool actions stream. Background with `ping_user` handles notifications. |
| `max_chain`     | integer | No       | `0`     | Max follow-up chain depth (0 = plain one-shot)                                                                |

**Availability:** Main session, interactive forks, and background forks. Reminder tools are not gated by `allow-ping` — they are data operations, not output operations.

### `list_reminders`

List all pending reminders with their IDs, scheduled times, modes, and descriptions. Takes no parameters.

**Availability:** Main session, interactive forks, and background forks.

### `cancel_reminder`

Cancel a pending reminder by ID.

| Parameter     | Type   | Required | Default | Description           |
| ------------- | ------ | -------- | ------- | --------------------- |
| `reminder_id` | string | Yes      | —       | Reminder ID to cancel |

**Availability:** Main session, interactive forks, and background forks.

## Chain tool

### `follow_up_chain`

Schedule a follow-up reminder that continues the current chain. Used by [reminders](/scheduling/reminders) with `max-chain` to create self-continuing check-in sequences.

| Parameter          | Type    | Required | Default | Description                        |
| ------------------ | ------- | -------- | ------- | ---------------------------------- |
| `minutes_from_now` | integer | Yes      | —       | Minutes until the next check fires |

The tool creates a new reminder with the chain depth incremented by one. The tool forwards all configuration from the current chain: `background`, `model`, `thinking`, `isolated`, `update-main-session`, `allow-ping`, `allowed-tools`, and `skills`.

Returns an error if:

* No active reminder context exists (the tool was called outside a reminder-triggered session)
* The chain depth has reached `max-chain` — the error includes recovery
  guidance: "follow-up limit reached — this was the last check. If the
  task still needs attention, ping the user now."

<Tip>
  If the task is done or no follow-up is needed, don't call `follow_up_chain`. The chain ends naturally.
</Tip>

## Configuration tool

### `update_names`

Update the bot and user display names. Writes to `.env` and takes effect after `/restart`.

| Parameter   | Type   | Required | Default | Description         |
| ----------- | ------ | -------- | ------- | ------------------- |
| `user_name` | string | Yes      | —       | User's display name |
| `bot_name`  | string | Yes      | —       | Bot's display name  |

Returns an error if either name is empty.

**Availability:** Main session only. Returns an error in interactive forks and background forks.

## Background fork enforcement

Background forks enforce the `update-main-session` policy before the agent can finish:

| Mode      | Behavior                                                                       |
| --------- | ------------------------------------------------------------------------------ |
| `freely`  | No enforcement — reporting is optional                                         |
| `blocked` | No enforcement — `report_updates` is blocked                                   |
| `always`  | Agent prompted to "summarize what you found or did to update the main session" |
| `on_ping` | Agent must call `report_updates` if it sent any visible output (ping or embed) |

See [background forks](/scheduling/background-forks) for how these modes are configured in routine and reminder YAML frontmatter.

## Next steps

<Columns cols={2}>
  <Card title="Forks" icon="code-branch" href="/core-usage/forks">
    How interactive and background forks work.
  </Card>

  <Card title="Background forks" icon="gears" href="/scheduling/background-forks">
    Configuration for background fork behavior, tool restrictions, and update modes.
  </Card>

  <Card title="Ping budget" icon="bell" href="/scheduling/ping-budget">
    How the refill-on-read budget gates output tools.
  </Card>

  <Card title="System prompt" icon="scroll" href="/development/system-prompt">
    How tool instructions are injected into the agent's system prompt.
  </Card>
</Columns>