Tools Reference

The AI Agent decides which tools to call automatically based on your question. You don’t invoke tools directly — just ask in plain language. This reference documents what each tool does so you know what to ask for.

PLC tools

These tools are always available when a PLC is connected.

get_cpu_status

Reads the current operating state of the connected PLC.

Returns: Operating mode (RUN/STOP/STARTUP), IP address, and API version.

Example prompt: “Is the PLC running?” / “What CPU is connected?”

---

get_diagnostic_buffer

Reads the PLC diagnostic buffer — the built-in event log of hardware faults, software errors, mode changes, and operator actions.

Parameters:

• count (default 20, max 100) — how many recent events to retrieve

Returns: Timestamped list of diagnostic events with human-readable descriptions.

Example prompt: “What happened in the last hour?” / “Why did the PLC stop?”

---

browse_alarms

Reads the current alarm list from the PLC.

Parameters:

• count (default 50) — maximum alarms to return

Returns: All alarms with their text, state (active/acknowledged/cleared), timestamps, and alarm IDs.

Example prompt: “Are there any active alarms?” / “Which alarms are unacknowledged?”

---

acknowledge_alarm

Acknowledges a specific alarm by ID. Only called when you explicitly ask to acknowledge.

Parameters:

• id — alarm ID as returned by browse_alarms

Example prompt: “Acknowledge the low-pressure alarm.”

---

browse_tags

Navigates the PLC tag namespace and lists available variables.

Parameters:

• filter — tag path to browse. Omit for root level. For a data block use "DBName". For a nested struct use "DBName".struct.

Returns: List of tags with name, data type, and hasChildren flag. If hasChildren is true, call browse_tags again with that name to go deeper.

Example prompt: “What tags are in the ProcessData data block?”

---

get_tag_value

Reads the current value of a single PLC tag.

Parameters:

• name — symbolic tag name. Data block variables: "DBName".varName (DB name in quotes). Global/M/I/Q tags: bare symbolic name only (e.g. Alarm1, not %M2000.0).

Returns: Current value, data type, and quality indicator.

Example prompt: “What is the current temperature setpoint?” / “Is conveyor 3 running?”

---

read_multiple_tags

Reads multiple tag values in one call — more efficient than calling get_tag_value repeatedly.

Parameters:

• names — array of symbolic tag names (same syntax rules as get_tag_value)

Example prompt: “Read the setpoint and actual value for temperature at the same time.”

---

get_module_states

Checks the health state of hardware modules in the PLC rack.

Returns: Module status for each slot — good, faulty, or missing.

Example prompt: “Are any I/O modules in a fault state?”

---

get_cycle_time

Reads the current PLC scan cycle time.

Returns: Cycle time in milliseconds.

Example prompt: “What is the current cycle time?”

---

get_plc_time / set_plc_time

Reads or sets the PLC system clock. Useful for correlating diagnostic timestamps with wall-clock time, or correcting clock drift.

Example prompt: “What time does the PLC think it is?” / “Sync the PLC clock to the current PC time.”

---

TIA Portal tools

These tools are available when a TIA Portal project is connected via the MCP integration. See TIA Portal Overview for setup.

get_blocks

Lists all blocks (FBs, FCs, OBs, DBs) in a PLC device.

Parameters:

• device_name — name of the PLC device in TIA Portal (e.g. PLC_1)

Returns: Block name, number, type, programming language, and folder path.

Example prompt: “What function blocks are in this project?”

---

get_block_interface

Reads the input/output interface of a block — parameters, instance data, and local variables — without loading the full source.

Parameters:

• device_name, block_name

Returns: Structured interface with section names (INPUT/OUTPUT/IN_OUT/STATIC/TEMP), variable names, data types, and initial values.

Example prompt: “What are the inputs and outputs of FB_MotorControl?”

---

get_block_source

Reads the full source code and interface of a block.

Parameters:

• device_name, block_name

Returns: SCL source code for SCL blocks; per-network summary (title, comment, called blocks, accessed variables) for LAD/FBD blocks; variable structure for DBs.

Example prompt: “Show me the source code for FC_PIDCalculation.” / “Explain what OB35 does.”

---

get_devices

Lists all devices in the TIA Portal project — PLCs, HMIs, drives, etc.

Returns: Device names, types, and article numbers.

Example prompt: “What devices are in this project?”

---

get_profinet_topology

Returns the network topology: IP addresses, subnet masks, and subnet connections for every PROFINET interface in the project.

Example prompt: “What IP addresses are configured for the PLCs in this project?”

---

list_tag_tables / get_tag_table

Lists all global tag tables in a PLC device, or reads the full contents of one table (symbolic names, data types, logical addresses, and comments).

Example prompt: “What global tag tables does PLC_1 have?” / “Show me all tags in the default tag table.”

---

create_block / import_scl_file

Creates or imports a new block from SCL source. Used primarily during the Ladder Migration workflow.

Example prompt: “Save this SCL code as FC_NewLogic in the project.”

---

File tools

These tools operate on files in your configured workspace folder (see Setup & Models).

list_workspace_files

Lists files and folders in the workspace (or a subfolder). Results include the workspace root absolute path — the agent uses this when calling tools that need absolute paths (e.g. import_scl_file).

Example prompt: “What files are in the workspace?”

---

read_workspace_file

Reads the content of a text file in the workspace (up to 512 KB). Supports reports, CSV, notes, and any UTF-8 text file.

Example prompt: “Read the diagnostic report I saved last week.”

---

write_workspace_file

Creates or overwrites a file in the workspace with text content. Automatically creates any intermediate folders.

Example prompt: “Save a summary of today’s faults to reports/fault_summary.txt.”

---

create_workspace_folder

Creates a folder (and any parent folders) in the workspace.

Example prompt: “Create a folder called migrations/project1 in the workspace.”

---

Ladder Migration tools

These tools are available when the Ladder Migration MCP server is connected via Settings → Connections → Ladder Migration MCP. See Ladder Migration Overview for setup.

parse_ladder_pdf

Parses a Ladder Logic PDF printout into a structured intermediate markdown file. Renders every page as an image and uses Claude Vision to extract each network/rung. The intermediate file is saved automatically next to the source PDF.

Parameters:

• pdf_path — absolute path to the PDF file
• vendor — source PLC vendor hint ('Siemens', 'Allen-Bradley', 'Mitsubishi', 'Omron', or 'auto' to detect automatically)

Returns: Path to the saved intermediate file and a summary of networks found.

Example prompt: “Parse the file MotorControl_LAD.pdf in my workspace.”

---

list_networks

Lists all networks in a parsed intermediate file with a summary table of network titles and comments. Useful for reviewing what was extracted before running conversion.

Parameters:

• intermediate_file — path to the _intermediate.md file returned by parse_ladder_pdf

Example prompt: “List all the networks in the intermediate file.”

---

convert_network_to_scl

Converts a single network from the intermediate file to SCL. Use this to validate conversion quality on a specific network before converting the entire block.

Parameters:

• intermediate_file — path to the intermediate file
• network_number — the network number to convert (e.g. 5)
• vendor — source PLC vendor
• block_type — 'FB' or 'FC'

Example prompt: “Convert just network 7 to SCL so I can check the timer logic.”

---

convert_all_to_scl

Converts all networks in the intermediate file to a complete TIA Portal SCL block. The SCL source is returned in full and also saved automatically to a .scl file next to the intermediate file.

Parameters:

• intermediate_file — path to the intermediate file
• vendor — source PLC vendor
• block_name — name for the generated block (e.g. 'FB_MotorControl')
• block_type — 'FB' (default, for logic with timers/counters/latching) or 'FC'

Example prompt: “Convert all networks to FB_MotorControl as a Function Block.”

---

get_intermediate

Returns the full contents of the intermediate markdown file for inspection or editing. Use this to review exactly what the parser extracted before running conversion, or to check a specific network’s parsed representation.

Parameters:

• intermediate_file — path to the intermediate file

Example prompt: “Show me the raw intermediate for network 3 — I want to check the parsed contacts.”

---

write_scl_file

Writes SCL source code to a .scl file on disk, overwriting any existing content. Use this when TIA Portal’s import_scl_file reports compile errors: fix the SCL, save it with this tool, then re-import.

Parameters:

• scl_content — pure SCL source code (no markdown fences)
• file_path — absolute path ending in .scl

Example prompt: “Save the corrected SCL to C:\exports\FB_MotorControl_v2.scl.”

---

save_intermediate

Saves a manually crafted or edited intermediate markdown to a specific file path. Use this when you want to correct the parser’s output before running conversion.

Parameters:

• intermediate_md — the intermediate markdown content
• output_path — absolute path for the output file

Example prompt: “Save this corrected intermediate so I can re-run the conversion.”