tools (Section)

When To Use

Use tools to give an AI assistant an operation on the monitored host that is not a metric: list the running processes with their counters, read a log, reboot a server. A tool reuses what the connector already knows (the protocol, the credentials, the queries, the parsing) without creating any monitor.

The MetricsHub Agent exposes every tool as an MCP tool named <connectorId>_<toolName> (for example WindowsProcess_listProcesses), so an assistant connected to the agent discovers it with the connector.

A tool is:

• Sources and computes, exactly like a monitor job's: the same source types, the same computes, the same ${source::...} references.
• Parameters the assistant fills in, substituted with ${param::<name>} in the sources and computes.
• A result: the table of one of the sources, optionally with column names.

Syntax

tools:
  listProcesses:
    description: Lists the running processes with their CPU time and memory, optionally filtered by name.
    parameters:
      matchName:
        type: string
        description: Regular expression matching the process name, e.g. ^java (empty for all processes)
        default: ''
        # Only matched against the rows: any value on one line
        pattern: '.*'
    sources:
      processes:
        type: wmi
        namespace: root\CIMv2
        query: SELECT ProcessId, Name, WorkingSetSize, KernelModeTime FROM Win32_Process
        computes:
        - type: keepOnlyMatchingLines
          column: 2
          regExp: ${param::matchName}
    result:
      source: ${source::processes}
      columns: [ pid, name, workingSetBytes, kernelTime ]

Properties

Validation and Review

An argument comes from an AI assistant, and through it from whatever the assistant read: treat it as untrusted. Inserted as is into a command line, a value such as sshd; reboot would run a command of its own, and ' OR 1=1 -- would rewrite a query. MetricsHub validates every argument before the tool runs. Where the sources insert it, and what the command does with it, is checked when the connector is reviewed.

tools:
  serviceLogs:
    description: Returns the last lines of the journal of a systemd service. Use it when a service fails or restarts.
    parameters:
      service:
        # The default pattern takes unit names: sshd.service, getty@tty1.service
        description: The systemd unit, e.g. sshd.service
        required: true
      lines:
        type: integer
        description: How many lines to return, 1 to 9999
        default: 100
        # A bound: an unbounded count could return the whole journal
        pattern: '[1-9][0-9]{0,3}'
      priority:
        description: The lowest priority to return
        default: info
        enum: [ emerg, alert, crit, err, warning, notice, info, debug ]
    sources:
      journal:
        type: commandLine
        commandLine: journalctl --no-pager -n ${param::lines} -p ${param::priority} -u ${param::service}
    result:
      source: ${source::journal}

References and Order

Sources of a tool are keyed ${source::tools.<toolName>.sources.<sourceName>}. Inside the tool, a relative reference ${source::<sourceName>} resolves to the tool's own source, and the sources run in dependency order unless executionOrder says otherwise. A tool may also reference the connector's beforeAll sources with ${source::beforeAll.<name>}: they run before the tool, as before a monitor job.

A tool creates no monitor and its tables do not reach the monitor jobs: mapping is not allowed under a tool.

How the Assistant Calls It

The agent adds two parameters to every tool: hostname, a list of configured hosts to run it on (required), and poolSize, the number of hosts run concurrently. The result lists one entry per host, holding the columns declared in result and the rows of the result source, or an error.

{
  "hosts": [
    {
      "hostname": "win-01",
      "response": {
        "columns": [ "pid", "name", "workingSetBytes", "kernelTime" ],
        "rows": [ [ "4212", "java.exe", "734003200", "12.5" ] ]
      }
    }
  ]
}

Destructive Tools

A tool that changes the host (power control, a command, a configuration write) must declare destructive: true. The agent prefixes its description with DESTRUCTIVE:; its own MCP server and chat advertise it only when the agent runs with the JVM flag -Dmetricshub.mcp.tool.destructive.enabled=true, while MetricsHub Central receives every tool and applies its own approval policy.

tools:
  reboot:
    description: Reboots the server through iLO (graceful shutdown, then power on). Use only when the user explicitly asks for a reboot.
    destructive: true
    parameters:
      resetType:
        description: GracefulRestart (default) or ForceRestart
        default: GracefulRestart
        enum: [ GracefulRestart, ForceRestart ]
    sources:
      reset:
        type: http
        method: post
        path: /redfish/v1/Systems/1/Actions/ComputerSystem.Reset
        header: "Content-Type: application/json"
        body: '{"ResetType": "${param::resetType}"}'
        resultContent: http_status
    result:
      source: ${source::reset}
      columns: [ http_status ]

Recommended Pattern

• Name tools as verbs, without dots: listProcesses, readLog, reboot. A dotted name is refused when the connector loads, since the dot separates the segments of a source reference.
• Write the description for the assistant: what the tool returns, what the parameters mean, when not to use it.
• Give every parameter a default or required: true, and an example value in its description.
• Keep the default pattern for names and identifiers; use an enum or a numeric type where you can; give a wider pattern only where needed, with the escape of the field.
• Bound the numbers that size the work or the result (a line count, a time range) with a pattern such as [1-9][0-9]{0,3}: the type alone accepts any integer.
• Keep the result tabular: keep the commands plain, and filter, sort and select the lines with the source's keep and exclude and with computes (sort^[1], head^[2], tail^[3]) rather than with grep, sort, head or tail on the host; name the columns.
• Mark anything that writes as destructive: true, even a harmless-looking identify LED.

Common Mistakes

• Using ${param::...} in a mapping: tools have no mapping.
• Forgetting result: the tool has nothing to return.
• Leaving destructive unset on a tool that acts on the host.
• Widening a pattern (spaces, quotes, /) and inserting the parameter without the escape of its field, or outside the quotes the connector writes.
• Passing a parameter where it is not mere data: see What the Review Checks above.
• Returning raw command output without a parsing compute: the assistant gets a single-column table of lines.