Skip to main content
Glama

particle-pro

by pro.particle
OverviewDiscussionsAdmin

Particle Alert Preview

particle_alert_preview

Preview how often an alert would fire BEFORE creating it. Sweeps the past N days (default 7, max 30) for the given entity (or keyword, for kind=KEYWORD_MENTION) and returns the total match count, a per-day breakdown, and a small sample of the most recent matches with episode context. Use this to size an alert (REALTIME vs DAILY vs WEEKLY cadence) or to confirm the entity slug watches the right thing, then call particle_alert_create with the same entity slug (for KEYWORD_MENTION, the same keyword instead). Pass the same filters you plan to save so the estimate matches what the alert would surface — the languages and speaker_roles axes narrow the sweep; relevance and source_popularity are read-time projections that don't, so the count is an upper bound when relevance=RELEVANT. Starts a background sweep and caches its progress and results; it does not create an alert or send notifications.

Input Schema

NameRequiredDescriptionDefault
kindNoSignal to preview. Defaults to ENTITY_MENTION.
filtersNoSame as particle_alert_create.filters. Pass the filters you intend to save so the estimate reflects what the alert would actually surface. languages, speaker_roles, source_popularity and speaker_statement_characteristics narrow the historical sweep exactly as they narrow new matches; relevance is graded only on new matches, so setting it leaves the count unchanged (the estimate is an upper bound when relevance=RELEVANT).
keywordNoSame as particle_alert_create.keyword — required for KEYWORD_MENTION. A phrase that matched more than 700 podcast episodes in the past week is rejected as too broad, as on create.
entitiesNoThe entity to preview, as a single slug (from the resolve tools), same as particle_alert_create.entities — exactly one for entity kinds, omitted for KEYWORD_MENTION.
window_daysNoHow many days back to sweep (1-30, default 7).
output_formatNoOutput 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / filters / description
      Previous value: -"Same as particle_alert_create.filters. Pass the filters you intend to save so the estimate reflects what the alert would actually surface. Only languages and speaker_roles narrow the historical sweep; relevance and source_popularity are read-time projections that don't run on historical episodes, so setting them leaves the count unchanged (the estimate is an upper bound when relevance=RELEVANT)."New value: +"Same as particle_alert_create.filters. Pass the filters you intend to save so the estimate reflects what the alert would actually surface. languages, speaker_roles, source_popularity and speaker_statement_characteristics narrow the historical sweep exactly as they narrow new matches; relevance is graded only on new matches, so setting it leaves the count unchanged (the estimate is an upper bound when relevance=RELEVANT)."
    • addedInput schema / properties / filters / properties / speaker_statement_characteristics
      Added value: +{
+  "description": "ENTITY_MENTION alerts only — sending it on a PODCAST_SPEAKER or KEYWORD_MENTION alert returns unprocessable_entity. Keeps a match only when one of its mention lines was said the way you ask, the same filter particle_podcast_find_mentions takes: {'sentiment': ['negative']} for criticism of the watched entity, {'specificity': ['specific'], 'temporal_orientation': ['future']} for concrete predictions about it, {'certainty': ['confident']} for confident claims. Labels on one axis OR together, axes AND. Mention lines the filter does not accept are not marked as mentions and do not count. Put how something is said here, never in the alert's title or keyword.",
+  "properties": {
+    "certainty": {
+      "description": "How sure the speaker sounds. 'confident' for flat assertions and high conviction; 'hedged' for maybe, I think, it could, and other hedging; 'neutral' for neither.",
+      "items": {
+        "enum": [
+          "hedged",
+          "neutral",
+          "confident"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "sentiment": {
+      "description": "The statement's tone. 'positive' for optimistic, bullish, approving or praising lines; 'negative' for skeptical, bearish, critical or worried ones; 'neutral' for lines that clearly lean neither way.",
+      "items": {
+        "enum": [
+          "negative",
+          "neutral",
+          "positive"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "specificity": {
+      "description": "Whether the line commits to something concrete. 'specific' for names, numbers, dates and mechanisms (concrete claims); 'vague' for generalities; 'neutral' for neither.",
+      "items": {
+        "enum": [
+          "vague",
+          "neutral",
+          "specific"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "temporal_orientation": {
+      "description": "Where the line points in time. 'future' for predictions, forecasts, plans and expectations; 'past' for looking back; 'present' for how things are now.",
+      "items": {
+        "enum": [
+          "past",
+          "present",
+          "future"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / keyword / description
      Previous value: -"Same as particle_alert_create.keyword — required for KEYWORD_MENTION. A phrase that matched more than 7,000 podcast episodes in the past week is rejected as too broad, as on create."New value: +"Same as particle_alert_create.keyword — required for KEYWORD_MENTION. A phrase that matched more than 700 podcast episodes in the past week is rejected as too broad, as on create."
  3. Changed4 schema fields changed
    • changedInput schema / properties / entities / description
      Previous value: -"The entity to preview, as a single slug (from the resolve tools), same as particle_alert_create.entities — exactly one."New value: +"The entity to preview, as a single slug (from the resolve tools), same as particle_alert_create.entities — exactly one for entity kinds, omitted for KEYWORD_MENTION."
    • addedInput schema / properties / keyword
      Added value: +{
+  "description": "Same as particle_alert_create.keyword — required for KEYWORD_MENTION. A phrase that matched more than 7,000 podcast episodes in the past week is rejected as too broad, as on create.",
+  "maxLength": 100,
+  "type": "string"
+}
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "ENTITY_MENTION",
-  "PODCAST_SPEAKER"
-]New value: +[
+  "ENTITY_MENTION",
+  "PODCAST_SPEAKER",
+  "KEYWORD_MENTION"
+]
    • removedInput schema / required
      Removed value: -[
-  "entities"
-]
  4. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds meaningful behavior beyond the annotations: it is asynchronous ('Starts a background sweep and caches its progress and results'), it does not create an alert or notify anyone, and relevance=RELEVANT makes the count an upper bound. That last point is genuinely load-bearing for interpreting the number returned. It stops short of covering cost/latency or what happens on repeated calls, so it is not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the create-follow-up in the first three sentences, with per-parameter caveats after. It is on the long side and restates some schema content (the narrowing-versus-projection detail appears both here and in the filters schema), so a little trimming is possible without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so: total match count, per-day breakdown, and a sample of recent matches with episode context. Combined with the async/caching disclosure and the create-then-verify workflow, an agent has enough to call it and interpret the result correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a non-obvious semantic distinction the schema only partially states: languages and speaker_roles narrow the sweep while relevance and source_popularity are read-time projections that do not, making the count an upper bound under relevance=RELEVANT. It also flags the window default/max in prose, though much of the per-parameter guidance duplicates the already detailed schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb-plus-resource and an explicit temporal qualifier: 'Preview how often an alert would fire BEFORE creating it.' It then enumerates exactly what the sweep returns (total count, per-day breakdown, recent-match sample with episode context), which an agent cannot confuse with particle_alert_create or particle_alert_get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the two concrete use cases ('size an alert (REALTIME vs DAILY vs WEEKLY cadence)' or 'confirm the entity slug watches the right thing') and names the follow-up sibling: 'then call particle_alert_create with the same entity slug'. It also instructs passing the same filters so the estimate matches the saved alert, and explicitly scopes the tool out of creating alerts or sending notifications.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All particle-pro toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources