particle_alert_create

Create an alert that watches a single entity or keyword and emails you on podcast mentions or speaker appearances.

Create an alert that watches a single entity and emails you whenever it is mentioned on a podcast episode (kind=ENTITY_MENTION) or appears as a speaker (kind=PODCAST_SPEAKER). An alert watches exactly one entity — to cover several entities, create one alert per entity. When a name has no entity slug, or its entity has no podcast coverage, create a kind=KEYWORD_MENTION alert that watches a keyword instead (see Keyword alerts). This is a mutating tool — it creates a real alert in your project.

The watch target is passed as an entity slug 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 the 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.

Creating an active alert can move an eligible organization’s subscription from its credit/trial phase to paid fixed-fee billing. Explain this possible billing change and obtain the user’s explicit confirmation before creating an active alert. Creating a paused alert (is_active=false) does not trigger this transition, although the historical backfill still runs.

Alerts are not covered by zero data retention: the alert’s definition and its matched results are stored as part of the alerts feature. See Alerts → Data retention.

The tool advertises destructiveHint: true because of this possible billing transition. This annotation does not add a server-side confirmation check.

Inputs

Field	Type	Required	Default	Description
title	string	yes	—	Human-readable title (e.g. "OpenAI mentions"). Shown in the dashboard and email subject.
entities	array of strings	for entity kinds	—	The entity to watch, as a single slug from the resolve tools. Person, company, and place/other (knowledge-graph) slugs are all accepted. Exactly one — an alert watches a single entity. Omit for KEYWORD_MENTION.
keyword	string	for KEYWORD_MENTION	—	The phrase to watch, up to 100 characters. Only accepted on KEYWORD_MENTION alerts. A phrase that matched more than 700 podcast episodes in the past week is rejected as too broad.
kind	enum	no	ENTITY_MENTION	What 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: by default as guest, panelist, correspondent, or audience, or in an excerpted soundbite (SOUNDBITE_SPEAKER), never as host; speaker_roles replaces that set; KEYWORD_MENTION fires whenever keyword is spoken. Fixed at creation — create a new alert to change it.
delivery_cadence	enum	no	REALTIME	How matches are emailed: REALTIME (one email per match), DAILY (one bundled email each morning), or WEEKLY (one bundled email Monday).
notifications	array of strings	no	your account email	Email 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.
description	string	no	—	Optional longer description of what the alert is for. On a keyword alert, say what the phrase means — the relevance check uses it to drop mentions of an unrelated thing with the same name.
is_active	boolean	no	true	Whether the alert produces matches. Set false to create it paused (the one-time backfill still runs).
filters	object	no	—	Persistent narrowing applied to every surface the alert produces (matches list, realtime email, daily/weekly digest). Omit for no filters — every detected match is surfaced. See Filter object below.

Filter object

filters is an optional object with up to four independent axes. Omit filters (or any individual field) to leave that axis unfiltered. The same shape is accepted on particle_alert_update and is echoed back on every read tool (particle_alert_get, particle_alert_list). See Alerts → Filtering matches for the wire-level spec.

Field	Type	Default	What it does
languages	string[]	all languages	Primary language tags the source episode must be in (e.g. ["en", "pt", "zh"]). A region or script subtag is accepted for readability ("pt-BR", "zh-Hant") but matching is on the primary tag only — "pt-BR" surfaces every Portuguese episode regardless of region, and "pt-BR" + "pt-PT" collapse to one. Case-insensitive; echoed back as the canonical primary tag.
relevance	enum EVERYTHING | RELEVANT	EVERYTHING	EVERYTHING returns both on-target and incidental matches. RELEVANT narrows to on-target only — matches where the watched entity is the subject being discussed, dropping passing mentions.
source_popularity	enum ANY | POPULAR	ANY	ANY keeps every match. POPULAR keeps only matches whose source podcast is in the top 5% by chart-popularity percentile (multi-region weighted; podcasts not currently charting drop out).
speaker_roles	string[] of HOST, GUEST, PANELIST, CORRESPONDENT, AUDIENCE, SOUNDBITE_SPEAKER	[GUEST, PANELIST, CORRESPONDENT, AUDIENCE, SOUNDBITE_SPEAKER]	PODCAST_SPEAKER alerts only. Replaces (not intersects with) the default appearance set. The default excludes HOST because hosting the show isn’t an appearance — set ["HOST"] to flip that, or ["GUEST"] to narrow further. Values are case-insensitive and stored uppercase. Sending this on any other kind returns an unprocessable_entity error.

Keyword alerts

A KEYWORD_MENTION alert watches a phrase rather than an entity, for names the resolve tools don’t know — a startup whose brand differs from its legal name, a product, a drug, a code name. It matches the way a double-quoted keyword_search phrase on particle_podcast_search_transcripts does, not the looser unquoted match: the phrase’s words adjacent and in order, ignoring case and punctuation, on whole words, in topic-discussion and interview segments only (never ad reads, intros, or outros). It watches spoken dialogue, never speaker names.

Because a keyword can collide with an unrelated use of the same word, set description to say what the phrase means. A phrase too broad to alert on — more than 700 matching episodes in the past week, such as a common word or a household name — returns an unprocessable_entity error; watch a well-known person or company with an entity alert instead. Run particle_alert_preview with the same kind and keyword first to see what it would catch.

Agent calls: particle_alert_create {
  "title": "Lightfield mentions",
  "kind": "KEYWORD_MENTION",
  "keyword": "Lightfield",
  "description": "Lightfield, the AI-native CRM (lightfield.app)",
  "delivery_cadence": "DAILY"
}

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 (a **Keyword:** row instead on keyword alerts), and a **Notify:** row with the recipient emails. When the alert has any active filters, a ### Filters section follows with one bullet per configured axis (**Languages:**, **Relevance:**, **Source popularity:**, **Speaker roles:**).

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:** [e-mail]

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"
}

# Narrow with filters — English-language PODCAST_SPEAKER alert that only fires
# on guest spots on top-5% podcasts (a tight booking signal).
Agent calls: particle_alert_create {
  "title": "Sam Altman — guest spots on top podcasts",
  "entities": ["sam-altman"],
  "kind": "PODCAST_SPEAKER",
  "delivery_cadence": "REALTIME",
  "filters": {
    "languages": ["en"],
    "relevance": "RELEVANT",
    "source_popularity": "POPULAR",
    "speaker_roles": ["GUEST"]
  }
}

Related

• REST equivalent: POST /v1/projects/{projectId}/alerts.
• Resolve the watch target first with particle_entity_resolve, particle_person_resolve, or particle_company_resolve.
• Size the alert before creating it with particle_alert_preview.
• After creating, see what it caught with particle_alert_list_matches, or manage it with particle_alert_get, particle_alert_update, and particle_alert_delete.