Skip to main content
Glama
Industrial-AIops Energy

Industrial-AIops Energy

alarm_event_clusters

Read-only

Group alarm events by normalized message text to merge duplicate fault phrasings across sources into clusters, making recurring conditions visible for rationalization.

Instructions

[READ][risk=low] Collapse ten phrasings of one fault into one row.

`alarm_bad_actors` ranks by SOURCE, which answers "which instrument is
noisiest" and not "which fault is noisiest". A plant that words one condition
ten ways — `PT-101 HIGH`, `PT-102 HIGH`, `PT-103 high alarm` — gets ten bad
actors and no sign that they are one problem, so a rationalization meeting
works the list top-down and fixes the same thing three times. This groups the
same events by what they SAY instead of by who said it.

Clustering is **exact equality of a normalized string, not similarity**: case,
punctuation and embedded numbers are removed, and what remains must match
exactly. That is deliberately dumber than it could be, and it is why the
result needs no model and can be checked — two messages land together only
when they are literally the same sentence with the identifiers taken out.
Every cluster carries the distinct wordings and sources it merged, so you can
see what was combined. It does **not** claim two differently-worded alarms
mean the same thing; a person decides that.

Events carrying no message text are counted separately and excluded from the
shares, rather than being lumped together as one type.

Args:
    events: [{source?, message|description|text|condition|type, ...}].
    top_n: Clusters returned, largest first (default 20, capped at 100).
    min_count: Only report clusters with at least this many events (default 1 —
        a one-off is still reported, not tidied away).

Returns dict: {events_supplied, events_clustered, events_without_text,
    cluster_count, collapsed_count, clusters:[{signature, count, share_pct,
    distinct_wordings, distinct_sources, variants:[{text, count}],
    sources:[{source, count}]}], note}.

Example: alarm_event_clusters(events=[{"source":"PT-101","message":"pressure HIGH"},
    {"source":"PT-102","message":"Pressure high!"}]).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "events": "<events>"
    },
    "name": "alarm_event_clusters"
  }
}

Input Schema

NameRequiredDescriptionDefault
top_nNo
eventsYes
min_countNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.13

TDQS

A5/5.0
Behavior5/5

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

Annotations already mark the operation read-only and non-destructive, but the description adds substantial behavioral detail: exact equality after normalization of case, punctuation, and embedded numbers; events without message text are excluded from shares; and each cluster retains distinct wordings and sources. It also explicitly states what the tool does NOT claim, preventing over-interpretation of cluster meanings.

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

Conciseness5/5

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

The description is long but every sentence earns its place: it opens with a one-line summary and risk marker, explains motivation and algorithm, details all three parameters, and lists the return structure. The contrast with alarm_bad_actors is front-loaded, and the example grounds the explanation without bloat.

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?

Given there is no output schema, the description compensates by fully specifying the return dict fields, including clusters, signatures, counts, shares, distinct wordings, and sources. It also addresses edge cases like events without text and one-off clusters. Combined with the sibling context and annotations, an agent has everything needed to select and invoke this tool correctly.

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

Parameters5/5

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

Schema description coverage is 0%, so the description fully carries the burden. It explains the events parameter with accepted message field aliases, top_n with default and cap, and min_count with default and behavior. It even provides a concrete example call showing expected parameter shapes.

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 first line states a specific action and resource: 'Collapse ten phrasings of one fault into one row.' The description then explicitly contrasts this with alarm_bad_actors, clarifying that this tool answers 'which fault is noisiest' rather than 'which instrument is noisiest.' This clearly differentiates it from the closest sibling.

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 concrete when-to-use context: when multiple wordings of the same underlying fault inflate a bad-actor list. It names the alternative alarm_bad_actors and explains the distinction in terms of SOURCE versus message content. It also cautions that clustering is exact-equality based, not semantic similarity, so a human must decide whether different wordings mean the same thing.

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

Deploy Server

Other Tools