particle_alert_update

Update an existing alert — retitle, change cadence, pause/resume, or replace its watched entity.

Update an existing alert. This is a mutating tool. Only the fields you pass change; everything you omit is left untouched.

The entities and notifications lists, when provided, replace the whole set — pass the complete new list, not a delta. The watch target is passed as a single entity slug from the resolve tools, exactly as in particle_alert_create; it is re-resolved to its (entity_type, entity_id) internally. An alert watches exactly one entity — alerts created before this rule keep their multi-entity watch list until entities is next written. Use is_active to pause or resume an alert without deleting it.

An alert’s kind is fixed at creation — to watch for a different signal (mention vs. speaker appearance), create a new alert.

Inputs

Field	Type	Required	Default	Description
alert_id	string	yes	—	Alert id to update.
title	string	no	unchanged	New title.
description	string	no	unchanged	New description.
delivery_cadence	enum	no	unchanged	New delivery cadence: REALTIME, DAILY, or WEEKLY.
is_active	boolean	no	unchanged	Pause (false) or resume (true) the alert.
entities	array of strings	no	unchanged	Replacement watch target as a single entity slug (from the resolve tools). When provided, replaces the entire existing watch list — exactly one entity; omit to leave entities unchanged.
notifications	array of strings	no	unchanged	Replacement notification emails. When provided, replaces the entire existing set; omit to leave them unchanged.
filters	object	no	unchanged	Replacement filter set. When provided, replaces the entire existing set — pass {} to clear all four axes back to their defaults; omit to leave filters unchanged. Same four axes as particle_alert_create.filters (languages, relevance, source_popularity, speaker_roles).

Output

A markdown document rendering the updated alert’s full configuration — the same shape returned by particle_alert_create and particle_alert_get: title H2, **ID:**, **Kind:**, **Delivery:**, **Status:**, optional **Description:**, a ### Watching (N) entity list, a **Notify:** row, and (when any filter is set) a ### Filters section with one bullet per configured axis.

Passing output_format: "json" returns the same fields as compact JSON.

Example

# Pause an alert without deleting it.
Agent calls: particle_alert_update { "alert_id": "dKxN6Ry2mL9pJ5qW", "is_active": false }

# Switch to a weekly digest and swap in a new watched entity.
Agent calls: particle_company_resolve { "ticker": "NVDA" }
            → reads "- **Slug:**" row → "nvidia"

Agent calls: particle_alert_update {
  "alert_id": "dKxN6Ry2mL9pJ5qW",
  "delivery_cadence": "WEEKLY",
  "entities": ["nvidia"]
}

# Tighten filters — only RELEVANT matches from the top 5% of podcasts.
Agent calls: particle_alert_update {
  "alert_id": "dKxN6Ry2mL9pJ5qW",
  "filters": { "relevance": "RELEVANT", "source_popularity": "POPULAR" }
}

# Clear all filters back to defaults.
Agent calls: particle_alert_update { "alert_id": "dKxN6Ry2mL9pJ5qW", "filters": {} }

Related

• REST equivalent: PATCH /v1/alerts/{id}.
• Resolve the replacement watch target with particle_entity_resolve, particle_person_resolve, or particle_company_resolve.
• To change an alert’s kind, create a new one with particle_alert_create.
• To remove an alert entirely, use particle_alert_delete.