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
Section titled “PLC tools”These tools are available when a PLC is connected — but which ones depend on your connection method. get_cpu_status, get_tag_value, browse_tags, and read_multiple_tags work over both the S7 WebServer and OPC UA connection methods. Every other PLC tool on this page (diagnostic buffer, alarms, module states, cycle time, PLC clock) requires the S7 WebServer connection method — see OPC UA Setup for the full breakdown.
get_cpu_status
Section titled “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
Section titled “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
Section titled “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
Section titled “acknowledge_alarm”Acknowledges a specific alarm by ID. Only called when you explicitly ask to acknowledge.
Parameters:
id— alarm ID as returned bybrowse_alarms
Example prompt: “Acknowledge the low-pressure alarm.”
browse_tags
Section titled “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
Section titled “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
Section titled “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 asget_tag_value)
Example prompt: “Read the setpoint and actual value for temperature at the same time.”
get_module_states
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.”
More block tools
Section titled “More block tools”| Tool | What it does |
|---|---|
get_block_raw_xml |
The raw TIA Portal XML of a block, for debugging. To read logic, use get_block_source or get_lad_block_code |
create_global_db |
Creates a global data block. If it goes into a folder, the folder must exist first |
create_instance_db |
Creates an instance data block for an existing function block |
create_block_folder |
Creates a folder (group) for blocks |
move_block |
Moves a block to an existing folder of the same PLC |
rename_block |
Renames a block. The agent does this only when you ask; cross references in other blocks are not updated |
delete_block |
Deletes a block permanently and saves the project |
compile_device |
Compiles the software of a PLC and returns every error and warning |
compile_hardware |
Compiles the hardware configuration of the station that holds a PLC |
Native Ladder tools
Section titled “Native Ladder tools”See Native Ladder Blocks for how they are used together.
| Tool | What it does |
|---|---|
get_lad_block_code |
Exports a LAD (or FBD) block as source text: the logic of every network, plus titles and comments. With a folder given, the files are saved there and only a short summary comes back |
get_lad_syntax_reference |
The syntax reference for the Ladder text format. The agent reads it before it writes Ladder |
import_lad_block |
Creates or replaces a LAD block from source text, compiles it, and saves the project when it compiles cleanly. It will not replace an existing block unless the agent was told to |
append_lad_networks |
Adds networks to the end of an existing LAD block, compiles, and rolls the block back if the new part does not compile |
Data types, tags, and constants
Section titled “Data types, tags, and constants”| Tool | What it does |
|---|---|
get_udts / get_udt_code |
Lists the PLC data types, or returns the members of one (types, start values, comments) |
import_udt |
Creates one or more data types from a file with TYPE ... END_TYPE declarations |
delete_udt |
Deletes a data type. It refuses and lists the users if another type or a block still uses it |
create_plc_tag_table / rename_tag_table / delete_plc_tag_table |
Creates, renames, or deletes a global tag table |
create_plc_tag |
Creates one tag in a table, with data type, address, and comment |
create_plc_tags_from_file |
Creates many tags at once from a JSON file, for example the I/O map written by the Ladder Migration tools |
delete_plc_tag |
Deletes a tag from a table |
read_user_constant |
Lists the user constants with data type and value |
create_user_constant / update_user_constant / delete_user_constant |
Creates, changes, or deletes a user constant |
Technology objects
Section titled “Technology objects”| Tool | What it does |
|---|---|
list_technology_objects |
Lists the technology objects of a PLC with type and version |
create_technology_object |
Creates one object: a positioning, speed, or synchronous axis, or another type such as PID_Compact. The project is saved first |
set_technology_object_parameters |
Sets parameters of an object from a list of names and values, then saves |
get_technology_object_parameters |
Lists the configuration parameters of an object with their values. A filter narrows the list, because an axis has about 240 |
delete_technology_object |
Deletes one object. Blocks that use it no longer compile |
Cross references
Section titled “Cross references”| Tool | What it does |
|---|---|
get_callers |
Which blocks call a given block. Slow on projects with many blocks |
get_callees |
Which blocks a given block calls |
get_cross_references |
Callers and callees of a block together, or where a tag is accessed |
Project and hardware
Section titled “Project and hardware”| Tool | What it does |
|---|---|
connect_to_tia_portal / disconnect_from_tia_portal / get_tia_portal_status |
Attaches to the running TIA Portal, detaches, or reports the connection and the open project |
list_projects / open_project / close_project / create_project / save_project |
Project handling |
get_project_intellisense |
A compact map of the PLC: all blocks by type, data types with members, constants, and tag tables. The agent uses it to get oriented quickly |
search_hardware_catalog |
Searches the hardware catalog for devices by a filter text |
add_plc_device / add_hmi_device |
Adds a PLC or an HMI panel from its article number and version |
File tools
Section titled “File tools”These tools operate on files in your configured workspace folder (see Setup & Models).
list_workspace_files
Section titled “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
Section titled “read_workspace_file”Reads the content of a text file in the workspace. Supports reports, CSV, notes, and any UTF-8 text file. A whole-file read is limited to 512 KB.
For a bigger file, or to read only the part around something it found, the agent passes offset (first line, starting at 1) and limit (number of lines, default 200, at most 2000). The result then starts with the range and the total number of lines, for example [lines 249-251 of 1000; more follow: call again with offset=252]. Ranged reads work on files up to 64 MB.
Example prompt: “Read the diagnostic report I saved last week.”
search_workspace_files
Section titled “search_workspace_files”Searches the text of files in the workspace, like grep. It is read-only. The agent uses it to find things in large or many files without reading them whole: the TODO rung placeholders of a generated Ladder migration, a tag or block name, an error message, a keyword in an export.
- Where: one file, or a folder searched recursively. Binary files, files over 64 MB,
node_modulesand.gitare skipped, and the result names what was skipped. - What: plain text by default. The agent can switch to a regular expression, make the match case sensitive, restrict it to file names such as
*.s7dclor*.{scl,s7dcl}, and ask for 0 to 5 lines of context around each match. - How much comes back:
matches(default) listspath:line: text, up to 100 matches (at most 500) with long lines shortened;countgives the number of matches per file;fileslists only the files that match. A result that is cut off says so. - Safety: it only reads inside the workspace folder. A link that leads out of the workspace is not followed. A search runs in a separate thread and is stopped after 20 seconds, so a very expensive regular expression cannot freeze the app; the agent is told to use plain text or a simpler pattern.
The agent usually starts with count, then lists the matches, then reads around a hit with read_workspace_file and a line range.
Example prompt: “How many placeholders did the migration leave in projects/plant1/out, and which reasons cause the most of them?”
write_workspace_file
Section titled “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
Section titled “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
Section titled “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. Files the tools read or write must be inside your workspace folder; a relative path is taken relative to it.
Studio 5000 .L5X tools
Section titled “Studio 5000 .L5X tools”These tools read an .L5X export exactly and generate native Ladder with program code, without using the AI model for the translation. See Studio 5000 project to native Ladder.
| Tool | What it does |
|---|---|
parse_l5x_project |
Reads a whole-controller .L5X and builds the project model: routines and their call order, data types, Add-On Instructions, tags, I/O map, name collisions, and a list of decisions. Read-only and fast |
generate_project_declarations |
Writes the declarations only (data types, Add-On Instruction function blocks, instance data blocks, the global data block, the I/O tags) and the import order |
generate_lad_project |
Writes everything: the declarations and every routine as a LAD function, the review files, and the exact import order. Optional parameters exclude routines by name pattern and choose how safety routines are handled (reference-only blocks, or left out) |
parse_l5x |
Reads an .L5X export of a single routine into an intermediate file, exactly (contacts, polarity, branches, outputs, tag types, timer presets, Add-On Instruction definitions) |
generate_lad_block |
Generates a native LAD function block from an .L5X export of one routine, without writing the Ladder by the model. For a whole controller use generate_lad_project |
set_lad_network |
Replaces one network of a generated file, usually a placeholder, with Ladder or SCL |
add_lad_members |
Declares extra variables in the interface of a generated file |
list_placeholders |
Lists the rungs the generator could not translate (placeholders) of a generate_lad_project run: the count per category first, then each placeholder with its original Studio 5000 rung, the reason, a triage class and its status. The triage is a suggestion from the reason text: write (the S7 form exists, the generator has no rule yet), decide (needs you or the hardware: motion, drive diagnostics, communication, safety), blocked (the source is not in the export, such as a vendor block) or review |
get_placeholder_context |
Everything needed to resolve one placeholder: the full original rung, the types of its tags, the network as it stands in the generated file, and the calls to replace and check it. For some categories (so far COP in its different forms, jumps and labels, and a variable index into an array of Add-On Instruction instances) it also includes a recipe: tested patterns that were compiled in TIA Portal, and what the agent still has to ask you (for example the word or byte order of a device) |
set_placeholder_status |
Records where a placeholder stands (open, written, asked, skipped) in placeholder_status.json and migration_status.md, next to the generated files, so the state survives a long session. set_lad_network marks the network it replaced as written by itself |
list_tags |
Lists every tag of an intermediate file with how it is used (read, written), so the interface of a block can be declared once |
verify_lad_block |
Compares a migrated LAD block with the intermediate file it was built from, network by network, and lists the differences. See Reviewing migrated Ladder |
Example prompts: “Migrate Plant.L5X to native Ladder in PLC_1.” / “Migrate the routine in Conveyor.L5X to a LAD function block.” / “Check the block FC_Start against its source.”
PDF to SCL tools
Section titled “PDF to SCL tools”These tools work from a PDF printout and produce SCL. See PDF to SCL workflow.
parse_ladder_pdf
Section titled “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— path to the PDF file in your workspacevendor— 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
Section titled “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.mdfile returned byparse_ladder_pdf
Example prompt: “List all the networks in the intermediate file.”
convert_network_to_scl
Section titled “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 filenetwork_number— the network number to convert (e.g.5)vendor— source PLC vendorblock_type—'FB'or'FC'
Example prompt: “Convert just network 7 to SCL so I can check the timer logic.”
convert_all_to_scl
Section titled “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 filevendor— source PLC vendorblock_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
Section titled “get_intermediate”Returns the 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 filefirst_network,last_network— optional range, for a large file (the whole file is returned when both are left out)
Example prompt: “Show me the raw intermediate for network 3 — I want to check the parsed contacts.”
write_scl_file
Section titled “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— path ending in.scl, inside your workspace folder (for exampleprojects/plant1/FB_Baler.scl)
Example prompt: “Save the corrected SCL as projects/motor/FB_MotorControl_v2.scl.”
save_intermediate
Section titled “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 contentoutput_path— path for the output file, inside your workspace folder
Example prompt: “Save this corrected intermediate so I can re-run the conversion.”