@mastra/core/dist/docs/references/reference-signals-create-notification-inbox-tool.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# createNotificationInboxTool()

**Added in:** `@mastra/core@1.39.0`

`createNotificationInboxTool()` creates a Mastra tool that lets an agent inspect and manage notification inbox records for the current thread.

Use this tool with durable notification signals. For sending notification records, see [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent).

## Usage example

The following example adds the inbox tool to an agent.

```typescript
import { Agent } from '@mastra/core/agent'
import { createNotificationInboxTool } from '@mastra/core/notifications'

const notificationsStorage = await storage.getStore('notifications')

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support Agent',
  instructions: 'Help the user triage updates.',
  model: 'openai/gpt-5.5',
  tools: {
    notificationInbox: createNotificationInboxTool({ storage: notificationsStorage }),
  },
})
```

## Parameters

**options** (`object`): Tool configuration.

**options.storage** (`NotificationsStorage`): Notification storage domain returned by storage.getStore('notifications').

## Tool input

The generated tool has the id `notification-inbox` and accepts these input fields.

**action** (`'list' | 'read' | 'markSeen' | 'dismiss' | 'archive' | 'search'`): Inbox action to perform.

**threadId** (`string`): Thread ID to inspect. Defaults to the current agent thread when available.

**id** (`string`): Notification ID. Required for markSeen, dismiss, and archive. Optional for read.

**status** (`'pending' | 'delivered' | 'seen' | 'dismissed' | 'archived' | 'discarded'`): Status filter for list, read, or search actions.

**priority** (`'low' | 'medium' | 'high' | 'urgent'`): Priority filter for list, read, or search actions.

**source** (`string`): Source filter for list, read, or search actions.

**query** (`string`): Search query. Required when action is search.

**limit** (`number`): Maximum number of notifications to return. Must be a positive integer.

## Actions

| Action     | Description                                                                             |
| ---------- | --------------------------------------------------------------------------------------- |
| `list`     | Returns matching notifications.                                                         |
| `read`     | Delivers readable notification contents as signals and marks delivered records as seen. |
| `markSeen` | Marks one notification as seen.                                                         |
| `dismiss`  | Marks one notification as dismissed.                                                    |
| `archive`  | Marks one notification as archived.                                                     |
| `search`   | Searches notifications by query and optional filters.                                   |

When `read` finds pending or delivered notifications, the tool delivers their contents as notification signals instead of returning the full contents as normal tool output. Use this after a `<notification-summary>` signal when the agent needs the full records behind the summary.