Tools
Keysight MCP Server for Instrument Control exposes seventeen 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, 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.
Each tool carries a few simple tags that describe what it does: whether it changes anything, whether you can run it twice safely, and whether it reaches outside your computer. Your AI client reads these tags and decides how to handle the call. For example, it might ask you to confirm before running a tool tagged Destructive, but run a Read-only tool without asking. Keysight's MCP server only attaches the tags; it doesn't enforce anything based on them, and your client decides whether to pay attention to them at all.
- Read-only: the tool only looks or reports. It changes nothing.
- Destructive: the tool can make a change you can't easily undo.
- Idempotent: run it twice with the same input, and you get the same result as running it once. Nothing extra happens.
- Open World: the tool reaches outside your computer, to a real instrument or the internet, instead of working only with information already stored locally.
Discovery
| Tool | Description | Annotations |
|---|---|---|
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. For non-Keysight Technologies instruments (or legacy Agilent/HP), it's flagged with a short per-instrument note, and one summary warning is added to the response — including when the instrument was found via a direct probe because Connection Expert wasn't available. | Read-only, Idempotent, Open World |
IDF and Command Resolution
| Tool | Description | Annotations |
|---|---|---|
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. If no IDF exists for the model at all (commonly a non-Keysight Technologies or virtual/emulated instrument), this returns a warning instead of failing, directing the engineer to supply SCPI directly for validation with preview_commands. |
Read-only, Idempotent, Open World |
search_instrument_capabilities
|
Searches the instrument's command set by free-text keyword and returns matching commands, ranked by relevance. This tool is used when resolve_commands returns low confidence for an intent and a broader exploration of available commands is needed. It can also find matching multi-step procedures. If you give it a keyword, it returns the complete procedure with all its steps and parameters, ready to use. If you leave out the keyword, it lists every procedure available for that instrument type instead, up to 50 at a time. This list only shows the procedure names, not the full steps. To see the full steps for one of them, search again using that procedure's name. If no IDF exists for the model at all (commonly a non-Keysight Technologies or virtual/emulated instrument), this returns a warning instead of failing, directing the engineer to supply SCPI directly for validation with preview_commands. Procedure search is unaffected and still returns matches. |
Read-only, Idempotent |
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:
If no IDF exists for the model at all (commonly a non-Keysight Technologies or virtual/emulated instrument), this returns a warning instead of failing, directing the engineer to supply SCPI directly for validation with |
Read-only, Idempotent, Open World |
describe_commands
|
Reverse lookup: given a model and one or more existing SCPI command headers (short or long form), returns each command's real IDF description, parameters, and send form, without previewing or executing anything. Use this to recover a command's actual meaning instead of guessing from mnemonic text, most commonly as the first step in translating a SCPI sequence to a different instrument model: look it up against the source model here, then find the equivalent on the target model with resolve_commands, and validate it with preview_commands before presenting it to the engineer. Works from a model number alone; no connected instrument or VISA session is required for either the source or the target model. Shares its matching logic with preview_commands, so both tools apply the same lookup rules. If no IDF exists for the model at all (commonly a non-Keysight Technologies or virtual/emulated instrument), this returns a warning instead of failing, directing the engineer to supply SCPI directly for validation with preview_commands. |
Read-only, Idempotent, Open World |
Execution
| Tool | Description | Annotations |
|---|---|---|
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. Accepts SCPI in either short or long form, including sequences supplied directly by the engineer rather than generated by Assure. Resolving and previewing a sequence does not require the instrument to be connected or powered on. For an instrument with no matching IDF, it validates any commands it recognizes as universal (such as *IDN? and *OPC?) and marks the remaining commands as unchecked instead of blocking the preview. |
Read-only, Idempotent |
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. Unlike preview_commands, this tool requires the instrument to be connected and reachable. If it isn't, the tool reports a clear connection timeout rather than retrying silently, and the AI suggests checks such as power state, LAN status, cabling, and network path before trying again. |
Destructive, Open World |
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 | Annotations |
|---|---|---|
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. |
Destructive, Idempotent, Open World |
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. | Idempotent, Open World |
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 | Annotations |
|---|---|---|
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. | Read-only, Idempotent, Open World |
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. |
Destructive, Idempotent, Open World |
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. | Idempotent, Open World |
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. |
Idempotent, Open World |
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. |
Destructive, Open World |
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 | Annotations |
|---|---|---|
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. | Read-only, Idempotent, Open World |
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. | Idempotent, Open World |
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. | Destructive |