This server provides read-only analysis tools for GX Works3 PLC projects, enabling engineers and AI agents to inspect project structure and logic without modifying source files. Key capabilities include:
List allowed commands (gx3_list_commands): Show all available read-only GX3 CLI commands.
Trace device logic (gx3_trace_device): Trace a device's ON/OFF/hold conditions from ladder topology, including master-control zones and warnings for multi-coil or conditional jump issues.
Interlock check (gx3_interlock_check): Statically determine if two coils' enable conditions can be simultaneously true, returning a witness assignment or mutual exclusion.
Cross-reference lookup (gx3_xref_where_used): Find writers and readers of a device with POU name and step number (requires pre-built xref database).
Static linting (gx3_lint): Run checks for duplicate coils, multi-writers, alarm quality, unused devices, comment issues, and math/type errors, outputting CSV reports.
Dead logic detection (gx3_dead_logic): Identify constant-OFF contacts, always-on NC contacts, unread coils/words, and SET-without-RST latches (requires xref database).
Device map (gx3_device_map): Show device usage ranges, density, and free gaps from the SQLite index.
Alarm map (gx3_alarm_map): Inventory alarms/faults with trigger, hold type, timer setpoint, and reset condition (requires xref database).
Semantic diff (gx3_semantic_diff): Perform rung-level comparison between two projects using stable block GUIDs.
Network map (gx3_network_map): Aggregate IP, CC-Link, SCON, and safety relationships.
Ladder print (gx3_ladder_print): Render programs in GX Works3 print-text layout, with filtering by section, device, or position range.
Run arbitrary command (gx3_run_command): Execute any MCP-allowed, read-only CLI command, rejecting mutating or demo-generation commands.
All tools operate locally and never modify the project, making them safe for AI-driven analysis.
Provides read-only analysis tools for Mitsubishi Electric GX Works3 (.gx3) PLC projects, enabling inspection of project structure, device usage, cross references, ladder conditions, communication boundaries, and static quality signals.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gx3-mcp-server trace device M100 in the demo project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Work out why a coil never turns on, without opening GX Works3.
Reads a GX Works3 .gx3 project on your own machine and answers questions
about it — where a device is written, what has to be true for a coil to turn
on, which conditions come from outside the PLC, which branches can never be
true. Read-only: it never writes back to the project.
It is a CLI, and the same analysis is a stdio MCP server, so an AI agent can answer from indexed facts instead of guessing at a binary file.
日本語: 三菱電機 MELSEC の .gx3 を GX Works3 を開かずに解析する CLI / MCP
サーバーです。「このコイルがなぜ ON にならないか」をラダーから追います。
読み取り専用で、元のプロジェクトは書き換えません。
pip install gx3-cli-mcpPython 3.10+. Installs two console scripts: gx3-cli and gx3-mcp-server.
Related MCP server: x402-industrial-mcp
No project needed — generate one:
gx3-cli synthetic-project demo.gx3 --profile demo-line
gx3-cli guide --root demo.gx3guide reads the project and tells you which commands are worth running on it,
and why. That is the answer to "there are sixty commands, where do I start".
gx3-cli doctor --root project.gx3 # does it read?
gx3-cli index-lite build --root project.gx3
gx3-cli xref build --root project.gx3
gx3-cli guide --root project.gx3 # what to run nextThen ask it something:
# where is this device written, and what reads it?
gx3-cli xref where-used M100 --root project.gx3
# why is this coil not turning on?
gx3-cli trace-device M100 --root project.gx3 --strict-logic --compact
# the whole program, one line per rung
gx3-cli rung-text --root project.gx3
# search the comment you remember, not the device number you don't
gx3-cli query-comment "clamp pressure" --root project.gx3Every command takes --format json for scripting, and -o FILE to write
instead of print. gx3-cli --help lists all of them by group.
Passing a .gx3 extracts it to .gx3_cache/<sha256>/ and analyses that copy.
Question | Command |
Why is this coil off? |
|
Where is this device written or read? |
|
What does this program do? |
|
Show me the rung as a picture |
|
What comes from outside the PLC? |
|
What can never be true? |
|
What looks wrong? |
|
What changed between versions? |
|
Did it read the project correctly? |
|
{
"mcpServers": {
"gx3": { "command": "gx3-mcp-server" }
}
}Or "command": "python", "args": ["-m", "gx3cli.gx3_mcp_server"] if your
client cannot resolve console scripts from PATH. The server exposes read-only
analysis tools and a restricted command runner.
See Agent usage guide (JA) for how an agent should drive it.
Read-only analysis of .gx3 on your machine. Ladder is what it reads well.
FBD, ST, SFC and MIL are detected and reported as such rather than guessed at,
so a program it cannot read comes back saying so instead of coming back empty.
It does not edit projects, connect to a PLC to change anything, or replace GX
Works3. live-read can read live device values over MC Protocol/SLMP, CLI-only
and only with explicit connection parameters.
Output is advisory. Verify in GX Works3 and through your own safety process before touching real equipment. See Validation matrix (JA) for what has been checked.
If a project fails to parse, gx3-cli failure-corpus capture turns it into a
local regression sample without sending anything anywhere.
7z-style .gx3 — install 7-Zip, or point at it:
set GX3_7Z=C:\Program Files\7-Zip\7z.exe. Encrypted containers are not
decrypted; export the folder from GX Works3 instead.
PyPI blocked — pip install git+https://github.com/purinzan/gx3-cli-mcp.git
Something reads wrong — gx3-cli doctor --root ... first, then
open an issue.
Ladder practical tips (JA) — field-oriented modification and review tips
Security note (JA) — local data handling, read-only MCP policy
Validation matrix (JA) — verified scope and limits
GX Works3 feature matrix (JA) — standard-feature coverage, gaps, and implementation priorities
File usage guide (JA) — repository map
Analysis benchmark (JA) — synthetic performance baseline and measurement limits
Review questions (JA) — the questions to ask a change before opening a pull request, and the bugs each of them found
Related projects (JA) — other GX Works3/MELSEC tools and what was taken from them
llms.txt — machine-readable summary of what this is and is not
Agent skills: existing project audit · failure corpus
Current query-by-query status and remaining acceptance work for #153: 解析契約の移行台帳.
Source-available, not open source. Full terms in LICENSE.txt; this is a summary and the license text governs.
You may read the source and run it for evaluation and internal work, including inside a company. You may not redistribute it, host it as a service, or ship it in a paid product without written permission. There is no licence key, activation or paid plan.
日本語: 社内での評価・業務利用は許諾されています。禁止しているのは再配布、 SaaS 提供、有償製品への組み込みです。実行にライセンスキーや課金は不要です。 商用利用の相談は Issue からどうぞ。
Indexed as an MCP server, with per-tool scores for how well each tool describes what it does. Useful as outside feedback on the tool surface — the low scores there are the ones whose descriptions need work.
Contributing: CONTRIBUTING.md · AGENTS.md
Inventory every alarm and fault device with what triggers it, whether it latches, any timer setpoint, and what resets it. Answers "what raises this alarm and how is it cleared" without reading the ladder by hand. Reads the project; WRITES a CSV. Interpret clearing from the hold type: a plain OUT clears when its enable logic goes false; SET-latched alarms require a reset path, and self-hold circuits require their seal-in path to drop or reset logic to act. Do not infer a power-cycle requirement merely from an empty RST list. Requires the xref DB.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | list | |
| root | Yes | Extracted project folder. | |
| device | No | Device to show (required when mode=show). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and handles it well. It discloses the side effect ('Reads the project; WRITES a CSV'), the interpretation rules for clearing based on hold type, and warns against inferring power-cycle requirements from an empty RST list. These are exactly the behavioral nuances an agent needs beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and output, then provides necessary interpretive guidance. Every sentence adds value, though the clearing-interpretation second half is dense and slightly long. It earns a strong score, but the structure could be tightened without losing necessary nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, output format, side effect, interpretive rules, and a prerequisite, which is substantial for a tool with no output schema and no annotations. The main gap is that 'mode=list' versus 'mode=show' semantics are not described, leaving the agent to infer how to use the third parameter correctly. Otherwise, the tool is well specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with root and device already described in the schema. The description adds no parameter-specific meaning; notably, the 'mode' enum (list/show) is not explained beyond its values, and the description never clarifies how mode interacts with the inventory versus show behavior. It neither heavily compensates nor significantly neglects, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Inventory every alarm and fault device' with the exact attributes captured (trigger, latch, timer setpoint, reset). It also states the core question it answers ('what raises this alarm and how is it cleared') and notes the CSV output, making it clearly distinct from sibling ladder-printing or tracing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when the tool is valuable: answering alarm trigger/reset questions without manual ladder reading. It also states the xref DB prerequisite. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks the exclusionary guidance needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build conservative argument-level source-to-destination value-flow edges. Known transfer and other classified instructions produce edges with argument indexes, ranges, widths, execution condition, and confidence. Unknown or partially parsed operations are returned as unresolved records; no guessed edge is emitted. Device comments are included when available.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| device | No | Only edges touching this device. | |
| format | No | json | |
| opcode | No | Only this exact instruction opcode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does well: it discloses that the analysis is conservative, that no guessed edges are emitted, that unresolved operations become unresolved records, and that device comments are included when available. This adds substantive behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences with no filler. The main purpose is front-loaded, followed by edge attributes, then behavior for unknown operations and device comments. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description does a solid job of conveying the result shape: edges with specific fields, unresolved records, and device comments. It is slightly incomplete because it does not describe how the returned data is packaged or how the format parameter affects it, but the core behavior is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already explains root, device, and opcode. The description introduces important domain concepts like argument indexes, widths, ranges, and confidence, but it does not specifically explain how the parameters affect the output beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific, action-oriented verb ('Build') and names a well-defined resource ('argument-level source-to-destination value-flow edges'). It goes on to specify the kinds of instructions covered and the fields produced, making it clearly distinct from siblings like gx3_trace_device or gx3_xref_where_used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for conservative value-flow analysis and mentions behavior for unknown operations, so an agent can infer a use case. However, it never explicitly states when to choose this tool over alternatives such as gx3_trace_device or gx3_xref_where_used, nor does it name any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find logic that can never do anything: contacts that can never close, NC contacts on always-ON relays, coils and words written but never read, and SET latches with no matching RST. Returns findings grouped by kind with the device, its comment and where it appears. Reads the project; WRITES a CSV under the output directory. Devices refreshed from a network are excluded, since a remote station may be the real reader. Requires the xref DB.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses that the tool reads the project and writes a CSV under the output directory, which is a non-obvious side effect. It also reveals the network-device exclusion and the xref DB prerequisite, making behavioral traits and assumptions transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a vivid purpose statement followed by concrete examples. Each subsequent sentence earns its place: return grouping, side effects, exclusions, and prerequisites. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is remarkably complete. It covers purpose, output format, side effects (CSV write), exclusions (network devices), and prerequisites (xref DB), enabling an agent to select and invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the only parameter 'root' is already documented as 'Extracted project folder.' The description mentions 'the project' but does not add new meaning about how 'root' is used beyond what the schema provides. This matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') and resource ('logic that can never do anything'), then enumerates four concrete detection categories: contacts that can never close, NC contacts on always-ON relays, written-but-never-read coils/words, and SET latches with no matching RST. This distinguishes it from siblings like gx3_lint, gx3_data_flow, and gx3_xref_where_used without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context by stating a prerequisite ('Requires the xref DB') and an exclusion rule ('Devices refreshed from a network are excluded, since a remote station may be the real reader'). However, it does not explicitly name alternative tools or state 'use this when...', so it lacks explicit routing versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report, per device type, observed LD usage, density, and gaps in the index. Gaps are not verified free allocations: ST/FBD, unresolved accesses and external or reserved allocations are not excluded. Verify them in GX Works3 before adding devices. Read-only; returns a table and writes nothing. Requires the index-lite DB: run gx3-cli index-lite build --root <root> once per project first.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| types | No | Comma-separated device types, e.g. M,D,W. | |
| min_free | No | Only report free gaps at least this large. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it explicitly states 'Read-only', 'returns a table and writes nothing', warns that gaps are not verified free allocations, and explains what may be included or excluded. It also discloses the prerequisite database state, giving the agent a clear model of the tool's behavior and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and every sentence adds value: result contents, the critical verification caveat, safety/read-only behavior, and the required setup command. Nothing is redundant or extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are no annotations and no output schema, the description is remarkably complete: it states what the tool reports, what it does not guarantee, that it writes nothing, what output shape to expect, and the prerequisite setup. An agent has enough information to decide when to call it and what to do with the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaningful context beyond the schema. The caveat that gaps are unverified and the 'per device type' framing enrich the meaning of `min_free` and `types`, helping the agent interpret results and filter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a precise resource scope ('per device type, observed LD usage, density, and gaps in the index'), which makes the tool's purpose immediately clear. It does not explicitly name a sibling alternative, but the focused phrasing distinguishes it from related tools like gx3_alarm_map or gx3_dead_logic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: before adding devices, to identify gaps that need verification in GX Works3. It also states a concrete prerequisite ('run gx3-cli index-lite build --root <root> once per project first'), though it does not explicitly contrast it with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Match a captured device snapshot against the enable conditions the static trace produced, and say what the snapshot does not answer for. Reads files only: this never opens a PLC connection, and there is no MCP tool that does. Report the analysis state with the result -- a device the snapshot holds no value for comes back as 'no measured value; file only', and the rows that did evaluate are not the whole answer when that appears. One snapshot explains the instant it was captured, never the cause of a past stop or trip: do not use it to answer 'why did this trip earlier'.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| device | Yes | Target device or resolved label. | |
| format | No | text | |
| snapshot | Yes | Captured live-values JSON, previously exported. | |
| max_depth | No | ||
| max_devices | No | ||
| exclude_reset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and meets it. It discloses read-only file behavior, the absence of PLC connectivity, the special 'no measured value; file only' result state, and the snapshot's temporal limitation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, and every sentence adds a distinct piece of information. It is slightly dense, especially the sentence about rows that did evaluate, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a file-analysis tool with no output schema and no annotations, it covers the essential use context, read-only safety, output caveats, and temporal limitations. It is incomplete only in not characterizing the full return shape or the behavior of optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%, and the tool description does not explain the undocumented optional parameters (format, max_depth, max_devices, exclude_reset) or how they affect the result. It adds context for the required snapshot/device/root inputs, but leaves most optional parameter semantics to inference from names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: match a captured device snapshot against the enable conditions produced by the static trace, and say what the snapshot does not answer for. It also explicitly rules out trip-cause questions, so the tool's scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the tool reads files only, never opens a PLC connection, and that no MCP tool does. It also provides a concrete when-not-to-use example: do not use it to answer why a trip happened earlier. This is clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Static satisfiability check: can two coils' ON/enable conditions be true at the same time? A 'mutually-exclusive' verdict is sound; a 'simultaneous-possible' verdict returns a witness assignment but is not a reachability proof.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| device_a | Yes | First coil/device. | |
| device_b | Yes | Second coil/device. | |
| max_vars | No | Variable cap for the SAT search. | |
| max_depth | No | Upstream substitution depth. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It adds significant value by explaining that 'mutually-exclusive' is sound and 'simultaneous-possible' returns a witness but not a reachability proof. This clarifies the nature of the result and its limits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly written, with the core question and the critical soundness caveat front-loaded. Every phrase adds meaning and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 provides useful return semantics by mentioning verdicts and witness assignments. It covers the most important caveat (not a reachability proof), which is essential for correct interpretation. Minor gaps include not describing possible error conditions, but overall it is sufficiently complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add much parameter-specific detail, though it loosely maps device_a/device_b as coils. The schema already covers root, max_vars, and max_depth adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (static satisfiability check) and precise resource (two coils' ON/enable conditions). It clearly distinguishes this from sibling tools like trace, data flow, or lint by focusing on whether two conditions can be true simultaneously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use clear: determine if two coils' ON/enable conditions can co-occur. It also signals a key limitation—'simultaneous-possible' is not a reachability proof—which helps the agent avoid over-trusting the result, though it does not explicitly name alternative tools for reachability analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a program in GX Works3 print-text layout. This is the output to show a user when explaining how a circuit is wired: quote it verbatim in a code block, never a JSON dump of the same rung. Output can be large; pass 'output' to write it to a file. To emit only the circuit under discussion, use 'list_sections' to discover section titles, then filter with 'section', 'pos_range' (A-B), or 'device'.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| device | No | Render only rungs referencing this device (any role), plus their section title. | |
| output | No | Optional output file path (-o); parent dirs are created. | |
| program | Yes | Program/POU name or <hash>_LDDB.db. | |
| section | No | Render only sections whose title contains this text. | |
| pos_range | No | Render only rows whose step pos is within A-B (inclusive). | |
| list_sections | No | List section titles with pos range and rung count, then exit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that output can be large, that 'output' writes to a file, that list_sections exits after listing, and that the result should be quoted verbatim rather than restructured. This is strong coverage, though it does not detail all edge-case behaviors such as exact return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and each sentence earns its place: purpose, output handling, and filtering workflow. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the essential context: what the tool renders, how to present the result, how to manage large outputs, and how to narrow the result via list_sections and filters. An agent has enough information to invoke the tool correctly in the intended workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining why 'output' matters (large output), how list_sections relates to filtering, and which filters are appropriate for narrowing the rendered circuit. This enriches the schema definitions without repeating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Render a program in GX Works3 print-text layout." It also clarifies the intended use case—showing a user how a circuit is wired—which distinguishes it from sibling analysis and check tools like gx3_lint or gx3_interlock_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool: when explaining circuit wiring, and how to present the output (verbatim in a code block, not JSON). It also provides a concrete workflow for filtering output using list_sections, section, pos_range, and device, making usage conditions clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run static review checks over the whole project and return a per-check summary with finding counts by severity. Checks: duplicate coils, multi-writers, alarm quality, unused devices, contradictory comments, linked-device writes, and signed/width/division type problems. Reads the project; WRITES one CSV per check plus a JSON summary into the working directory. Findings are advisory: a duplicate coil may be a deliberate SET/RST pair, so report the severity and let the engineer judge. Needs the index and xref DBs for the full check set.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| checks | No | Comma-separated check names, or 'all' (default). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the tool reads the project, writes one CSV per check plus a JSON summary, and that findings are advisory rather than definitive. This is excellent transparency about side effects and interpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a compact list of covered checks, then behavioral and prerequisite notes. Every sentence carries load-bearing information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool without an output schema, the description adequately covers return behavior ('per-check summary with finding counts by severity'), file side effects, advisory semantics, and prerequisites. An agent has enough context to call it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by listing the specific check categories an agent can expect, which helps interpret the 'checks' parameter even though the schema already documents comma-separated names or 'all'. The 'root' parameter meaning is already clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Run static review checks over the whole project' and names the exact kinds of checks. This clearly distinguishes lint from sibling tools like gx3_trace_device or gx3_data_flow, which serve different inspection purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use this tool: when a whole-project static review with per-check severity summaries is needed. It also gives the prerequisite that index and xref DBs are needed for the full check set. It does not explicitly name alternatives or when-not-to-use conditions, but the scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every project-read-only GX3 CLI command this server will run, with a one-line summary of each. Read-only; touches no project. Call this before gx3_run_command when no typed tool fits, to see what is actually available rather than guessing a command name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It clearly states the tool is read-only, touches no project, and returns a one-line summary per command. This adequately discloses side effects and output shape for a simple listing tool, though it does not describe pagination or formatting details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The core purpose and output are front-loaded in the first sentence, and the second sentence adds essential usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter discovery command with no output schema, the description is complete: it states what the tool lists, how the list is formatted, that it is safe/read-only, and when to use it relative to gx3_run_command. An agent has everything needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and schema coverage is 100% by definition. With no parameters to document, the description does not need to add parameter-level semantics; the baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('List') and resource ('every project-read-only GX3 CLI command'), and clearly states the output format ('with a one-line summary of each'). It is immediately distinguishable from all sibling tools, especially gx3_run_command, because it is a meta-command that enumerates available CLI commands rather than performing a domain action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: call this before gx3_run_command when no typed tool fits, to discover what is actually available rather than guessing a command name. This names the alternative tool and the condition that selects this tool, leaving no ambiguity about when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map how this PLC is wired to everything outside it: IP addresses, CC-Link and SCON stations, and safety relationships, aggregated into one view. Use it to find which unit or remote station owns a device before assuming the program drives it. Reads the project and the comm detail CSVs; WRITES its own CSVs under the output directory. It does not communicate with any device -- everything is read from the project files.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| prefix | No | Communication prefix (optional). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It explicitly states that the tool reads project and comm detail CSVs, writes its own CSVs under the output directory, and does not communicate with any device. This fully covers the main side-effect and safety-relevant behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler: purpose, usage cue, and behavioral constraints are each given their own sentence. Key information is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is quite complete: it explains the purpose, the triggering scenario, the data sources, the write side effect, and the lack of device communication. It does not enumerate output CSV filenames or the exact return shape, but 'aggregated into one view' plus CSV output is enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already described meaningfully, so the baseline is 3. The description only contextualizes the parameters by mentioning project and comm detail CSVs; it does not add new format, optionality, or behavioral detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it maps how the PLC is wired to everything outside it, covering IP addresses, CC-Link/SCON stations, and safety relationships. It clearly distinguishes from the sibling tools by emphasizing external/network wiring and device ownership rather than command lists, ladders, or diffs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear selection cue: 'Use it to find which unit or remote station owns a device before assuming the program drives it.' It does not name sibling alternatives or explicitly state when not to use it, but the context is strong enough for an agent to choose it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an already-captured CSV/JSON device log offline: normalize it, emit per-device time series, list value change points, or export one instant as a snapshot for gx3_explain_snapshot. Reads files only and never opens a PLC connection. An imported or polled log is not a scan-synchronized recording: two devices that appear to change together may simply have been sampled together, so do not read ordering between devices out of it.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | ISO 8601 timestamp; required for verb=snapshot. | |
| root | No | Optional project, used only to verify project_fingerprint. | |
| verb | Yes | What to do with the captured log. | |
| input | Yes | Captured CSV or JSON log. | |
| device | No | Optional one-device filter for series/changes. | |
| at_mode | No | exact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states it only reads files and never opens a PLC connection, and it warns about interpreting temporal ordering between devices due to sampling. This provides good insight into the tool's behavior, though it does not explicitly confirm the absence of side effects beyond the read-only implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main purpose stated upfront and additional caveats presented in a clear, second sentence. It avoids unnecessary detail while covering the essential operations and the important sampling caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a high-level overview of the four operations (normalize, series, changes, snapshot) and mentions the relationship to gx3_explain_snapshot. However, it does not elaborate on the output format or specific behavior of each verb, which could leave an agent uncertain about which verb to choose for a given task. Overall, it is reasonably complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%) with all parameters described. The tool description adds little beyond the schema, except for hinting that snapshot output is intended for gx3_explain_snapshot. Since the schema already covers parameter meanings well, the description does not meaningfully enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reading captured CSV/JSON logs offline and performing specific operations (normalize, series, changes, snapshot). It uses specific verbs and distinguishes itself from live tools by explicitly noting it never opens a PLC connection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the scenario of 'already-captured' logs and the offline nature, which implies when to use it, but it does not explicitly contrast with alternative sibling tools (e.g., gx3_trace_device for live data). No direct when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: run any MCP-allowed, project-read-only GX3 CLI command with explicit arguments. Project-mutating commands and local demo generation commands are rejected. Local artifacts are confined to GX3_MCP_OUTPUT_DIR. Prefer the typed tools above when one fits.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| root | No | Optional extracted project root. | |
| command | Yes | MCP-allowed GX3 CLI command name. | |
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that the tool is read-only, restricts to MCP-allowed commands, rejects mutating operations, and confines local artifacts to GX3_MCP_OUTPUT_DIR. It does not describe error behavior or exact execution semantics, but the key safety-relevant traits are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, followed by constraints and routing guidance. Every sentence adds necessary information with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic command-running escape hatch without annotations or an output schema, the description covers the essential constraints: allowed scope, rejected operations, artifact confinement, and sibling tool preference. It could be more complete with an example or note on command availability via gx3_list_commands, but the core guidance is sufficient for an agent to select and invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: command and root have descriptions, while args and timeout_seconds do not. The description adds useful context by noting commands must be MCP-allowed and project-read-only, and that args are explicit, but it does not explain how to format args or how timeout behaves. It partially compensates for the schema gaps but leaves room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('run') and resource ('GX3 CLI command'), and frames itself as an 'escape hatch' for cases where typed tools don't fit. It clearly distinguishes itself from the sibling typed tools by naming them as preferable when they do fit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to prefer typed tools when one fits, and defines the boundary of what is allowed: MCP-allowed, project-read-only commands only. It also states what is rejected (project-mutating commands and local demo generation), giving clear selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two versions of a project rung by rung and return what was added, removed or changed. Rungs are matched by their stable block GUID rather than by position, so inserting a rung does not report everything after it as changed. Use it to review what a revision actually did. Reads both projects; WRITES a detail CSV. Neither project is modified.
| Name | Required | Description | Default |
|---|---|---|---|
| new | Yes | New project folder or .gx3. | |
| old | Yes | Old project folder or .gx3. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It states that both projects are only read, that neither project is modified, and that a detail CSV is written. This is strong transparency, though the destination/location of the CSV is not specified, leaving a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core comparison behavior is in the first sentence, the matching mechanism in the second, the intended use in the third, and side effects in the final sentence. Every sentence adds distinct value without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two string parameters and no output schema, the description covers the main behaviors: what it compares, how rungs are matched, what it returns, and that it writes a CSV without modifying inputs. The only notable omission is where the CSV is written and the exact return format, but this remains adequate for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'old' and 'new' described as 'project folder or .gx3'. The tool description does not add extra parameter-level semantics beyond that, but the baseline of 3 is appropriate because the schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Compare') and resource ('two versions of a project rung by rung'), and clearly states the output ('what was added, removed or changed'). It also distinguishes itself from positional diffing by mentioning stable block GUID matching, which helps separate it from simpler diff-like tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Use it to review what a revision actually did.' It does not explicitly name alternatives or exclusion conditions, but the intended scenario is clear enough for an agent to select this tool over siblings like gx3_explain_snapshot or gx3_list_commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace a device's ON/OFF/hold conditions from exact ladder topology. MC master-control zone conditions are folded into the enable logic, and the output warns on multi-OUT-coil devices and rows below a conditional jump. The output carries each device's comment: keep every device paired with its comment when you report the result, and show the rung itself with gx3_ladder_print rather than describing it in prose.
| Name | Required | Description | Default |
|---|---|---|---|
| ja | No | Japanese headings. | |
| root | Yes | Extracted project folder. | |
| device | Yes | Target device, e.g. Y10, M4801, D200. | |
| compact | No | Evidence-focused compact summary. | |
| max_depth | No | ||
| strict_logic | No | Derive AND/OR from topology (recommended). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and succeeds: it discloses that MC master-control zone conditions are folded into enable logic, that multi-OUT-coil devices and jump-skipped rows produce warnings, and that output includes device comments. These are non-obvious behavioral details beyond what the schema or name reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with purpose and followed by edge-case behavior and output guidance. Every sentence earns its place; there is no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description covers the main behavioral results, warnings, and the expected output-pairing instruction. It could go slightly further by explaining how max_depth constrains the trace, but the high schema coverage and strong behavioral detail make it largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents most parameters. The description adds no parameter-specific meaning beyond noting the output carries comments; max_depth remains undocumented in both schema and description. This meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Trace a device's ON/OFF/hold conditions from exact ladder topology.' It also distinguishes itself from siblings by telling the agent to use gx3_ladder_print for showing the rung, making the division of labor clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool—when tracing a device's conditions from ladder topology—and explicitly routes rung display to gx3_ladder_print rather than describing the rung in prose. It does not enumerate exclusions versus other siblings like gx3_xref_where_used or gx3_interlock_check, but the context is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writers and readers of a device with POU name and real step. The first line carries the device comment; repeat it alongside the device in your answer instead of reporting a bare device number. Requires the xref DB: run gx3-cli xref build --root <root> once per project first.
| Name | Required | Description | Default |
|---|---|---|---|
| root | Yes | Extracted project folder. | |
| device | Yes | Device to look up. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses an output convention—the first line carries the device comment and should be repeated alongside the device—and it warns that a prebuilt xref database is required. It does not mention side effects or failure modes, but for a read-oriented where-used lookup the disclosed context is meaningful and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by an output-handling note and a setup prerequisite. Each sentence adds distinct information, though the first sentence is slightly elliptical and could be more explicit.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers the main needed context: what the tool returns, how to handle the first-line device comment, and the xref database prerequisite. It does not fully describe the result structure beyond the first line, but enough is present for an agent to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'root' and 'device' already described, so the baseline is 3. The description adds only a mention of '--root <root>' in the prerequisite command and does not deepen the meaning of either parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool surfaces writers and readers of a device, with POU name and real step, which clearly points to a where-used lookup. It lacks an explicit verb like 'list' or 'find,' and it does not contrast itself with siblings such as gx3_trace_device or gx3_data_flow, but the meaning is still reasonably specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context by requiring the xref DB and telling the agent to run 'gx3-cli xref build --root <root>' once per project first. It does not explicitly compare against sibling tools or state when not to use this tool, but the purpose and prerequisite make the intended usage fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0gx3_data_flowgx3_explain_snapshotgx3_replay_capturev0.1.0gx3_alarm_mapgx3_dead_logicgx3_device_mapgx3_interlock_checkgx3_ladder_printgx3_lintgx3_list_commandsgx3_network_mapgx3_run_commandgx3_semantic_diffgx3_trace_devicegx3_xref_where_usedScored across 15 tools
Most tools target clearly distinct analysis tasks (interlock check, dead logic, trace, xref, data flow, lint, device map, alarm map, diff, network map, print, snapshot, replay). The main overlaps are gx3_dead_logic vs gx3_lint and the device-relationship cluster of trace_device/xref_where_used/data_flow, but the detailed descriptions provide enough separation to avoid serious misselection.
All names share the gx3_ prefix and snake_case style, which creates a strong family identity. The post-prefix portion mixes verb-led names (trace_device, explain_snapshot, replay_capture, run_command) with noun-led report names (dead_logic, device_map, alarm_map, semantic_diff, network_map, ladder_print), a mild convention split that is still readable and predictable.
At 15 tools, the count is at the upper boundary of the well-scoped range, and each tool earns its place by addressing a distinct analysis workflow. The command-discovery and escape-hatch tools (gx3_list_commands, gx3_run_command) are justified additions rather than padding for this domain.
The server covers the core static-analysis, comparison, printing, and offline-capture workflows comprehensively. Minor gaps exist: gx3_ladder_print references a list_sections tool that is not provided as a typed tool, and prerequisite xref/index DBs must be built outside the server, but gx3_run_command or user instructions can work around these.
Query Allen-Bradley and Siemens PLC projects, live tag values, and analyses in plain English.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Read, analyze, and safely edit Microsoft Project MPP files.
