Skip to main content
Create an alert that watches one or more entities and emails you whenever they are mentioned on a podcast episode (kind=ENTITY_MENTION) or appear as a speaker (kind=PODCAST_SPEAKER). This is a mutating tool — it creates a real alert in your project. Watch targets are passed as entity slugs from a resolve tool — the same slug→edge contract as the rest of the surface. Resolve a name once with particle_entity_resolve, particle_person_resolve, or particle_company_resolve, then create the alert with the slug it returns. The tool resolves each slug to its (entity_type, entity_id) internally, so you never handle a raw entity id; the resolved type and name are echoed back in the response. Every MCP request is scoped to exactly one project by your credential, so the alert is created in that project — there is no project parameter. After creation the alert immediately backfills matches from the past 7 days (visible via particle_alert_list_matches, flagged is_backfilled and never emailed). To see what an alert would catch before committing, run particle_alert_preview first.
Alerts require a plan that includes them (Team, Business, or Enterprise) and an available alert allowance. On a plan without alerts or at the allowance limit, the call returns an isError result with upgrade guidance.

​
Inputs

FieldTypeRequiredDefaultDescription
titlestringyes—Human-readable title (e.g. "OpenAI mentions"). Shown in the dashboard and email subject.
entitiesarray of stringsyes—Entity slugs to watch, from the resolve tools. Person, company, and place/other (knowledge-graph) slugs are all accepted. At least one is required.
kindenumnoENTITY_MENTIONWhat to watch for. ENTITY_MENTION fires whenever a watched entity is mentioned on an episode; PODCAST_SPEAKER fires only when a watched person is themself an identified speaker (guest/panelist/correspondent/audience). Fixed at creation — create a new alert to change it.
delivery_cadenceenumnoREALTIMEHow matches are emailed: REALTIME (one email per match), DAILY (one bundled email each morning), or WEEKLY (one bundled email Monday).
notificationsarray of stringsnoyour account emailEmail addresses to notify. Each must already be verified for your organization (or belong to an org member). When omitted, defaults to your account email if available; otherwise pass at least one.
descriptionstringno—Optional longer description of what the alert is for.
is_activebooleannotrueWhether the alert produces matches. Set false to create it paused (the one-time backfill still runs).

​
Output

A markdown document rendering the created alert’s full configuration: the title as an H2, then **ID:**, **Kind:**, **Delivery:**, and **Status:** (active/paused) KV rows, an optional **Description:** row, a ### Watching (N) section listing each resolved entity as Name — type · id, and a **Notify:** row with the recipient emails. The **ID:** row is the alert id — feed it into particle_alert_get, particle_alert_update, particle_alert_delete, and particle_alert_list_matches. Sample (title="OpenAI mentions", entities=["sam-altman"], delivery_cadence="DAILY"): 
## OpenAI mentions

**ID:** dKxN6Ry2mL9pJ5qW
**Kind:** ENTITY_MENTION
**Delivery:** DAILY
**Status:** active

### Watching (1)

- **Sam Altman:** PERSON · 9rQ2pV…

- **Notify:** you@example.com
Passing output_format: "json" returns the same fields as compact JSON.

​
Example

User: Email me whenever Sam Altman is mentioned on a podcast.

Agent calls: particle_person_resolve { "query": "Sam Altman" }
            → reads "- **Slug:**" row → "sam-altman"

Agent calls: particle_alert_create {
  "title": "Sam Altman mentions",
  "entities": ["sam-altman"],
  "kind": "ENTITY_MENTION",
  "delivery_cadence": "DAILY"
}