# The tools, area by area

> What every tool an agent can call does, grouped by the capability toggle that advertises it.

Tool names are stable snake_case identifiers. Errors are structured and actionable: a
failed call returns what went wrong plus a hint naming the tool or step that fixes it,
so an agent self-corrects instead of guessing. When the Backups (manage) area is on, the
server also instructs agents to create a configuration backup before making
configuration changes. Which of these lists an agent actually sees is
[what each area opens](agent-areas).

## Connector — read {#connector--read}

| Tool | What it does |
| --- | --- |
| `connector_browse` | Lists the configured tree with live health: Modbus RTU as driver, serial line, device, tag; every other driver as driver, device, tag with each device's folder beside it. Reveals the tag aliases (`Driver.Folders….Device.Tag`) that `tag_read`, `tag_write` and Logic expressions use. Aliases are null while the embedded server is stopped. |
| `tag_read` | Reads one tag's live values by alias: the raw device-level value, the engineering value after the conversion pipeline, quality and both timestamps. |

## Connector — configure {#connector--configure}

| Tool | What it does |
| --- | --- |
| `driver_capabilities` | Lists every driver the app can serve with the connection fields a device needs, the tag addressing model (free-text address and/or typed fields), discovery support and parameters, timing ranges and the supported value types. The map an agent reads before `device_upsert` or `tag_upsert`. |
| `serial_line_list` | Lists every persisted Modbus RTU serial line, disabled and empty ones included, with its stable id and the configured, automatic and effective timing values. |
| `serial_line_upsert` | Creates a Modbus RTU line or updates one by stable id. Name and enabled state change at any time; the minimum transaction interval also changes while enabled; serial port, baud rate, serial format and response timeout only change while the persisted line is disabled. |
| `serial_line_delete` | Deletes a line by stable id. A line that still contains devices is refused unless the call explicitly authorizes deleting every child device and tag. |
| `device_upsert` | Creates or updates a device by driver + name (the driver is immutable after creation). Only supplied parameters change; connection fields are per driver; moving a device into a folder rewrites every reference to its old tag addresses. The change is reconciled into the running server immediately. |
| `device_delete` | Deletes a device and all its tags; reconciled into the running server immediately. |
| `tag_upsert` | Creates or updates a tag on a device. Addressing is driver-specific (free-text address and/or typed fields); the response echoes the assembled wire address and the alias for `tag_read`. Includes the invalid-reading stages (NaN action and read-failure presentation) for numeric tags. |
| `tag_delete` | Deletes a tag; reconciled immediately. |

## Logic — read {#logic--read}

| Tool | What it does |
| --- | --- |
| `logic_browse` | Browses the rooted Logic address space, the same dot tree every expression reads: System, Server, Connector, Variables, Alarms, Process and Assets. Operator folders are real address levels; child points include their live value and quality. |
| `logic_read` | Reads one point by its dot address (for example `Variables.Setpoint`) and returns the live value and quality. |

## Logic — configure {#logic--configure}

Upserts are partial (omitted parameters keep their value) and every merged draft passes
the same validation the [Logic](logic) editors apply; an invalid draft is rejected and
nothing is half-applied.

| Tool | What it does |
| --- | --- |
| `variable_upsert` | Creates or updates a variable: Expression (a single read-only JavaScript expression over the address space) or Memory (a writable, optionally retentive value). The name is the key and, sanitized, the address; the folder parameter files it, rewriting every reference to the old address. |
| `variable_delete` | Deletes a variable by path, its retained value included. Channels bound to it lose their source. |
| `action_upsert` | Creates or updates an action: a JavaScript statement block with exactly two write verbs, memory-variable assignment and the engineering tag write. Statically validated, never executed at save time. |
| `action_delete` | Deletes an action by name. Triggers bound to it idle. |
| `trigger_upsert` | Creates or updates an interval trigger: every `intervalMs` (minimum 100) the bound action fires on the logic queue; a tick during a pending run is skipped. The action binding is loose and by name. |
| `trigger_delete` | Deletes a trigger; the bound action is untouched. |
| `alarm_upsert` | Creates or updates an alarm: a Bool condition expression, priority (Critical/High/Medium/Low), on/off delays, whether acknowledgement is required, and the annunciation style. Saving a changed condition or timing resets the running state machine. |
| `alarm_delete` | Deletes an alarm by path; an active annunciation is cleared first. |
| `logic_folder_upsert` | Creates, renames or re-files an organizing folder of one section (Variables, Alarms, Actions, Triggers; at most three levels). For Variables and Alarms the folder path is part of the address, so renames and moves rewrite every expression, script, condition and dashboard binding beneath. |
| `logic_folder_delete` | Deletes a folder. Nothing it held is destroyed: items and subfolders re-file one level up and references are rewritten; a name collision at the destination refuses the delete. |

## Logic — operate {#logic--operate}

All of these ride the single logic queue and journal with origin **MCP**.

| Tool | What it does |
| --- | --- |
| `variable_write` | Writes a value into a Memory variable (coerced to its output type, retained when retentive). Expression variables are computed and refuse writes. |
| `tag_write` | Writes an engineering value to a writable tag: reversed through the tag's conversion pipeline, coerced to the device type, written to the equipment. Read-only tags and read-only drivers are refused with the reason. |
| `action_run` | Runs one action on the logic queue and returns its outcome and duration. A disabled action fails without running. |
| `alarm_ack` | Acknowledges one alarm, the operator response; a no-op when nothing is pending. |
| `alarm_ack_all` | Acknowledges every alarm awaiting one, as one logic-queue item with each transition journaled. |

## Server — read {#server--read}

| Tool | What it does |
| --- | --- |
| `server_status` | Reports the embedded OPC UA server's health: running state, uptime, endpoint URL, connected client sessions, and the size of the configured address space. |

## Server — operate {#server--operate}

| Tool | What it does |
| --- | --- |
| `server_start` | Starts the embedded OPC UA server, materializing the current configuration. A no-op when already running. |
| `server_stop` | Stops the server gracefully. Device communication, tag reads and the live Logic address space stop until it starts again. |
| `server_restart` | Stop then start, re-materializing the configuration; the full reload after a batch of changes. |
| `connector_refresh` | Incrementally reconciles the running server with the configured devices (adds, removes, recreates) without a full restart; the lighter way to apply changes. |
| `device_discover` | Runs a driver's device-discovery scan and returns candidates with their tags, persisting nothing. Only drivers whose protocol supports a real scan take part; candidates that already exist are marked as such. |

## Logs — read {#logs--read}

| Tool | What it does |
| --- | --- |
| `logs_read` | Reads the program-wide live log feed (the same one on the [Events](events) Console), filtered by minimum severity (Debug/Information/Warning/Error, default Information), area (App/Server/Connector/Logic/Process/Dashboard/Agent/Licensing), component and a contextual substring; returns the newest matches (default 100, at most 500). Agent actions journal under the Agent area. |
| `event_history_read` | Reads the persistent operational-event timeline, which survives restarts: alarm transitions, occurrence transitions and interlock transitions. Filter by kind (Alarm/Occurrence/Interlock), an inclusive UTC period and a level (alarm priority, occurrence severity or interlock transition); newest first, default 100, at most 500. Strictly read-only: nothing can clear or delete journal entries. |

## Process — read {#process--read}

| Tool | What it does |
| --- | --- |
| `process_models` | Lists the [Process](process) models in full: channels, shared groups, units with resolved wiring and running state, procedures, panels, recipes, evaluations, occurrences, plus the global report-template library. The map an agent reads before starting anything. |
| `process_runs` | Lists runs, most recent first: id, name, state, verdict, what ran, who started it (Station/User/Automation/Agent), timing and cycle progress. Can be restricted to active runs and capped (default 50). |
| `process_run` | Reads one run's complete frozen record by id: snapshot, metadata, judged criteria with sample counts, occurrence episodes and events, as-executed recipe writes, comments, and the frozen report and label artifacts with their print attempts. Optionally computes datalog row count and time range. |
| `unit_status` | Reports a unit's live status: whether it is running (with the active run) and the current engineering value behind each channel, read without recording. |

## Process — configure {#process--configure}

| Tool | What it does |
| --- | --- |
| `process_view_configure` | Configures exactly one panel of a model: the icon drawn beside it and whether it stands on the View page. Nothing else of the Process aggregate is writable over MCP; the rest is edited on the Process page. |

## Process — operate {#process--operate}

Runs started, ended or commented by an agent record **Agent** as the actor, never the
operator who happens to be signed in at the bench.

| Tool | What it does |
| --- | --- |
| `process_snapshot` | Captures one datalog row on a unit outside a procedure. Every call creates a new, already-completed Instant run in [Histories](histories) with no evaluation (verdict None). |
| `process_evaluate` | Captures one datalog row and judges it with an evaluation; creates a completed Instant run and returns its verdict. |
| `process_recipe_apply` | Applies an Instant recipe once to a unit through the Process write funnel and source locks. Commands equipment; creates no run (the writes are journaled). Temporal recipes are refused. |
| `process_start` | Starts a procedure run on a unit, with a JSON object for the procedure's metadata fields. Missing or invalid required metadata, a unit already running, or a shared-channel lock conflict refuse the start. Returns the new run id. |
| `process_stop` | Stops a running run: finalization block, frozen history snapshot, computed verdict. |
| `process_hold` | Holds a run's temporal profile at the last setpoint; the datalog keeps recording. |
| `process_resume` | Resumes a held run's temporal profile. |
| `process_abort` | Aborts a run from Running or Held: finalization runs, the snapshot is written, the state becomes Aborted and the verdict NOK. |
| `process_comment` | Adds a timestamped comment into a run's file: a timeline note while active, a post-run note after. |
| `process_report` | Generates (or regenerates) the PDF report of a finished run and returns its file path. A named template from the global library overrides the procedure's configured one; with neither, the all-sections default layout applies. Refused while the run is active. |
| `process_run_delete` | Permanently deletes a recorded run: its history-index pointer and per-run database file. Refused while active; configuration is untouched. |

## Dashboard — configure {#dashboard--configure}

| Tool | What it does |
| --- | --- |
| `dashboard_list` | Lists dashboards (or, naming a model, that model's screens): grid size, folder, icon, startup flag, role visibility and every component with its position, layer and properties JSON, plus every persisted connection network. Also returns the component-kind catalog with each kind's default size and default property bag. |
| `dashboard_upsert` | Creates or updates a dashboard by name: grid size (a shrink that would orphan a component is rejected), Visualization-list folder and icon, startup flag, status-bar visibility in full screen, and per-role visibility. Naming a model addresses that model's screens instead. Open dashboard pages reflect the change live. |
| `dashboard_delete` | Deletes a dashboard and its components by name; naming a model deletes that model's screen instead. |
| `component_upsert` | Adds a component by kind (placed at the first free cell with the kind's default size unless told otherwise) or updates one by id. Placement must lie inside the grid; overlapping is allowed with the z layer deciding rendering order; the properties JSON is the kind's typed bag. Naming a model addresses that model's screens instead, so a screen created there can be laid out here. |
| `component_delete` | Removes a component by id; naming a model addresses that model's screens instead. |
| `connection_upsert` | Connects two Symbol terminals with a typed connection network, resolving type, role and direction from the symbol catalog exactly as the canvas editor does. Ends that resolve to different types fail unless an undefined connection is explicitly allowed; an anchor already carrying a connection is rejected. Naming a model addresses that model's screens instead. |
| `connection_delete` | Removes one connection network by id and expected revision, so a stale delete is rejected instead of clobbering a newer edit; naming a model addresses that model's screens instead. |

## UI — automate {#ui--automate}

These tools drive the real application window; they exist so an agent can verify the
operator-facing UI, not a simulation of it. Interactions are dispatched to the live
shell, so the intended conduct is to follow each gesture with `ui_screenshot` and
observe the effect, and ambiguous matches come back as candidate lists instead of a
guessed click.

| Tool | What it does |
| --- | --- |
| `ui_state` | Reports the shell's state: active page, available pages, theme, window size and visibility, and the loopback address this instance serves its UI on. The orientation call before anything else. |
| `ui_navigate` | Activates a page of the shell by its stable name, which is English on every station: `View`, `Process`, `Logic`, `Connector`, `Users`, `Validation`, `Events`, `Agent`, `Settings`, `Account`. The label the navigation rail draws in the station's own language is accepted too. |
| `ui_screenshot` | Captures the window as shown on screen into a PNG file and returns its absolute path; restores the window first when hidden to the tray. Can capture one named screen region (a unique, visible `data-doc-region` area) instead of the whole window, and a missing, hidden or ambiguous region fails with the visible regions listed rather than silently falling back to a full capture. |
| `ui_scroll` | Scrolls the active page's main scroll region to top or bottom or by viewport pages, returning the offsets so a long page can be swept. |
| `ui_set_theme` | Applies the theme (System, Light or Dark). This persists exactly like the title-bar theme menu, so a well-behaved agent restores the original value when done. |
| `ui_resize` | Resizes the restored window in device-independent units, clamped to the window minimum; useful to audit compact layouts. |
| `ui_click` | Clicks the visible button, hyperlink, checkbox or toggle whose text matches; checkboxes and toggles are found by their field label and the result reports the landed state. Ambiguity returns the candidates instead of picking one. |
| `ui_set_text` | Writes a value into a text box identified by its field label, committing the binding like typing would. |
| `ui_select` | Selects an item by visible text: a slash-separated path walks a tree, expanding along the way; a single segment also matches list, tab, combo-box items and grid rows on the current page. |

## Backups — manage {#backups--manage}

| Tool | What it does |
| --- | --- |
| `backup_create` | Creates an online snapshot of the configuration database into the backups folder, with an optional note. Recorded runs live outside the configuration and are never touched by backup or restore. |
| `backup_list` | Lists the configuration backups (file name, creation time, size, note) plus any restore already scheduled. |

There is deliberately **no backup delete tool**: retention is operator-only, on the
[Backups](settings-backups) page.

## Backups — restore {#backups--restore}

| Tool | What it does |
| --- | --- |
| `backup_restore` | Schedules a backup to replace the current configuration at the **next** application start. Nothing changes in the running app and the tool never restarts it; the configuration being replaced is snapshot automatically first, and the operator can cancel the pending restore from Settings until the restart. Refused while a recording is active. |

## Settings — manage {#settings--manage}

| Tool | What it does |
| --- | --- |
| `settings_read` | Reads the station's display and lifecycle preferences: date/time/number formats, decimal places, theme, close-to-tray and crash-report flags. |
| `localization_set` | Updates the display preferences (partial: omitted parameters stay). Display only — storage, driver I/O and recordings always use the invariant format. |
| `asset_list` | Lists the user assets (images, icons, colors) with ids, values and paths. |
| `asset_import` | Imports a PNG/JPG from a local file path into the app-owned asset library and returns the new asset id. The bytes are copied, so the source file may move afterwards. |
| `symbol_validate` | Validates inline symbol content (raw SVG or a v2 package) without persisting anything: a dry run of the exact import, returning errors, sanitizer warnings and a summary of what was recognized. The tool description carries the complete [portable symbol contract](ganter-symbols). |
| `symbol_import` | Imports inline symbol content as a new user-symbol asset and returns its id and `user:<guid>` reference. Always creates a new asset; a colliding name is auto-suffixed. |