Tools

Keysight MCP Server for Instrument Control exposes eighteen tools to the AI client via the MCP protocol. The AI client calls these tools on behalf of the engineer; the engineer never interacts with the tools directly.

Tools are organised into six functional groups: Discovery, IDF and Command Resolution, Execution, Instrument Utilities, File Operations, Procedures, and Update Management.

Any tool that identifies an instrument (for discovery, execution, file transfer, or screenshot capture) accepts a bare IP address or hostname in place of a full VISA resource string. The server resolves it automatically and caches the result for 5 minutes so it doesn't need to re-resolve on every call.

Discovery

Tool Description

discover_instruments Scans all VISA buses and returns connected instruments with their model, resource string, and class. The filter accepts a keyword, a bare IP address or hostname, or a full VISA resource string. Instruments marked as favourites in Connection Expert are returned first. If Connection Expert doesn't recognize a direct address, the server connects to the instrument directly instead, using a few standard network methods automatically, and lets you know with a warning that it found the instrument this way rather than through Connection Expert. This tool is called once at the start of each session. The results are retained for the entire session and are not re-fetched on follow-up requests unless explicitly instructed. The server also checks for a newer version at this time and includes a brief notice in the response if one is available.

Tool	Description
`discover_instruments`	Scans all VISA buses and returns connected instruments with their model, resource string, and class. The filter accepts a keyword, a bare IP address or hostname, or a full VISA resource string. Instruments marked as favourites in Connection Expert are returned first. If Connection Expert doesn't recognize a direct address, the server connects to the instrument directly instead, using a few standard network methods automatically, and lets you know with a warning that it found the instrument this way rather than through Connection Expert. This tool is called once at the start of each session. The results are retained for the entire session and are not re-fetched on follow-up requests unless explicitly instructed. The server also checks for a newer version at this time and includes a brief notice in the response if one is available.

IDF and Command Resolution

Tool Description

get_instrument_info Returns a compact IDF summary for a specific instrument: model, command count, and available subsystems. The AI calls this tool when it needs to understand the breadth of an instrument's capabilities before resolving a specific command.

search_instrument_capabilities Performs a free-text keyword search across the instrument's full IDF command set and returns up to ten matching commands with their mnemonics and descriptions. This tool is used when resolve_commands returns low confidence for an intent and a broader exploration of available commands is needed.

Tool	Description
`get_instrument_info`	Returns a compact IDF summary for a specific instrument: model, command count, and available subsystems. The AI calls this tool when it needs to understand the breadth of an instrument's capabilities before resolving a specific command.
`search_instrument_capabilities`	Performs a free-text keyword search across the instrument's full IDF command set and returns up to ten matching commands with their mnemonics and descriptions. This tool is used when `resolve_commands` returns low confidence for an intent and a broader exploration of available commands is needed.
`resolve_commands`	Maps a batch of structured intents (each an operation, subsystem, and parameters) to their best matching SCPI commands in the IDF, in a single call. This is the primary command resolution tool; resolving a batch avoids repeated back-and-forth calls for multi-step requests. For each intent, it runs a deterministic scoring pipeline and returns one of three confidence levels: High confidence: A single clear winner was found. The AI proceeds to the preview step. Medium confidence: Two or three close candidates were found. The AI presents them in a ranked list and asks the engineer to confirm the recommendation or select an alternative. Low confidence: No strong match was found for that intent. The AI reports this and falls back to `search_instrument_capabilities`.

resolve_commands

Maps a batch of structured intents (each an operation, subsystem, and parameters) to their best matching SCPI commands in the IDF, in a single call. This is the primary command resolution tool; resolving a batch avoids repeated back-and-forth calls for multi-step requests. For each intent, it runs a deterministic scoring pipeline and returns one of three confidence levels:

High confidence: A single clear winner was found. The AI proceeds to the preview step.
Medium confidence: Two or three close candidates were found. The AI presents them in a ranked list and asks the engineer to confirm the recommendation or select an alternative.
Low confidence: No strong match was found for that intent. The AI reports this and falls back to search_instrument_capabilities.

Execution

Tool Description

preview_commands Validates a command sequence against the instrument's IDF and generates a plain-language summary of what each command will do. The preview is presented to the engineer before any execution takes place. This tool must always be called before execute_commands.

execute_commands Sends the approved SCPI command sequence to the instrument through VISA. Opens an exclusive VISA session for the duration of execution so no other process can interrupt. Returns timestamped results for each command. The AI translates responses into plain language with the correct units. The engineer must approve the preview before this tool can run. By default, the server checks for errors after each command and stops if one fails. Set -scpi-poll-instrument-errors=false to check errors only once, at the end. With this setting, the sequence keeps running even if a command fails, and you get the full error list when it's done. Use get_all_errors to check the queue manually at any other time.

Tool	Description
`preview_commands`	Validates a command sequence against the instrument's IDF and generates a plain-language summary of what each command will do. The preview is presented to the engineer before any execution takes place. This tool must always be called before `execute_commands`.
`execute_commands`	Sends the approved SCPI command sequence to the instrument through VISA. Opens an exclusive VISA session for the duration of execution so no other process can interrupt. Returns timestamped results for each command. The AI translates responses into plain language with the correct units. The engineer must approve the preview before this tool can run. By default, the server checks for errors after each command and stops if one fails. Set `-scpi-poll-instrument-errors=false` to check errors only once, at the end. With this setting, the sequence keeps running even if a command fails, and you get the full error list when it's done. Use `get_all_errors` to check the queue manually at any other time.

Instrument Utilities

To reset an instrument to its factory default state, use execute_commands with the SCPI command *RST directly. A dedicated reset tool is not available.

Tool Description

get_all_errors Checks and clears the instrument's error queue, and returns any pending error messages. The server translates error codes into plain language with suggested fixes. execute_commands runs this check automatically, either after each command or once at the end, depending on the -scpi-poll-instrument-errors setting. Use get_all_errors on demand at any other time.

capture_screenshot Captures the instrument display and saves it to a local file. The server identifies the instrument family from its identification string and dispatches the correct SCPI capture sequence automatically. Supported instrument families include InfiniiVision and Infiniium oscilloscopes, PXA/MXA/EXA/CXA/UXA signal analyzers, PNA/ENA network analyzers, MXG/EXG/CXG/PSG/UXG/VXG signal generators, and FieldFox handhelds. If no local path is specified, the file is saved to the system temporary directory with a timestamped filename.

Tool	Description
`get_all_errors`	Checks and clears the instrument's error queue, and returns any pending error messages. The server translates error codes into plain language with suggested fixes. `execute_commands` runs this check automatically, either after each command or once at the end, depending on the `-scpi-poll-instrument-errors` setting. Use `get_all_errors` on demand at any other time.
`capture_screenshot`	Captures the instrument display and saves it to a local file. The server identifies the instrument family from its identification string and dispatches the correct SCPI capture sequence automatically. Supported instrument families include InfiniiVision and Infiniium oscilloscopes, PXA/MXA/EXA/CXA/UXA signal analyzers, PNA/ENA network analyzers, MXG/EXG/CXG/PSG/UXG/VXG signal generators, and FieldFox handhelds. If no local path is specified, the file is saved to the system temporary directory with a timestamped filename.

File Operations

The file operation tools transfer and manage files on instrument storage. The server selects the transfer method automatically based on instrument family: signal generators use SCPI block transfer; all other families try SCP first, then FTP, then SCPI. The method can be overridden if needed.

The server accepts a startup argument -file-transfer-local-base-dir. When you set it to a non-empty path, the server constrains local file writes to that directory tree. In particular, omitting local_path for capture_screenshot saves captures into this directory instead of the OS temporary directory. The server rejects any file path that escapes the configured tree; for requests to other destinations, it saves the file to the configured directory first and then copies it to the requested destination if permitted. See Security for more information on path restrictions.

Tool	Description
`list_files`	Lists files and directories on the instrument's storage. Returns the name, type, size, and modification timestamp for each entry. Results are capped at 200 entries. If the listing is truncated, use the path or file type filter to narrow the results.
`upload_file`	Uploads a local file to the instrument's storage. The destination path on the instrument is instrument-specific: signal generators commonly use paths such as `NVWFM:` or `INT:`; oscilloscopes and analyzers use standard filesystem paths.
`download_file`	Downloads a file from the instrument's storage to a local path. Parent directories on the local machine are created automatically if they do not exist.
`copy_file`	Copies a file on the instrument without transferring it to the local machine. Uses SCPI `MMEM:COPY` where the instrument supports it, falling back to SFTP or FTP.
`move_file`	Moves or renames a file on the instrument, including across directories. Uses SCPI `MMEM:MOVE` where the instrument supports it, falling back to SFTP or FTP rename.

Procedures

Tool	Description
`list_procedures`	Returns a list of all available procedures. Each entry shows the procedure ID, name, instrument class, and a brief description. This tool is used as a fallback when `resolve_procedure` cannot match the engineer's intent, allowing the AI to present available options.
`resolve_procedure`	Matches a multi-step measurement intent to a predefined procedure. Takes the instrument class, a keyword describing the measurement, and any parameter overrides supplied by the engineer. Returns an expanded procedure with all steps resolved and parameters substituted, ready to be converted into a command array before the preview step.

Update Management

These tools allow the engineer to check for, download, and install updates to the Keysight MCP Server for Instrument Control without leaving their AI client. Each step requires explicit engineer approval before proceeding. In addition to this on-demand check, the server automatically checks for an update once per session when discover_instruments first runs, and surfaces a brief notice if a newer version is available.

Tool	Description
`check_updates`	Checks whether a newer version of the Keysight MCP Server for Instrument Control is available. Returns the current installed version, the latest available version, and release notes for the update. If an update is available, the details are presented to the engineer before any download is initiated.
`download_update`	Downloads the installer for the available update and verifies its integrity. The engineer must explicitly approve this step before the download begins. After the download completes, the engineer must give a separate approval before the installer is launched.
`install_update`	Launches the downloaded installer as a separate process. The engineer must explicitly approve this step. The MCP server continues running during installation. Once the installer wizard completes, the server should be restarted to activate the new version.