particle_alert_create
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). Pass the entity slug from a resolve tool — resolve a name with particle_entity_resolve, then create the alert with the slug it returns. An alert watches exactly one entity; to cover several entities, call this tool once per entity.
Use the optional filters object to narrow what gets surfaced on every channel (matches list, realtime email, daily/weekly digest). Four independent axes: languages (BCP-47-like tags like ['en','pt-BR'] — empty means all languages), relevance (EVERYTHING returns on-target + incidental matches, RELEVANT narrows to on-target only — dropping passing mentions), source_popularity (ANY keeps every source, POPULAR keeps only matches from podcasts in the top 5% by chart popularity), and speaker_roles (PODCAST_SPEAKER alerts only — REPLACES the default appearance set GUEST/PANELIST/CORRESPONDENT/AUDIENCE/SOUNDBITE_SPEAKER; sending it on an ENTITY_MENTION alert errors with unprocessable_entity).
After creation the alert immediately backfills matches from the past week (visible via particle_alert_list_matches) without sending emails for them. To see what an alert would catch BEFORE committing, use particle_alert_preview first. The created alert's id feeds particle_alert_get, particle_alert_update, particle_alert_delete, and particle_alert_list_matches.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | What signal to watch for. ENTITY_MENTION (default) fires whenever a watched entity is mentioned on a podcast episode. PODCAST_SPEAKER fires only when a watched person is themself an identified speaker (guest/panelist/correspondent/audience). Kind is fixed at creation. | |
| title | Yes | Human-readable title for the alert (e.g. 'OpenAI mentions'). | |
| filters | 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 AlertFiltersInput for the four axes (languages, relevance, source_popularity, speaker_roles). | |
| entities | Yes | The entity to watch, as a single slug from the resolve tools (particle_entity_resolve, particle_person_resolve, particle_company_resolve). Person, company, and place/other (knowledge-graph) slugs are all accepted; the resolved type is echoed back in the response. Exactly one — an alert watches a single entity, so create one alert per entity. | |
| is_active | No | Whether the alert produces matches. Defaults to true. Set false to create it paused. | |
| description | No | Optional longer description of what the alert is for. | |
| notifications | No | 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. | |
| output_format | No | Output serialization. 'markdown' (default) returns the LLM-facing rendering. 'json' returns the structured payload as JSON text — use only for programmatic chaining where exact field extraction matters; the JSON shape is larger and noisier for an LLM to read. | |
| delivery_cadence | No | How often matches are emailed: REALTIME (default, one email per match), DAILY (one bundled email each morning), or WEEKLY (one bundled email Monday). |