Skip to main content
Glama
Industrial-AIops Energy

Industrial-AIops Energy

plc_program_xref_config

Read-only

Joins an exported PLC program’s addresses with a configured endpoint’s points using exact address matching, revealing which program symbol corresponds to each line point.

Instructions

[READ][risk=low] Join an exported program's addresses with one endpoint's configured points.

Answers "which program symbol is that point on the line?" by **exact address
match only** — never by name. A configured label that reads like a program
symbol, or a ref one character from a tag, is NOT a match (semantics are given
by a person, never guessed). Comparable pairs: Siemens AWL / .scl × an ``s7``
endpoint (area, DB, byte, bit and width must all agree) and Rockwell L5X × a
Logix ``ethernetip`` endpoint (the tag path is the CIP address). Every other
pair returns ``comparable: false`` with the reason and NO lists — e.g. Modbus
registers are assigned in the device's Modbus map, which no export contains.

Args:
    path: Exported program file (.st/.scl/.awl/.l5x/.txt; must exist, ≤5 MB),
        under $IAIOPS_HOME, the config dir or an IAIOPS_AGENT_READ_DIRS dir.
    endpoint: Configured endpoint name whose ``tags`` are joined.
    live: Also read MATCHED points now. Logix requires a matching live
        controller name. AWL/SCL has no CPU identity, so MCP live reads are
        refused; an operator can attest origin through the CLI. A failed
        read is a gap with no value.

Returns dict: {program:{source_file, format, content_sha256}, endpoint:{name,
    protocol, configured_tag_count}, comparable, address_space,
    unmatchable:{program_format, protocol, reason}|null, refused (why an
    unreadable export was not answered)|null, parse_errors, program.controller
    (L5X: {name, processor_type}),
    matched:[{address, program_symbol, configured_ref, label, role, match
    ('exact_address'|'member_of_tag'), sites_scope (L5X), sites:[{access, block, line,
    source_line}], site_count}]|null, in_export_not_configured|null,
    configured_not_in_export|null, configured_not_comparable, overlaps,
    symbolic_only, indirect_access_sites, counts, notes,
    live:{points:[{configured_ref, status, ...}], read_count, gap_count}
    (only when live=True): a 'read' point has value, read_at, freshness; a 'gap'
    has error and NO value (read_at only when an empty answer arrived)}.

Example: plc_program_xref_config(path="~/.iaiops/plc/OB1.awl", endpoint="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>",
      "endpoint": "<endpoint>"
    },
    "name": "plc_program_xref_config"
  }
}

Input Schema

NameRequiredDescriptionDefault
liveNo
pathYes
endpointYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.13

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only cover the read-only/no-destroy profile, and the description goes well past them: file-size and directory-confinement rules (≤5 MB, under $IAIOPS_HOME or a read dir), why live reads are refused for AWL/SCL without CPU identity, how a failed live read becomes a gap with no value, and what a non-comparable pair returns. That is exactly the extra context the annotations cannot supply.

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 one-sentence purpose and the hard matching rule, then organized under Args/Returns/Example. It is long, and the Returns block is a dense unstructured enumeration that takes up nearly half the text, but with no output schema that detail is load-bearing rather than padding.

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?

For a read-only join tool with no output schema and a hard semantic rule, everything an agent needs is present: comparability matrix, refusal rationale, live-read failure semantics, and a full return-shape listing including the exclusive-in-both-directions lists. The example call reinforces the expected path/endpoint shape.

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 carries the full burden and does — an Args section covers all three params: path's accepted extensions, existence/size/directory constraints; endpoint as the configured endpoint whose tags are joined; live's semantics and protocol-specific requirements. Nothing about the parameters is left undocumented.

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?

States a specific verb+resource ("Join an exported program's addresses with one endpoint's configured points") and pins down the exact semantic rule: "exact address match only — never by name." It also enumerates the only comparable pairs (Siemens AWL/.scl × s7, Rockwell L5X × ethernetip), so an agent can tell instantly whether this tool applies.

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

Usage Guidelines4/5

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

Gives strong when-it-applies guidance via the comparable-pairs list and the explicit fallback that every other pair returns comparable:false with a reason. It also scopes the live=False default and its Logix/AWL caveats. It stops short of naming a sibling (e.g. the name-based plc_program_xref) as the alternative, so the agent must infer that routing itself.

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