# MCP tools for lead alerts

List, create, update, and delete lead alert rules, and read the visits they checked, from an AI assistant.

Available on the Pro plan.

These tools manage [lead alerts](https://rightmessage.com/help/lead-alerts) and read their results. Rule changes take effect immediately: there's no draft and nothing to publish. The [lead alerts reference](https://rightmessage.com/help/lead-alerts-reference) explains how visits are checked and what each action does.

## MCP lead alert access

Every tool accepts an optional string `project_id` and follows the [shared MCP authorization and project-selection rules](https://rightmessage.com/help/mcp-authorization-reference). Lead alerts require **Pro**. On a project without them, every tool returns `Lead alerts are part of the Pro plan (People pages), which this project does not have. Upgrade the project to use them.`

Rules and checked visits are addressed by string IDs (`rule_id` and `visit_id`). Results can include email addresses, contact tags and fields, and browsing history. Examples are illustrative and were not executed. They show `tools/call` parameters and decoded response payloads.

## `list-lead-alert-rules`

Read-only. Takes only `project_id`. Returns:

- `live_checking`: whether visits are being checked and actions run in this environment.
- `how_it_works`: a sentence-level summary of when visits are checked and when a rule takes effect.
- `alert_confidence`: the confidence a match needs, such as `0.8`.
- `max_rules`: `10`.
- `rules`: each rule's `rule_id`, `name`, `description`, `enabled`, and `actions`.

```json
{"name":"list-lead-alert-rules","arguments":{"project_id":"123456789"}}
```

Actions use the shapes below. Email platform actions include the `platform` they were set up for.

| `type`  | Fields                                                               |
| ------- | -------------------------------------------------------------------- |
| `email` | `to`: comma-separated addresses, 1 to 20. One email action per rule. |
| `tag`   | `tag_ids`, up to 20, and `platform`.                                 |
| `list`  | `list_ids`, up to 20, and `platform`.                                |
| `field` | `field_id`, `value` (up to 500 characters), and `platform`.          |

Tag, list, and field IDs come from `get-integration-data` in the [integration tools](https://rightmessage.com/help/mcp-tools-integrations). These actions only change a person who is already a contact in the connected email platform; they never create one. An action the platform can't run, or one set up for a different platform, is refused with the reason.

## `create-lead-alert-rule`

| Argument      | Type    | Required | Behavior                                                                        |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------- |
| `project_id`  | string  | No       | Active or eligible project.                                                     |
| `name`        | string  | Yes      | Shown in alerts and email subjects. Up to 120 characters.                       |
| `description` | string  | Yes      | Who to alert on, in plain language. Up to 1,000 characters.                     |
| `enabled`     | boolean | No       | Defaults to `true`.                                                             |
| `actions`     | array   | No       | Up to 10 actions in the shapes above. Without actions, matches are only listed. |

A project can have up to 10 rules. The rule applies to visits checked after it's created. Returns `{rule}`.

```json
{"name":"create-lead-alert-rule","arguments":{"project_id":"123456789","name":"Ready to buy","description":"People who aren't customers yet, looking at pricing or coming back several times in a week.","actions":[{"type":"email","to":"sales@example.com"}]}}
```

## `update-lead-alert-rule`

Requires `rule_id` and at least one of `name`, `description`, `enabled`, or `actions`, with the same limits as create. `enabled: false` pauses the rule without deleting it. `actions` replaces every action the rule has, so start from the rule's current actions; keep each existing email platform action's `platform`, and leave it out for a new one. An empty list leaves matches only listed. New wording applies to visits checked from then on. Returns `{rule}`.

## `delete-lead-alert-rule`

Requires `rule_id`. Deletes the rule immediately; there's no undo. Visits it already checked keep its verdicts. Returns `{"deleted":true,"rule_id":"..."}`.

## `list-lead-alerts`

Read-only. Lists checked visits, newest first.

| Argument              | Type    | Required | Behavior                                                                                    |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `project_id`          | string  | No       | Active or eligible project.                                                                 |
| `include_non_matches` | boolean | No       | Defaults to `false`, which lists alerts only. `true` adds checked visits that didn't alert. |
| `email`               | string  | No       | Only this person's visits.                                                                  |
| `limit`               | integer | No       | `20`; clamped to `1`–`50`.                                                                  |
| `offset`              | integer | No       | `0`. Visits to skip, for paging.                                                            |

```json
{"name":"list-lead-alerts","arguments":{"project_id":"123456789","limit":20}}
```

The response has `live_checking`, `total`, `limit`, `offset`, `has_more`, and `visits`. Each visit has `visit_id`, `email`, `visit_ended_at`, `alert`, `summary`, `pageviews`, `arrived_from`, `test_run`, nullable `emailed_at`, `verdicts`, and `actions`. A verdict has `rule_id`, `rule_name`, `verdict` (`match`, `no_match`, or null), `confidence`, `alerted`, and `repeat_not_resent`. An action result has `rule_id`, `type`, `status` (`done`, `skipped`, or `failed`), and `detail`. `test_run: true` marks a visit found by replaying past traffic; no actions ran for it.

## `get-lead-alert`

Read-only. Requires `visit_id` from `list-lead-alerts`. Returns everything in the list entry plus `visit_started_at`, `facts` (the pages with titles and time on each, arrival, network, earlier activity, segments, and email platform contact the rules were judged on), `insights`, and `insights_error`.

```json
{"name":"get-lead-alert","arguments":{"project_id":"123456789","visit_id":"987654321"}}
```

An unknown ID returns `Checked visit '<id>' not found. Use list-lead-alerts to see visit IDs.`