Skip to main content
Glama
Industrial-AIops Energy

Industrial-AIops Energy

plc_program_drift

Read-only

Compare an exported PLC program against its approved snapshot to report whether bytes or extracted logic blocks changed, naming moved variables, calls, branches, and timers.

Instructions

[READ][risk=low] Has this program changed since its approved snapshot, and what moved?

Three verdicts, and the wording of each is load-bearing. **identical** means
the same SHA-256 and nothing else earns the word. **logic_changed** means the
extracted structure differs — reported per block, naming which categories
(variables / calls / branches / timers_counters) moved. **changed_outside_
extracted_structure** means the bytes differ while every block fingerprint
matched: usually comments or formatting, but these parsers extract structure
rather than parse a grammar, so a real change inside a construct they do not
model looks identical from here. Calling that "documentation only" would be
the comfortable reading of evidence that does not support it, so it is not
called that, and it is not a clearance — line and comment counts are reported
beside it so a reviewer can see which way it leans.

Nothing here decides whether a change was authorised; that is change control's
job. No device is touched — this reads a file a person exported.

Args:
    path: The current exported program file to check (same roots as above).
    name: Tracked program name (defaults to the file's stem).
    against: Snapshot id to compare with; default is the latest.

Returns dict: {program, name_source, baseline:{snapshot_id, taken_at, label,
    source_file}, current:{source_file}, verdict, content_changed,
    structure_changed, content_sha256:{before, after}, blocks:{added[],
    removed[], changed:[{block, kind, line, previous_line, changed[]}],
    unchanged}, totals:{block_count, line_count, comment_count}, parse_errors,
    note, advisory}.

Example: plc_program_drift(path="~/.iaiops/plc/Line3_today.scl", name="Line3").

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": {
      "path": "<path>"
    },
    "name": "plc_program_drift"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNo
pathYes
againstNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.13

TDQS

A4/5.0
Behavior5/5

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

Beyond the annotations (readOnly, openWorld, non-destructive), the description discloses that no device is touched and only an exported file is read, and it carefully qualifies what each verdict does and does not prove — notably that changed_outside_extracted_structure is not a clearance because the parsers extract structure rather than parse a grammar. That is exactly the kind of caveat an agent needs before relaying a result as 'documentation only'.

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

Conciseness3/5

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

The verdict definitions are front-loaded and valuable, but the prose is padded with rhetorical framing ('the wording of each is load-bearing', 'the comfortable reading of evidence that does not support it') that costs tokens without adding callable information. The Args/Returns/Example structure is good; the surrounding philosophy could be cut by a third.

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?

There is no output schema, yet the description spells out the full return dict — baseline/current metadata, three boolean/verdict fields, per-block added/removed/changed detail, totals, parse_errors, note and advisory. Combined with the parameter docs and a concrete example, an agent has everything needed to call and interpret this tool.

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 0% (titles only), so the description carries the burden and mostly does: path is the current exported file, name defaults to the file stem, against is a snapshot id defaulting to the latest. The path entry leans on a dangling reference ('same roots as above') that supplies no actual root information in this standalone definition, which keeps it from a 5.

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

Purpose4/5

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

It opens with a precise question — has the program changed since its approved snapshot, and what moved — and enumerates the three verdicts it returns, so the verb and resource are unambiguous. It does not explicitly contrast itself with close siblings such as plc_program_snapshot or plc_program_history, so the agent must infer the routing from the verdict semantics rather than being told.

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

Usage Guidelines3/5

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

Usage is implied by the framing ('Has this program changed since its approved snapshot') and reinforced by the worked example and by the scope exclusion that authorisation decisions belong to change control. However, there is no explicit statement of when to prefer this over plc_program_snapshot or plc_program_history, nor any prerequisite (e.g. that a snapshot must already exist) stated up front.

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