How It Works

Three discovery tools

Loading all 264 operations as separate tools would add about 400 KB of schemas to every conversation. Instead, the server always provides three tools:

Tool	What it does
vsp360_list_operations	Lists the 35 API areas. With tag or query, lists the matching operations.
vsp360_describe_operation	Shows one operation's parameters, request body, response schema, required permissions and prerequisites.
vsp360_call_operation	Calls any operation by its operationId.

A typical exchange: Claude searches for the user's request, describes the best match to learn its parameters, then calls it.

For the areas you use most, VSP360_TOOLSETS adds direct tools: one per operation, each with a full input schema, so Claude can call them without searching first. See Configuration.

How search finds operations

A query goes through three steps. Only the first changes the order; the other two add advice.

1. BM25 ranking

Operations are ranked with BM25 over their ID, summary, area, path, description and a set of example questions. Six refinements make plain-language requests work:

• Words in the summary and ID count more than words in the description.
• camelCase is split, and light stemming is applied.
• Storage vocabulary is mapped to API terms: volume → ldev, LDAP → directories, ESXi → hypervisor.
• Verbs signal intent: "list" and "show" favour reads; "delete", "start" and "register" favour writes.
• List-style requests prefer collection endpoints over single-item ({id}) endpoints.
• Example questions bridge operator wording and API wording. For instance, "take a snapshot now outside the schedule" leads to protectionTriggerPolicy.

2. Confidence

Each result set is rated HIGH, MEDIUM or LOW, based on how far the top result leads the next and how much of the request it matches. The rating comes with advice: call the top result, check its description first, or compare the top two or three. When a weak result looks like a performance or topology question, the response points to Analytics.

With HIGH confidence, the top result's parameters are listed too: their types, allowed values and required body fields. Claude can then usually call the operation straight away, without a vsp360_describe_operation turn. This is skipped when the top result is blocked by the current settings, such as a write in read-only mode, and for analyticsRunQuery, which needs describe's MQL reference.

3. Learned hint (optional)

With VSP360_DECISION_HINT=true, a small model trained on logged searches suggests the next step: call the top operation, compare the top few, use Analytics, or search again. It never changes the ranking. See Development.

Analytics (MQL)

The spec documents the Analytics query endpoint, analyticsRunQuery, but not what it can query. Describing that operation therefore adds an MQL reference: usage notes, the attributes and relations of the most-used resource types (raidStorage, raidPool, raidLdev, raidPort, raidHG, raidLU, raidPortWWN, raidPair, plus host, fabric and VMware types), and the names of 38 more. Describing it with resourceType, for example raidPool, returns one type's full attribute list.

This is how performance and capacity questions get answered: "port IOPS and latency over the last hour", or "which volumes are busiest".

Requests and responses

• Sign-in: an OAuth2 client-credentials token, reused until shortly before it expires and refreshed automatically after a 401. The server signs in when it makes its first request, not at startup.
• Pagination: limit and offset (up to 100 per page), or all_pages: true to fetch every page, capped by max_pages (default 20). When the first page's Link header names both next and last, the remaining pages are fetched four at a time; otherwise next links are followed one by one. Links always go back to VSP360_URL, so the token never goes to another host.
• Downloads: binary responses (diagnostic bundles, CSR ZIPs, billing reports) are streamed to VSP360_DOWNLOAD_DIR, and the file path is returned. Any call can pass save_to to write its response to a file instead.
• Uploads: multipart operations take local file paths, streamed from disk, so multi-GB upgrade packages work. See Safety and Security.
• Compact responses: JSON responses and describe output aren't indented, which takes about a quarter fewer tokens for the same content. Files written with save_to stay indented.
• Large responses are truncated at VSP360_MAX_RESPONSE_CHARS, with a note on how to narrow the request.
• Fast startup: the build keeps a pre-parsed copy of the bundled spec, so the server starts in about a quarter of a second instead of parsing 2 MB of YAML each time.

A newer VSP 360 release

No code is generated from the spec. Point VSP360_SPEC at the new OpenAPI file, YAML or JSON, and restart. A replaced spec is parsed afresh, which adds about a quarter of a second to startup; JSON loads fastest. If the new release adds POST operations that only read data, they need adding to READ_ONLY_POSTS in src/spec.ts to be allowed in read-only mode.