Skip to main content
Glama

particle-pro

by pro.particle
OverviewDiscussionsAdmin

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

TableJSON 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. 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).
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. 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."
  2. 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"
-]
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations (readOnlyHint=false, destructiveHint=false) are minimal and all-negative, so the description carries the behavioral burden and discharges it exceptionally. It discloses the background sweep and caching side effect (which explains why readOnlyHint=false), the non-destructive guarantee, the upper-bound caveat when relevance=RELEVANT, and which filter axes actually narrow the historical sweep vs which are read-time projections. No contradiction with annotations; the side-effect disclosure actually reconciles the readOnlyHint=false flag.

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?

The description is dense (~120 words) but logically ordered: purpose → mechanism → usage workflow → filter semantics → side-effect caveats. Every sentence carries distinct information and the purpose is front-loaded. Slight deduction for redundancy, since the filter projection/upper-bound caveat is restated in the schema's filters.description, making the overall definition longer than strictly necessary.

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

Completeness4/5

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

For a complex 6-parameter tool with sparse annotations and no output schema, the description covers the essentials well: return content (count, breakdown, sample), non-destructive behavior, filter semantics, and the create-workflow link. The main gap is the sync/async ambiguity — it says 'starts a background sweep and caches its progress and results' without clarifying whether the call blocks for the sweep or returns immediately with progress, nor how to retrieve the cached results afterward. A minor gap given the otherwise thorough coverage.

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% with rich per-parameter descriptions, so the baseline is 3. The tool description adds genuine cross-parameter orchestration value: it ties entities/keyword to the derive-from-create workflow, and clarifies which filters (languages, speaker_roles) narrow the sweep vs which (relevance, source_popularity) are projections that leave the count unchanged. It stops short of 5 because individual parameter semantics are already exhaustively documented in the 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?

The opening sentence 'Preview how often an alert would fire BEFORE creating it' grounds the tool with a specific verb and resource, and the description further specifies the mechanism (sweep past N days), return values (match count, per-day breakdown, sample), and explicit exclusions ('does not create an alert or send notifications'). It clearly differentiates from siblings: it is not particle_alert_create (no creation), not particle_alert_get/list (no existing-alert read), and not particle_alert_list_matches (no live-match listing).

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?

The description gives explicit when-to-use guidance: 'Use this to size an alert (REALTIME vs DAILY vs WEEKLY cadence) or to confirm the entity slug watches the right thing.' It also names the exact continuation workflow — 'then call particle_alert_create with the same entity slug' — and instructs the caller to reuse planned filters. This is turnkey routing to the correct sibling.

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