Assistant Tools
Assistant and MCP tools let AI models inspect HSYCO context, follow HSYCO task procedures, read documentation, query runtime state, work with uploaded files, create downloadable files, and perform selected HSYCO operations.
Tools are grouped into bundles. Where the tools are used determines which bundles are available:
| Used in | Available bundles |
|---|---|
| Manager Assistant | Bundles selected for a Manager-enabled profile, excluding Client Page |
| Client Assistant | Bundles selected for a Client-enabled profile, limited to Client Page, Session Files, Catalog, general Docs, and permitted read-only Runtime tools |
| AIGEN I/O Server | Bundles selected for an I/O Server-enabled profile, excluding browser editors, Client Page, and Session Files |
| MCP Server | Approval tools, plus the shared bundles selected by the MCP client with toolBundles; all shared bundles are available by default after Manager approval |
Select bundles in the AI profile. Each surface can use only the tools available to it, even if the profile enables more bundles. Manager Settings prevents selecting bundles that none of the profile's enabled surfaces can use.
If you selected bundles before the names changed, update the profile to use the IDs below. An empty selection allows every tool available to the profile's enabled surfaces.
| Bundle | Manager | I/O Server | Client | Purpose |
|---|---|---|---|---|
runtime_status | Yes | Yes | Yes | Host and device status. |
runtime_config | Yes | Yes | No | Configuration and server definitions. |
runtime_sessions | Yes | Yes | No | Active user sessions. |
runtime_state | Yes | Yes | Partial | Live variables, I/O, UI, datasources, and indexed search. |
runtime_history | Yes | Yes | Yes | Timelines, logs, and dataloggers. |
runtime_media | Yes | Yes | Yes | Images and cameras. |
runtime_execution | Yes | Yes | No | Sandboxed JavaScript analysis. |
runtime_control | Yes | Yes | No | Set live variables, I/O, and UI values. |
runtime_events | Yes | Yes | No | EVENTS errors. |
runtime_files | Yes | Yes | No | Saved text files. |
runtime_source | Yes | Yes | No | EVENTS and Java source. |
docs | Yes | Yes | Partial | Documentation and references. |
catalog | Yes | Yes | Yes | Catalog lookup. |
editor_project | Yes | No | No | Live Project Editor. |
editor_code | Yes | No | No | Live Code Editor. |
session_files | Yes | No | Yes | Attachments and downloadable files. |
client_page | No | No | Yes | Connected Client page context. |
skills | Yes | No | No | Installed skills and their saved scripts. |
For the Client Assistant, “Partial” means general documentation and selected read-only Runtime State tools.
MCP clients always have access to the approval tools. Protected HSYCO tools request Manager approval automatically before they run. See MCP Server for the approval flow.
Earlier Assistant Results
The Assistant can reuse earlier results from the same conversation, including images and files. In Manager, it can analyze an earlier result or save it as a downloadable file when Session Files is enabled. MCP clients cannot access Assistant results.
Available to the Manager Assistant and the Client Assistant. It is not part of a bundle.
| Tool | Description |
|---|---|
hsyco_tool_result_read | Reads part of an earlier result from the same Assistant session, or recovers one of its images or files. It cannot read other sessions. |
MCP Approval
MCP Server only.
| Tool | Description |
|---|---|
hsyco_approval_request | Creates a Manager approval popup for the current MCP session. |
hsyco_approval_status | Gets approval status for the current MCP session. |
Runtime Events
Available to the Manager Assistant and MCP Server after Manager approval. The AIGEN I/O Server receives only hsyco_events_errors; the Client Assistant receives no event tools.
| Tool | Description |
|---|---|
hsyco_events_errors | Fetches current event compiler and runtime errors. |
Runtime Files and Source Code
Saved-file tools read files on disk without opening Code Editor and intentionally exclude unsaved changes. Source tools include live Code Editor changes only for EVENTS and Java source files.
| Tool | Description |
|---|---|
hsyco_file_read | Reads a page from one saved text file without using Code Editor. |
hsyco_file_search | Searches one saved file or a bounded set of saved allowlisted text files on disk, without using Code Editor. |
hsyco_source_list | Lists EVENTS and Java source files, including open files with unsaved changes. |
hsyco_source_read | Reads one exact EVENTS or Java source path; open unsaved content overrides the saved file. |
hsyco_source_check | Checks Java source files for compile errors without writing class files; open unsaved content overrides the saved file. Requires the JDK compiler. |
hsyco_java_api | Looks up Java classes, packages and methods on the classpath HSYCO compiles against, including the libraries in hsyco.jar. Requires the JDK compiler. |
Saved-file reads can continue across pages or long lines. Searches across files have size limits. Configuration files are excluded unless both runtime_files and runtime_config are enabled.
Docs
General documentation search/list/open tools are also available to the Client Assistant and AIGEN I/O Server. Object, code, and icon reference tools remain available only where the selected surface policy and profile permit them.
| Tool | Description |
|---|---|
hsyco_docs_search | Searches HSYCO documentation and available object references. |
hsyco_docs_list | Lists general documentation files from the live HSYCO documentation store. |
hsyco_docs_open | Opens Markdown content from one general documentation file. |
hsyco_object_reference | Gets an overview of one UI object type and its attributes. |
hsyco_object_attrs_open | Opens documentation for specific UI object attributes. |
hsyco_code_reference | Lists code reference entries for EVENTS, JavaScript, or Java. |
hsyco_code_reference_open | Opens full code reference documentation for specific entries. |
hsyco_icons_search | Searches MDI icon metadata for custom project icons. |
Handbook
The handbook is a set of HSYCO task procedures built into HSYCO. The Assistant follows it when it builds, configures, operates, diagnoses or changes the installation, and uses the Docs tools for conceptual questions and documentation requests.
The handbook tools are available to the Manager Assistant, the Client Assistant, the AIGEN I/O Server when tools are enabled, and MCP clients. They are not a bundle and are not selected in the AI profile: each session receives only the procedures that its surface and enabled bundles can carry out.
| Tool | Description |
|---|---|
hsyco_handbook_search | Finds the procedures for a task, best first, optionally with the text of the best one. |
hsyco_handbook_open | Opens procedures by ID or path, or an example file that a procedure links. |
hsyco_handbook_list | Lists the available procedures, optionally filtered by category or text. |
The handbook is private to the Assistant: users don't open it, and the Assistant puts the steps, values and syntax they need in its answers.
Project Editor
The Project Editor tools are available to the Manager Assistant and to the MCP Server after Manager approval.
| Tool | Description |
|---|---|
hsyco_project_list | Lists available UI projects. |
hsyco_project_read | Reads a project in Project Editor, including unsaved state, page summaries and the page the project opens on. |
hsyco_project_get_page | Reads one Project Editor page, or the objects of one container on it, including unsaved edits and the current selection. |
hsyco_project_query_objects | Finds objects with a CSS selector on one page, the selected page or every page. |
hsyco_project_capture_page | Captures a page, or the area of one object, as an image of how Project Editor shows it, to check the layout. An object can be drawn at twice its size. |
hsyco_project_apply_edits | Applies unsaved Project Editor edits in the active Manager browser. |
hsyco_pe_open_project | Opens one project in Project Editor and can focus a page or object path. |
hsyco_pe_close_project | Closes the active project in Project Editor. A project with unsaved edits stays open. |
The read, capture and edit tools open the project they name. The Assistant never discards unsaved changes in Project Editor: when another project has them, it asks the user to save or discard them first.
Code Editor
Available to the Manager Assistant and to the MCP Server after Manager approval. This bundle controls Manager Code Editor tabs and is separate from runtime_events.
| Tool | Description |
|---|---|
hsyco_ce_read_file | Opens or focuses an allowlisted file and reads its live Code Editor buffer, including an already-open unsaved File Manager New File buffer. Returns a revision guard. |
hsyco_ce_search_file | Searches one live Code Editor buffer and returns the revision guard required for editing. |
hsyco_ce_apply_edits | Applies ordered exact-match edits to the revision-matched open buffer without creating or saving a file. |
hsyco_ce_open_file | Opens one live HSYCO file in Manager Code Editor. |
hsyco_ce_close_file | Closes one open file tab in Manager Code Editor. |
Call hsyco_ce_read_file or hsyco_ce_search_file immediately before hsyco_ce_apply_edits and pass the returned revision. Edits use {oldString, newString, replaceAll?}. An empty oldString is accepted only as the sole non-replaceAll edit against an empty revision-matched buffer, which supports initializing an unsaved New File tab without introducing a separate patch language.
Runtime Read
Available according to the surface policy and selected profile. The Client Assistant receives only user-facing read-only queries such as status, variables, I/O, devices, indexed state, datasource, timelines, logs, images, dataloggers, and cameras; it does not receive configuration, active-session, Manager UI, or code-execution tools.
| Tool | Description |
|---|---|
hsyco_status_summary | Reads the live HSYCO host and system status summary. |
hsyco_config_get | Reads HSYCO configuration entries from hsyco.ini. |
hsyco_config_ioservers | Lists configured I/O servers, including connection parameters and optional installer descriptions. |
hsyco_config_cameras | Lists configured cameras, including URLs, recording and PTZ settings, and optional installer descriptions. |
hsyco_config_commports | Lists configured communication ports, including line parameters, TCP addresses, and optional installer descriptions. |
hsyco_code_run | Runs short JavaScript for data analysis. In Assistant sessions, it can use an earlier result; attachments and downloadable output require Session Files. |
hsyco_vars_query | Queries live HSYCO runtime variables. |
hsyco_io_query | Queries live HSYCO I/O state. |
hsyco_ui_query | Queries live HSYCO UI state for one project and optional session. |
hsyco_devices_query | Queries live HSYCO device state from the Status Browser snapshot. |
hsyco_sessions_list | Lists active HSYCO user sessions. |
hsyco_datasource_query | Queries a live HSYCO datasource. |
hsyco_state_search | Searches live HSYCO state across the enabled bundles. |
hsyco_timeline_io | Queries I/O datapoint value-change history from Timeline. |
hsyco_timeline_command | Queries command history from Timeline. |
hsyco_timeline_var | Queries variable value-change history from Timeline. |
hsyco_timeline_stats | Gets Timeline database statistics. |
hsyco_timeline_all | Queries all Timeline records across I/O, commands, and variables. |
hsyco_log_read | Reads live HSYCO log entries. |
hsyco_image_read | Reads an image file from the local HSYCO filesystem and returns it as an artifact. |
hsyco_datalogger_get | Lists HSYCO DataLogger definitions, including optional installer descriptions. |
hsyco_datalogger_query | Queries live DataLogger data for one datalogger. |
hsyco_camera_get | Reads live HSYCO camera status. |
hsyco_camera_get_motions | Queries camera motion events for one camera. |
hsyco_camera_get_frame | Retrieves a current or recorded camera frame. |
Session Files
Available to the Manager Assistant, Client Assistant, and MCP Server after Manager approval. The AIGEN I/O Server does not use the Assistant session file cache.
| Tool | Description |
|---|---|
hsyco_artifact_create | Creates one downloadable file from assistant-generated text or base64 data. |
hsyco_artifact_create_many | Creates multiple downloadable files from assistant-generated text or base64 data. |
hsyco_attachment_list | Lists files uploaded by the user for the current assistant session. |
hsyco_attachment_read | Reads uploaded text and images, and returns supported PDF or Office documents as native file artifacts. Unsupported binary formats return metadata only. |
Client Page
Available to the Client Assistant, and to the MCP Server after Manager approval when a matching client page is connected.
| Tool | Description |
|---|---|
hsyco_client_get_context | Gets the limited live context exposed by the current client page. |
hsyco_client_get_object_context | Gets live context for one exposed client item handle. |
hsyco_client_get_table_data | Gets semantic table status and paginated rows. It defaults to filtered rows in the current sort order, visible columns, and displayed values. Row value arrays align with the returned columns; options expose viewport or unfiltered rows, source order, hidden columns, raw values, and selected-only rows. |
hsyco_client_get_datasource_data | Gets paginated raw rows and columns from a datasource cache loaded in the current client page. Datasource cache data is distinct from a rendered table view. |
hsyco_client_get_datalogger_context | Gets live context for one exposed datalogger or timeline handle. |
Catalog
Available to the Manager Assistant, Client Assistant, AIGEN I/O Server when tools are enabled, and MCP Server after Manager approval.
| Tool | Description |
|---|---|
hsyco_catalog_get | Reads live HSYCO catalog devices and locations. |
hsyco_catalog_search | Searches live HSYCO catalog devices and metadata. |
Runtime Control
Available to the Manager Assistant, AIGEN I/O Server when tools are enabled, and MCP Server after Manager approval. These tools change live HSYCO runtime state immediately.
| Tool | Description |
|---|---|
hsyco_vars_set | Sets or deletes one live HSYCO runtime variable. |
hsyco_io_set | Sets one or more live HSYCO I/O datapoint values. |
hsyco_ui_set | Sets one live HSYCO UI attribute globally or for one session. |
Skills
Manager Assistant only, when the skills bundle is enabled. Skills are installed in the aigen/skills folder of the HSYCO folder or of a plugin.
| Tool | Description |
|---|---|
hsyco_skill_read | Reads the SKILL.md instructions of an installed skill, or one of its text resources. |
hsyco_skill_run | Runs a saved JavaScript script of an installed skill. Also requires the runtime_execution bundle. A script that calls server callbacks also requires the runtime_control bundle and an authenticated Manager session. |
Dynamic tool loading
On supported models, HSYCO sends the complete authorized catalog to the provider while initially placing only a small frequently used set in the model context. OpenAI GPT-5.4 and later use native tool search with grouped namespaces; supported Claude 4.5+ and Claude 5 models use Anthropic's native BM25 tool search. The model can discover a deferred tool when the request needs it without changing the surface permissions.
The always-visible business tools are status summary, indexed state search, handbook search and open, and saved-file read and search where the surface allows them. Client Assistant also keeps current Client context visible. Providers without a compatible native tool-search protocol receive the complete surface-authorized catalog.