Skip to content

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.

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.

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?”


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?”


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?”


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.”


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?”


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?”


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.”


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?”


Reads the current PLC scan cycle time.

Returns: Cycle time in milliseconds.

Example prompt: “What is the current cycle 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.”


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

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?”


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?”


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.”


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?”


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?”


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.”


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.”


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

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
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
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
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
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

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

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?”


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.”


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_modules and .git are 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 *.s7dcl or *.{scl,s7dcl}, and ask for 0 to 5 lines of context around each match.
  • How much comes back: matches (default) lists path:line: text, up to 100 matches (at most 500) with long lines shortened; count gives the number of matches per file; files lists 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?”


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.”


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

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


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.

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.”


These tools work from a PDF printout and produce SCL. See PDF to SCL workflow.

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 workspace
  • 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.”


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.”


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.”


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.”


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 file
  • first_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.”


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 example projects/plant1/FB_Baler.scl)

Example prompt: “Save the corrected SCL as projects/motor/FB_MotorControl_v2.scl.”


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 — path for the output file, inside your workspace folder

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