# Tool Reference

> Purpose, parameters, and example input/output for all five VisualOne MCP tools.

The VisualOne MCP exposes five tools. This page documents each one: its purpose, parameters, and example input/output. All five are **read-only**.

| Tool | Category |
| --- | --- |
| `visualone_discover_reports` | Discovery |
| `visualone_get_reports` | Data |
| `visualone_list_units` | Discovery |
| `visualone_get_session` | Session |
| `visualone_health_check` | Diagnostics |

## visualone_discover_reports

Search the VisualOne report registry to find which report — and which stored procedure — to use for a request. **Call this first** whenever you want to see, run, or analyze a report, then use the returned `proc_name` to make the follow-up `visualone_get_reports` call.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Natural-language description of the report or data you want. |
| `limit` | integer | No | Max results. Default 5, min 1, max 20. |
| `report_id` | string | No | Look up one specific report by its exact reportId instead of searching. |

```
{ "tool": "visualone_discover_reports",
  "arguments": { "query": "storage capacity plan", "limit": 5 } }
```

Reading the result: pick the report whose title / context matches, use its `proc_name` for the next call, and check each parameter’s source (`context` params are automatic; `navigation` params you must supply; `user_input` params are optional filters). When a report lists several routes, each `proc_name` is a different cut of the report (e.g. grouped by data center vs. by tier).

## visualone_get_reports

Execute a VisualOne report and return the data. Use `visualone_discover_reports` first to obtain the correct `proc_name`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | Yes | Operation to perform. Use `run_get` to execute a stored-procedure report. |
| `proc_name` | string | Yes (for run_get) | Stored procedure to run, from `visualone_discover_reports`. |
| `client_id` | string | No | Resolved from session automatically. Super users may pass it to query another client. |
| `period_id` | string | No | Auto-resolved to the latest period for the report context. Pass only to override. |
| `response_format` | string | No | `markdown` (default) or `json`. |
| drilldown identifiers | string | depends | Supply when the report declares them as `navigation` parameters (see below). |

### Drilldown identifier parameters

Provide these only when the chosen report requires them. Use `visualone_list_units` to resolve exact names.

| Parameter | Required for | Resolve via unit_type |
| --- | --- | --- |
| `device_name` | Storage Device drilldowns | `devices` |
| `vcenter_name` | Virtual drilldowns | `vcenters` |
| `cluster_name` | Cluster / host / VM drilldowns | `clusters` |
| `esx_host_name` | VM & ESX host drilldowns | `esx_hosts` |
| `vm_name` | VM summary drilldowns | `vms` |
| `datastore_name` | Datastore drilldowns | `datastores` |
| `data_center_name` | vCenter data-center summaries | `vcenters` |
| `host_name` | Host / Hosts drilldowns | `storage_hosts` |
| `switch_name` | Switch drilldowns | `switches` |
| `instance_name` | Database Server drilldowns | `database_instances` |
| `node_name` | Kubernetes Node drilldowns | `kubernetes_nodes` |

### Examples

```
// Enterprise report (no drilldown)
{ "tool": "visualone_get_reports",
  "arguments": { "action": "run_get", "proc_name": "enterprise_summary_proc" } }

// Drilldown report (JSON output)
{ "tool": "visualone_get_reports",
  "arguments": {
    "action": "run_get",
    "proc_name": "device_capacity_plan_proc",
    "device_name": "ARRAY-DAL-01",
    "response_format": "json"
  } }
```

> **Note:** `client_id` and `period_id` are resolved from your session and the report’s context — add them only to override the defaults. Report output is your live environment data; anonymize before publishing examples anywhere public.

The tool also advertises two helper actions — `device_summary` (a device inventory summary) and `get_tag_mapping` (a tag key/value map for a client). `run_get` is the primary, registry-driven action used for all catalog reports; confirm the helper actions in your deployment before relying on them.

## visualone_list_units

Look up the exact entity identifiers needed to run drilldown reports. Call this **before** `visualone_get_reports` whenever a report requires a `navigation` parameter such as `device_name`, `vcenter_name`, `cluster_name`, `esx_host_name`, `vm_name`, `switch_name`, or `instance_name`. It returns only the identifier fields needed for the follow-up call, plus a `total_matching` count — not full report data.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `unit_type` | string | Yes | The entity type to look up (see table below). |
| `search` | string | No | Case-insensitive substring match on the primary name. |
| `vcenter_name` | string | No | Filter. Applies to clusters, esx_hosts, vms, datastores. |
| `cluster_name` | string | No | Filter. Applies to esx_hosts, vms. |
| `esx_host_name` | string | No | Filter. Applies to vms. |
| `device_name` | string | No | Filter. Applies to storage_hosts. |
| `limit` | integer | No | Max rows. Default 100, min 1, max 500. |
| `response_format` | string | No | `markdown` (default) or `json`. |

### Unit types

| unit_type | Returns |
| --- | --- |
| `devices` | Storage arrays |
| `vcenters` | VMware vCenters |
| `clusters` | vSphere clusters |
| `esx_hosts` | ESX hypervisor hosts |
| `vms` | Virtual machines |
| `datastores` | vSphere datastores |
| `switches` | SAN switches |
| `storage_hosts` | Hosts connected to storage |
| `database_instances` | SQL Server instances |

```
// Resolve a VM by partial name
{ "tool": "visualone_list_units",
  "arguments": { "unit_type": "vms", "search": "sql", "limit": 25 } }

// Progressive discovery: narrow as you descend
{ "unit_type": "vcenters", "search": "dallas" }
{ "unit_type": "clusters", "vcenter_name": "dal-vcenter-01.corp" }
{ "unit_type": "vms", "vcenter_name": "dal-vcenter-01.corp", "cluster_name": "PROD-CL01" }
```

If `total_matching` exceeds the rows returned, add filters or a more specific `search` term rather than raising `limit`.

## visualone_get_session

Check the current authentication session. Returns the active user profile, client ID, role, and token expiry. Use it to confirm you are authenticated, to retrieve your `client_id`, or to check your `role` before super-user actions. Takes no parameters.

```
{ "tool": "visualone_get_session", "arguments": {} }

// Example response
{
  "status": "authenticated",
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "clientId": 1234,
  "role": "standard_user"
}
```

## visualone_health_check

Check whether the VisualOne Arbiter API is reachable and responding. Useful as a first step when troubleshooting. Accepts an optional `response_format` (`markdown` or `json`).

```
{ "tool": "visualone_health_check", "arguments": {} }

// Example response
# VisualOne Health Check

service:          arbiter
version:          6.0.0
mongoConnection:  OK
```

A response with `mongoConnection: OK` means the API and its datastore are healthy. Anything else indicates a backend issue — see [Troubleshooting & FAQ](https://visualoneintelligence.com/docs/voi-mcp-troubleshooting/).

---

Source: https://visualoneintelligence.com/docs/voi-mcp-tool-reference/