Watch, inbox and reminder MCP tools

Eleven nima MCP tools cover two separate features. Watches tell a person when something happens to a signal, beacon, spec, pull request or tracker ticket, and the inbox lists what nima told them. Reminders save a one-time message to your own Slack DM at a time you choose. Every tool acts on the caller's own rows only. For the ideas behind both features, read Watches and reminders. For connecting a client, read the MCP server overview.

Watch, inbox and reminder tools at a glance

All three scopes are on the OAuth consent screen, so a default connection holds them. A tool answers 403 if the token lacks the scope. The same operations are available over HTTP: see Watches and Scheduled messages. The event history tool get_history needs signals:read and is documented in Pipeline MCP tools.

list_event_types tool

list_event_types returns the fixed catalog of events a watch can react to: 16 event types, each with its subject kind, a one-line description, whether it is material and a JSON Schema for its payload. Read it before creating a watch, because triggerTypes and payloadEquals are validated against it.

The tool takes no input. The response is { subjectKinds, eventTypes }, and each entry of eventTypes carries type, subjectKind, description, material and payloadSchema. Subject kinds are signal, beacon, spec, pr and ticket. A material event can interrupt a person who was already told about the subject; pr.drift_checked does so only when the verdict is drifted on an open pull request. Non-material events about a subject you were already told about fold into the 09:00 digest (09:00 in your own timezone).

create_subscription tool

create_subscription saves a watch: when a listed event happens to one signal, beacon, spec or pull request, or to an item downstream of it, nima runs your saved instructions with fresh context and sends the answer to your inbox and Slack.

The input is strict: unknown fields are rejected. The tool returns the watch with id, name, handler, payloadEquals, subjectKind, subjectId, triggerTypes, templateKey, createdVia, state, pausedReason, expiresAt, lastFiredAt, fireCount and createdAt.

A watch reacts to future changes only. Events that happened before the watch existed never fire it. A watch on a signal also hears events on the beacon, spec and pull request that signal flowed into. Conditions are exact equality only: there are no ranges, or, not, timers or topic subscriptions. A watch pins one existing subject.

Repeating an identical active request returns the existing watch instead of creating a second one, so the tool is idempotent.

Create a workspace rule with create_subscription

create_subscription with scope: "org" creates a workspace rule over every tracker ticket event instead of a watch on one subject. It needs an owner or admin (the integrations-management permission), watches on for the workspace and outbound dispatch on for the workspace. No MCP token or API key can create one today. The route needs subscriptions:write and a workspace rule also needs integrations:write, and no token holds both: a default OAuth connection and a key from Settings lack integrations:write, and the Slack /nima mcp-key integrations key holds only integrations:write. Create workspace rules with POST /v1/watches from a signed-in owner or admin session, or ask the nima team. The fields below describe that request.

An org rule takes no subjectKind or subjectId. triggerTypes may only be ticket.opened, ticket.assigned and ticket.comment_added. Send one handler:

• { "kind": "notify", "to": { "role": "assignee" }, "fallback": "owner" } with templateKey: "tracker_assignee_reminder". role is owner, assignee, reporter or spec_owner. fallback is owner or none and defaults to none. templateKey is required for a notify rule. fallback can also go inside to.
• { "kind": "agent", "instructions": "...", "tools": ["reply_on_ticket"], "maxActions": 1 }. instructions is 1 to 4000 characters, context is optional (1 to 8000), and maxActions can only be 1. An agent rule takes no templateKey. A proposed reply waits for approval unless an owner or admin has set ticket replies to auto for an internal project and the asker is a verified workspace member. See Outbound actions.

mention on a notify handler is rejected ("mention is not supported yet"). Sending handler or templateKey without scope: "org" answers 400.

update_subscription tool

update_subscription changes one of your own conversational watches: its events, conditions, instructions, context or expiry, or resumes it. The subject cannot change, so create a new watch for a different subject.

Only watches whose handler is an AI response can be edited. Automatic notification watches (created by a bell reaction, by promoting a beacon, or for the spec owner when a spec is written) and workspace rules answer 400 "Only conversational subscriptions can be edited". A resumed watch does not fire on events from its paused period.

list_watches tool

list_watches returns your own watches, at most 200, with active ones first, then paused and expired ones, newest first within each group. It includes conversational watches, automatic notification watches and any workspace rules you created.

The tool takes no input and has no pagination. There is no call that lists another person's watches: their ids answer 404. Each row has the same fields as the create_subscription response, including state (active, paused or expired), pausedReason, createdVia and fireCount.

unwatch tool

unwatch pauses one of your own watches by id and returns it as it now stands. Nothing is deleted, so past notifications stay explainable.

The call returns HTTP 200 with the watch and state: "paused". Pausing an already paused or expired watch changes nothing. It also stops that watch's pending items in the 09:00 digest. Resume it with update_subscription and state: "active". Another person's id answers 404.

get_inbox tool

get_inbox returns your own nima inbox, newest first: everything nima has told you about what you watch, one item per notification.

The response is a page (data and meta, see Pagination). Each item has id, kind, state, ruleId, subjectKind, subjectId, title, body, links, channel, deliveredAt, digestedAt and createdAt. channel says how the item reached you:

get_scheduling_context tool

get_scheduling_context returns the current time, a suggested timezone and whether your Slack account is linked. Call it before schedule_message.

The tool takes no input and returns now (ISO 8601 UTC), suggestedTimeZone, slackConnected and guidance. The suggestion is your Slack profile timezone, or UTC when that cannot be read. It is only a suggestion, so confirm the timezone with the person before scheduling.

schedule_message tool

schedule_message saves a one-time message to your own linked Slack DM at an exact future time. nima stores the text now and sends it as written. It does not research or run anything later.

The input is strict. The tool returns a reminder with id, message, sendAt, localDeliveryTime, timeZone, state, version, delivery (slack_dm), sentAt, failureReason and createdAt. Delivery is accurate to about one minute.

Retrying with the same requestKey returns the original reminder, even after its due time. Reusing a key with a different message, time or timezone answers 409.

A reminder goes only to your own Slack DM, never to a channel or another person. Reminder states are pending, delivering, sent, cancelled, failed and uncertain. uncertain means Slack did not confirm delivery. nima never resends an uncertain reminder, so check Slack before sending it again.

list_scheduled_messages tool

list_scheduled_messages returns your own reminders and their delivery status: up to 200, with pending reminders first by delivery time, then recent history.

The tool takes no input. Each row includes the id and version you need to edit or cancel it. Do not report an uncertain reminder as sent.

update_scheduled_message tool

update_scheduled_message edits or reschedules one of your pending reminders. Read its id and version from list_scheduled_messages first.

Only a pending reminder can change. If delivery has started or the version is stale, the call answers 409 "The reminder changed or delivery has started. List reminders again before editing." A missing id answers 404. The tool is not idempotent: each successful call bumps version, so re-read the list before retrying. Editing also answers 409 while scheduled messages are switched off platform-wide, and the send time is checked again even when only message changes.

cancel_scheduled_message tool

cancel_scheduled_message cancels one of your pending reminders and returns it with state: "cancelled".

Cancelling an already cancelled reminder changes nothing. If delivery has started, the call answers 409. A missing id answers 404.

Availability of watch tools

Watch tools work only in a workspace where watches are switched on. Creating or editing a watch in any other workspace answers 409 "Subscriptions are not enabled for this workspace". The tools still appear in tools/list, and reading tools (list_event_types, list_watches, get_inbox) still answer. Events are recorded while watches are off, but nothing fires or is sent until an owner or admin sets triggersEnabled to true with PATCH /organizations/settings from a signed-in session, or the nima team does it for you. Turning it off again stops existing watches without an error.

Workspace rules also need outbound dispatch on for the workspace, and they can only be created from a signed-in owner or admin session with POST /v1/watches, not over MCP. See Availability of features.

Reminder tools do not depend on that setting. They need the caller's Slack account linked in the workspace and a token with the subscriptions:* scopes. Owners, admins and members can all use them.