Discord tools

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 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 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, and prefixes messages with [bg].

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

Fork management tools

These tools control interactive fork 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`	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.

Most forks don’t qualify — see exit strategies for when to use this vs. other options.

`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

Interactive fork
Background fork

Sets the exit action to REPORT. The fork is discarded after the agent finishes responding — further tool calls delay the exit.

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.

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 — 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 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.”

If the task is done or no follow-up is needed, don’t call follow_up_chain. The chain ends naturally.

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 for how these modes are configured in routine and reminder YAML frontmatter.

Next steps

Forks

How interactive and background forks work.

Background forks

Configuration for background fork behavior, tool restrictions, and update modes.

Ping budget

How the refill-on-read budget gates output tools.

System prompt

How tool instructions are injected into the agent’s system prompt.

Personalizing

Self-Hosting

Output tools

`discord_embed`

`ping_user`

`send_file`

Fork management tools

`enter_fork`

`save_context`

`report_updates`

`exit_fork`

Reminder tools

`add_reminder`

`list_reminders`

`cancel_reminder`

Chain tool

`follow_up_chain`

Configuration tool

`update_names`

Background fork enforcement

Next steps

Forks

Background forks

Ping budget

System prompt

​Output tools

​discord_embed

​ping_user

​send_file

​Fork management tools

​enter_fork

​save_context

​report_updates

​exit_fork

​Reminder tools

​add_reminder

​list_reminders

​cancel_reminder

​Chain tool

​follow_up_chain

​Configuration tool

​update_names

​Background fork enforcement

​Next steps

Forks

Background forks

Ping budget

System prompt

Output tools

`discord_embed`

`ping_user`

`send_file`

Fork management tools

`enter_fork`

`save_context`

`report_updates`

`exit_fork`

Reminder tools

`add_reminder`

`list_reminders`

`cancel_reminder`

Chain tool

`follow_up_chain`

Configuration tool

`update_names`

Background fork enforcement

Next steps