Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VergeOS MCP Server list all running VMs in the cluster"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for interacting with VergeOS virtualization platform. This enables AI assistants like Claude, Windsurf/Cascade, and other MCP-compatible clients to manage VMs, networks, tenants, and monitor your VergeOS cluster through natural language.
This project provides two deployment options:
┌─────────────────────────────────────────────────────────────────────────────┐
│ DEPLOYMENT OPTIONS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Option 1: Local (stdio) Option 2: Remote (HTTP + Local Proxy) │
│ ───────────────────────── ───────────────────────────────────── │
│ │
│ ┌──────────┐ stdio ┌─────────┐ ┌──────────┐ HTTP ┌─────────┐│
│ │ Windsurf │◄──────────►│ MCP │ │ Windsurf │◄────────►│ Local ││
│ │ /Claude │ │ Server │ │ /Claude │ stdio │ Proxy ││
│ └──────────┘ └────┬────┘ └──────────┘ └────┬────┘│
│ │ │ │
│ │ HTTPS HTTPS │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌──────────┐ │
│ │VergeOS │ │ K8s MCP │ │
│ │ API │ │ Server │ │
│ └─────────┘ └────┬─────┘ │
│ │ │
│ HTTPS│ │
│ ▼ │
│ ┌──────────┐ │
│ │ VergeOS │ │
│ │ API │ │
│ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Option | Use Case |
Local (stdio) | AI client runs on the same machine that can reach VergeOS |
Remote (HTTP) | AI client is remote (e.g., laptop) and VergeOS is on a private network |
Related MCP server: ProxmoxEmCP
Tool | Description |
| List all virtual machines (filter by running/name) |
| Get detailed VM information by ID |
| Get VM running status and power state |
| Power on a VM |
| Gracefully power off with optional wait and auto-force |
| Force power off (hard shutdown) |
| Reset/reboot a VM |
Tool | Description |
| Change CPU cores and/or RAM (handles running VMs) |
| Add a new disk drive to a VM |
| Expand an existing disk (increase only) |
| Get VM network interfaces |
| Get VM disk drives with sizes |
Tool | Description |
| List all virtual networks |
| Get network details |
| Power on/off, reset, apply rules |
Tool | Description |
| List all tenants |
| Get tenant details |
| Power on/off, reset tenants |
Tool | Description |
| List cluster nodes |
| Get node statistics |
| Get cluster health status |
| Get storage tier statistics |
Tool | Description |
| List storage volumes |
| Get system logs (filter by level/object type) |
| Get active alarms |
Tool | Description |
| List snapshots for a VM |
| Create a snapshot (with optional expiration and quiesce) |
| Delete a VM snapshot |
| Restore a VM from a snapshot |
Graceful shutdown with wait: power_off_vm can wait for VM to shut down and auto-force if timeout expires
Running VM handling: modify_vm detects running VMs and can auto-shutdown to apply CPU/RAM changes
Log filtering: Filter logs by level (error, warning, audit) or object type (vm, node, vnet)
Snapshot expiration: create_vm_snapshot supports automatic expiration (default 7 days)
Quiesced snapshots: Option to quiesce VM before snapshot (requires guest agent)
vergeos://cluster/status - Cluster status overview
vergeos://vms/list - All virtual machines
vergeos://networks/list - All virtual networks
vergeos://alarms/active - Active system alarms
Use this if your AI client runs on a machine that can directly reach your VergeOS instance.
git clone <repo-url> vergeos-mcp-server
cd vergeos-mcp-server
npm installCreate a .env file:
VERGEOS_HOST=your-vergeos-host
VERGEOS_USER=admin
VERGEOS_PASS=your-passwordOr use an API token (recommended):
# Get a token
curl -sk -X POST "https://your-vergeos-host/api/sys/tokens" \
-u "admin:password" \
-H "Content-Type: application/json" \
-d '{"login":"admin","password":"password"}' | jq -r '."$key"'
# Set in .env
VERGEOS_HOST=your-vergeos-host
VERGEOS_TOKEN=your-token-hereAdd to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"vergeos": {
"command": "node",
"args": ["/path/to/vergeos-mcp-server/src/index.js"],
"env": {
"VERGEOS_HOST": "your-vergeos-host",
"VERGEOS_USER": "admin",
"VERGEOS_PASS": "your-password"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"vergeos": {
"command": "node",
"args": ["/path/to/vergeos-mcp-server/src/index.js"],
"env": {
"VERGEOS_HOST": "your-vergeos-host",
"VERGEOS_USER": "admin",
"VERGEOS_PASS": "your-password"
}
}
}
}Use this if your AI client (e.g., Windsurf on your laptop) cannot directly reach VergeOS, but you have a Kubernetes cluster that can.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Windsurf │─────►│ Local Proxy │─────►│ K8s MCP │─────►│ VergeOS │
│ (Laptop) │stdio │ (Laptop) │HTTPS │ Server │HTTPS │ API │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
┌─────┴─────┐
│ Traefik │
│ Ingress │
└───────────┘# Clone the repo on your K8s host
cd vergeos-mcp-server
# Edit credentials in deploy.sh or create ~/.vergeos-credentials
cat > ~/.vergeos-credentials << EOF
VERGEOS_USER=admin
VERGEOS_PASS=your-password
EOF
# Deploy
./deploy.shThis creates:
Namespace: vergeos-mcp
Deployment running the HTTP MCP server
Service exposing port 3002
IngressRoute for external access (Traefik)
Add a DNS record pointing to your Traefik ingress:
vergeos-mcp.yourdomain.com → <traefik-ip># Health check
curl https://vergeos-mcp.yourdomain.com/health
# List VMs
curl https://vergeos-mcp.yourdomain.com/vms
# MCP protocol test
curl -X POST https://vergeos-mcp.yourdomain.com/message \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Since Windsurf only supports stdio-based MCP servers, you need a local proxy:
# Create directory
mkdir -p ~/.mcp/vergeos
cd ~/.mcp/vergeos
# Create package.json
cat > package.json << 'EOF'
{
"name": "vergeos-mcp-proxy",
"version": "1.0.0",
"type": "module",
"dependencies": {
"@modelcontextprotocol/sdk": "^0.5.0",
"node-fetch": "^3.3.2"
}
}
EOF
# Create index.js
cat > index.js << 'EOF'
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
const SERVER_URL = process.env.VERGEOS_MCP_URL || "https://vergeos-mcp.yourdomain.com";
async function apiCall(path, options = {}) {
const fetch = (await import("node-fetch")).default;
const response = await fetch(`${SERVER_URL}${path}`, {
...options,
headers: { "Content-Type": "application/json", ...options.headers },
});
if (!response.ok) throw new Error(`API Error: ${response.status}`);
return response.json();
}
const server = new Server({ name: "vergeos", version: "1.0.0" }, { capabilities: { tools: {} } });
const TOOLS = [
{ name: "list_vms", description: "List all VMs in VergeOS", inputSchema: { type: "object", properties: {} } },
{ name: "get_vm", description: "Get VM details by ID", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
{ name: "power_on_vm", description: "Power on a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
{ name: "power_off_vm", description: "Power off a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
{ name: "reset_vm", description: "Reset a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
{ name: "list_networks", description: "List virtual networks", inputSchema: { type: "object", properties: {} } },
{ name: "list_tenants", description: "List tenants", inputSchema: { type: "object", properties: {} } },
{ name: "list_nodes", description: "List cluster nodes", inputSchema: { type: "object", properties: {} } },
{ name: "get_cluster_status", description: "Get cluster status", inputSchema: { type: "object", properties: {} } },
{ name: "get_alarms", description: "Get active alarms", inputSchema: { type: "object", properties: {} } },
{ name: "get_logs", description: "Get system logs", inputSchema: { type: "object", properties: { limit: { type: "number" } } } },
];
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
try {
const result = await apiCall(`/tools/${name}`, { method: "POST", body: JSON.stringify(args || {}) });
return { content: [{ type: "text", text: JSON.stringify(result.result, null, 2) }] };
} catch (error) {
return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
}
});
const transport = new StdioServerTransport();
await server.connect(transport);
EOF
# Install dependencies
npm installAdd to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"vergeos": {
"command": "node",
"args": ["/Users/yourusername/.mcp/vergeos/index.js"],
"env": {
"VERGEOS_MCP_URL": "https://vergeos-mcp.yourdomain.com"
}
}
}
}Restart Windsurf to load the new MCP server.
The HTTP server also exposes a REST API for direct access:
Endpoint | Method | Description |
| GET | Health check |
| GET | List available MCP tools |
| POST | Execute an MCP tool |
| GET | List all VMs |
| GET | Get VM details |
| POST | VM action (poweron/poweroff/reset) |
| GET | List networks |
| GET | List tenants |
| GET | List nodes |
| GET | Cluster status |
| GET | Active alarms |
| GET | System logs |
Endpoint | Method | Description |
| GET | Server-Sent Events connection |
| POST | MCP JSON-RPC messages |
Once connected, you can ask your AI assistant:
"List all VMs in VergeOS"
"Power off the VM named 'test-vm'"
"Show me the cluster status"
"What alarms are active?"
"List all virtual networks"
"Get details for VM ID 34"
"How many nodes are in the cluster?"
"Show me the last 20 log entries"
"Create a snapshot of VM 34 called 'before-upgrade'"
"List all snapshots for the web-server VM"
"Restore VM 34 from snapshot ID 123"
"Add 2GB RAM to the database VM"
"Add a 50GB data disk to VM 34"
VergeOS uses cookie-based authentication:
POST to /api/sys/tokens with Basic Auth
Response contains token in $key field
Use token as cookie: Cookie: token=<value>
# Get token
TOKEN=$(curl -sk -X POST "https://vergeos/api/sys/tokens" \
-u "admin:password" \
-H "Content-Type: application/json" \
-d '{"login":"admin","password":"password"}' | jq -r '."$key"')
# Use token
curl -sk "https://vergeos/api/v4/vms" -b "token=$TOKEN"VMs with is_snapshot: true are templates, not running VMs
/machine_nics?machine=<ID> may return NICs from other machines; always filter by machine ID
Use fields=most for detailed responses, but be aware of large payloads
SSL verification is disabled for self-signed certificates (common in homelabs)
Store credentials in environment variables or Kubernetes secrets
Use API tokens instead of username/password when possible
The HTTP server should be behind TLS (handled by Traefik/Ingress)
Consider network policies to restrict access to the MCP server
# Test VergeOS API directly
curl -sk https://your-vergeos-host/api/v4/vms -b "token=YOUR_TOKEN"
# Test MCP server
curl https://vergeos-mcp.yourdomain.com/healthTokens may expire. The server automatically fetches new tokens using username/password if configured.
# Manually refresh token
curl -sk -X POST "https://your-vergeos-host/api/sys/tokens" \
-u "admin:password" \
-H "Content-Type: application/json" \
-d '{"login":"admin","password":"password"}'kubectl logs -n vergeos-mcp deployment/vergeos-mcp
kubectl get pods -n vergeos-mcp# Test proxy directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node ~/.mcp/vergeos/index.jsvergeos-mcp-server/
├── src/
│ ├── index.js # Stdio MCP server (local use)
│ ├── http-server.js # HTTP server (legacy)
│ ├── mcp-http-server.js # HTTP+MCP server (K8s deployment)
│ └── stdio-proxy.js # Stdio proxy for remote server
├── local-proxy/
│ ├── package.json # Local proxy dependencies
│ └── index.js # Local proxy for Windsurf
├── deploy.sh # Kubernetes deployment script
├── k8s-deployment.yaml # Kubernetes manifests
├── package.json
├── .env.example
└── README.mdMIT
Get active system alarms
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does but doesn't describe important behavioral aspects like whether this returns real-time or historical data, pagination behavior, rate limits, authentication requirements, or what constitutes an 'active' alarm. The description is minimal and lacks operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just three words, front-loading the essential information with zero wasted text. Every word earns its place, making it immediately clear what the tool does without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what format the alarms are returned in, what information they contain, whether this is a read-only operation, or any error conditions. Given the complexity of system monitoring and the lack of structured documentation, the description should provide more operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema fully documents the parameter situation. The description doesn't need to compensate for any parameter gaps, and the baseline for zero parameters is 4. The description appropriately doesn't mention parameters since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get active system alarms' clearly states the verb ('Get') and resource ('active system alarms'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get_logs' or 'get_cluster_status', but the specificity of 'alarms' provides inherent distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While the description implies it's for retrieving alarm information, it doesn't specify whether this is for real-time monitoring, historical analysis, or how it differs from related tools like 'get_logs' or status-checking siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get cluster tier statistics (storage tiers)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what the tool does ('Get cluster tier statistics') without any information about permissions required, rate limits, response format, or whether it's a read-only operation. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Get cluster tier statistics (storage tiers)')—just one phrase that directly states the purpose. It's front-loaded with the core action and resource, with no wasted words or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is minimally complete for a simple read operation. However, with no annotations to provide behavioral context and siblings that might overlap, it lacks guidance on usage and behavioral traits. It's adequate but has clear gaps in contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline score of 4 is applied since no parameters exist, and the description doesn't incorrectly imply any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get cluster tier statistics (storage tiers)'. It specifies the verb ('Get') and resource ('cluster tier statistics'), making it unambiguous. However, it doesn't explicitly differentiate from siblings like 'get_cluster_status' or 'get_node_stats', which might also provide statistical data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get_cluster_status' and 'get_node_stats' that might overlap in scope, there's no indication of when this tool is appropriate or what distinguishes it from other statistical tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the overall cluster status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states what the tool does ('Get the overall cluster status') without explaining what 'overall cluster status' entails, whether it's a read-only operation, what format the output takes, or any performance or permission considerations. This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It's front-loaded with the core purpose and appropriately sized for a simple, parameterless tool, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'overall cluster status' means (e.g., health, performance, configuration), what data is returned, or how this differs from sibling tools like 'get_cluster_stats'. For a tool in a cluster management context with many siblings, more context is needed to guide proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately doesn't mention parameters, which is efficient and correct for a parameterless tool, earning a high baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('overall cluster status'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'get_cluster_stats', which could provide similar cluster-related information, leaving some ambiguity about when to use one versus the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_cluster_stats' or other sibling tools. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent system logs
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of log entries to retrieve (default 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'recent' but doesn't clarify time ranges, ordering, or format of logs. For a read operation with no annotation coverage, this leaves critical gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a single phrase, 'Get recent system logs', which is front-loaded and wastes no words. However, it might be overly terse given the lack of context, slightly reducing effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what 'recent' means, the log format, or return values, leaving the agent with insufficient context for a tool that retrieves system data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for the 'limit' parameter, so the baseline is 3. The tool description adds no additional parameter information beyond what the schema provides, such as default behavior or constraints, so it doesn't enhance semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get recent system logs' clearly states the verb ('Get') and resource ('system logs'), making the purpose understandable. However, it lacks specificity about what 'recent' means and doesn't differentiate from sibling tools like 'get_alarms' or 'get_cluster_status', leaving ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get_alarms' and 'get_cluster_status' that might overlap in monitoring contexts, there's no indication of when this tool is appropriate or what distinguishes it, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific network
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Network ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it 'gets detailed information' but doesn't clarify what 'detailed' includes, whether it's a read-only operation, if it requires specific permissions, or what the response format looks like. This leaves significant gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, with no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' entails, potential error conditions, or behavioral traits like rate limits. For a tool with no structured metadata, more descriptive context is needed to adequately inform usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'Network ID'. The description adds no additional semantic context beyond what the schema provides, such as format examples or constraints, so it meets the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed information about a specific network'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_networks' (which likely lists multiple networks vs. getting details for one).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'get_network' over 'list_networks' or other get_* tools, nor does it specify prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics for a specific node
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Node ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get statistics' implies a read-only operation, it doesn't specify what kind of statistics are returned, whether there are rate limits, authentication requirements, or what format the statistics come in. This leaves significant behavioral gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words ('Get statistics for a specific node'), with zero wasted words. It's front-loaded with the core purpose and efficiently communicates the essential information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a statistics-retrieval tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what statistics are returned, their format, or any behavioral characteristics. Given the complexity of statistical data and the lack of structured output information, the description should provide more context about what 'statistics' encompasses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% with the single parameter 'id' clearly documented as 'Node ID'. The description doesn't add any additional parameter semantics beyond what the schema provides, but with complete schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get statistics') and target resource ('for a specific node'), which is a specific verb+resource combination. However, it doesn't distinguish itself from sibling tools like 'get_cluster_stats' or 'get_vm_status' that might provide similar statistical information for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when-not-to-use scenarios, or comparisons to sibling tools like 'get_cluster_stats' or 'list_nodes' that might serve related purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific tenant
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tenant ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'gets' information, implying a read-only operation, but doesn't specify permissions required, rate limits, error handling, or what 'detailed information' entails (e.g., format, fields). This is insufficient for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' includes (e.g., response structure), behavioral aspects like errors or permissions, or how it differs from sibling tools. For a tool in this context, more detail is needed to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the parameter 'id' documented as 'Tenant ID'. The description adds no additional meaning beyond this, such as format examples or constraints. Given the high schema coverage, the baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed information about a specific tenant'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_tenants' or 'tenant_action', which would require more specificity for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'get_tenant' over 'list_tenants' for listing tenants or 'tenant_action' for performing actions on tenants, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific VM by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Get detailed information' implies a read-only operation, it doesn't explicitly state whether this requires authentication, has rate limits, returns specific data formats, or handles errors. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates the core functionality without any wasted words. It's appropriately sized for a simple lookup tool and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and 100% schema coverage, the description is minimally adequate. However, without annotations or an output schema, it doesn't provide enough context about what 'detailed information' includes, error handling, or authentication requirements, leaving some gaps in understanding the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'id' clearly documented as 'VM ID' in the schema. The description adds no additional parameter semantics beyond what's already in the structured schema, so it meets the baseline expectation without adding extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('detailed information about a specific VM by ID'), making it easy to understand what the tool does. However, it doesn't explicitly distinguish this tool from its sibling 'get_vm_status' or 'list_vms', which would have earned a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_vm_status' (for status-only info) or 'list_vms' (for listing multiple VMs). It simply states what the tool does without any context about appropriate usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get disk drives for a VM
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get'), implying a read-only operation, but does not specify aspects like authentication requirements, rate limits, error handling, or the format of returned data. This leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence that directly conveys the tool's purpose without unnecessary words. It is front-loaded and efficient, making it easy to parse quickly, which is ideal for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficient. It does not explain what data is returned (e.g., drive types, sizes, statuses) or any behavioral nuances like pagination or error conditions. Given the complexity of VM management and the lack of structured data, more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'VM ID'. The description adds no additional semantic context beyond this, such as examples or constraints on valid IDs. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema adequately handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('disk drives for a VM'), making the purpose immediately understandable. However, it does not differentiate from sibling tools like 'get_vm' or 'get_vm_nics', which also retrieve VM-related information but focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'get_vm' for general VM details or 'list_volumes' for broader storage information. It lacks any context about prerequisites, exclusions, or specific scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get network interfaces for a VM
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states a read operation ('Get'), implying it is non-destructive, but does not cover aspects like error handling, rate limits, authentication needs, or what the output format might be (e.g., list of NICs with details). This leaves significant gaps for a tool with no structured safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words, making it highly concise and front-loaded. It efficiently communicates the core purpose without unnecessary elaboration, earning a top score for brevity and clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not explain what the tool returns (e.g., NIC details, error responses) or behavioral traits like permissions or side effects. For a read operation with no structured context, more information is needed to guide the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'VM ID'. The description does not add any meaning beyond this, such as format examples or constraints, but the schema provides adequate baseline information, justifying a score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('network interfaces for a VM'), making the purpose immediately understandable. However, it does not differentiate from sibling tools like 'get_vm' or 'get_vm_status', which might also retrieve VM-related information, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'get_vm' or 'list_vms', which might offer overlapping or related data. There is no mention of prerequisites, exclusions, or specific contexts for usage, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current status of a VM (running, stopped, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it's a read operation ('Get'), implying non-destructive, but doesn't disclose behavioral traits like authentication needs, rate limits, error conditions, or what 'etc.' includes. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It front-loads the purpose clearly and uses parentheses to succinctly elaborate on 'status'. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple input schema, the description is incomplete. It lacks details on return values (e.g., what specific statuses are possible), error handling, or operational context. For a tool that could involve critical system state, this leaves gaps in understanding its full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'id' documented as 'VM ID'. The description adds no additional meaning beyond this, such as format examples or constraints. With high schema coverage, the baseline is 3, as the schema does the heavy lifting without extra value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('current status of a VM'), specifying what information is retrieved (running, stopped, etc.). It distinguishes from siblings like 'get_vm' (likely general VM info) or power control tools, but doesn't explicitly name alternatives. This makes it clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_vm' (which might include status) or 'list_vms' (which might show statuses). The description implies usage for checking VM state, but lacks explicit context, prerequisites, or exclusions, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all virtual networks in VergeOS
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it lists networks but doesn't mention any behavioral traits like pagination, sorting, filtering options, rate limits, authentication requirements, or what the output format looks like. This leaves significant gaps for an agent to understand how to use it effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters) but lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like output format, pagination, or error handling, which are important for a list operation even without parameters. The description alone is insufficient for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline of 4 is applied since no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('all virtual networks in VergeOS'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'get_network' (singular) or 'network_action', but the plural 'all' implies a comprehensive listing rather than retrieving a specific network.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_network' (for a specific network) or 'network_action' (for operations on networks). The description implies it's for listing all networks, but doesn't clarify use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all nodes in the VergeOS cluster
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists nodes but doesn't cover aspects like pagination, rate limits, authentication needs, or what the output format might be. This leaves significant gaps for an agent to understand how to interact with the tool effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that front-loads the core purpose without any wasted words. It efficiently communicates what the tool does, making it easy for an agent to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate but lacks depth. It doesn't address behavioral aspects like output format or usage context, which could be important for an agent to operate correctly in a cluster environment with multiple related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate here, and it implies no filtering or arguments are required, aligning well with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('all nodes in the VergeOS cluster'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_node_stats' or 'get_cluster_status', which might provide overlapping or related information about nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_node_stats' and 'get_cluster_status' that might offer node-related data, the description lacks any context about use cases, prerequisites, or comparisons to help an agent choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tenants in VergeOS
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it lists all tenants but doesn't mention any behavioral traits like pagination, rate limits, permissions required, or what 'all tenants' means in practice (e.g., active only, includes deleted). This leaves significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple list operation, the description is incomplete. It doesn't explain what the output contains (e.g., tenant IDs, names, statuses) or any behavioral context like ordering or limitations, leaving the agent with insufficient information for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter semantics, and it doesn't contradict the schema. Baseline is 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all') and resource ('tenants in VergeOS'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_tenant' or 'tenant_action', which would require more specific scope or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_tenant' (for a specific tenant) or 'tenant_action' (for performing actions on tenants). There's no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all virtual machines in VergeOS. Can filter by running status or name.
| Name | Required | Description | Default |
|---|---|---|---|
| running | No | Filter to only running VMs | |
| name | No | Filter by VM name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's a listing operation with filtering. It doesn't disclose important behavioral aspects like pagination behavior, rate limits, authentication requirements, error conditions, or what 'partial match' means for the name filter. For a tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise - two sentences that directly state the purpose and key capability. Every word earns its place with zero wasted text. It's front-loaded with the core purpose followed by the filtering capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a listing operation that likely returns structured data, the description is incomplete. It doesn't explain what information is returned about each VM, whether results are paginated, or any error handling. For a tool in a system with many sibling tools, more contextual guidance would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description mentions filtering capabilities but doesn't add meaningful semantic context beyond what's in the schema descriptions. The baseline 3 is appropriate when the schema does all the parameter documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('virtual machines in VergeOS'), making the purpose immediately understandable. It distinguishes from some siblings like 'get_vm' (singular) but doesn't explicitly differentiate from other list tools like 'list_networks' or 'list_nodes' - hence not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through the mention of filtering capabilities ('Can filter by running status or name'), suggesting when this tool might be preferred over unfiltered alternatives. However, it doesn't provide explicit guidance on when to use this versus other VM-related tools like 'get_vm' or power management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all storage volumes
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('List') but doesn't describe what 'List' entails—whether it returns a summary or detailed data, if it's paginated, requires authentication, has rate limits, or affects system state. For a tool with zero annotation coverage, this is insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste: 'List all storage volumes'. It is front-loaded and appropriately sized for a simple tool, making it easy to parse quickly. Every word earns its place by specifying the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimal but incomplete. It lacks context on return values, behavioral traits, or usage scenarios. For even a simple tool, more detail on what 'List' returns or system impact would improve completeness, especially with no annotations to fill gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, meaning there are no parameters to document. The description doesn't need to add parameter semantics beyond what the schema provides. A baseline of 4 is appropriate as the description implies no filtering or options, aligning with the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all storage volumes' clearly states the verb ('List') and resource ('storage volumes'), making the purpose immediately understandable. It distinguishes from siblings like 'list_networks' or 'list_vms' by specifying the resource type. However, it doesn't specify scope or filtering options, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_vm_drives' that might retrieve volume information for specific VMs, there's no indication of whether this tool lists all volumes globally or per-resource. No exclusions, prerequisites, or comparison to siblings are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an action on a network (poweron, poweroff, reset, apply)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Network ID | |
| action | Yes | Action to perform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only lists actions without disclosing behavioral traits. It doesn't mention permissions needed, whether actions are destructive, rate limits, or response behavior, which is inadequate for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste, front-loaded with the core purpose. It lists actions concisely without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral impact, error handling, or return values, failing to compensate for the missing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters. The description adds no additional meaning beyond listing actions, which aligns with the enum but doesn't explain semantics like what 'apply' or 'applydns' do. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'perform' and resource 'network', specifying the actions available (poweron, poweroff, reset, apply). It distinguishes from siblings like power_on_vm and power_off_vm by focusing on networks rather than VMs, though it doesn't explicitly mention this distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like power_on_vm or tenant_action. The description lists actions but doesn't explain context, prerequisites, or exclusions, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power off a virtual machine (graceful shutdown)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID to power off |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'graceful shutdown,' which implies a safe, orderly power-off rather than a forced stop, but fails to cover critical aspects like required permissions, potential side effects (e.g., data loss if unsaved), rate limits, or response behavior. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('power off a virtual machine') and adds clarifying detail ('graceful shutdown') without unnecessary words. Every part earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a mutation operation (powering off a VM) with no annotations, no output schema, and incomplete behavioral transparency, the description is insufficient. It lacks details on permissions, side effects, error conditions, or what to expect upon success, leaving critical gaps for an AI agent to use it safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'id' documented as 'VM ID to power off.' The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('power off') and target resource ('virtual machine'), with the parenthetical 'graceful shutdown' adding specificity about the shutdown method. However, it doesn't explicitly differentiate from sibling tools like 'reset_vm' (which might imply a hard reset) or 'power_on_vm' (the opposite action), missing full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'reset_vm' or 'power_on_vm', nor does it mention prerequisites (e.g., VM must be powered on) or exclusions. It's a basic statement of function without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power on a virtual machine
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID to power on |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action but doesn't cover critical aspects like required permissions, whether this is a destructive operation, potential side effects (e.g., network activation), rate limits, or what happens on failure. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately clear and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral traits, error conditions, or result expectations, leaving the agent with insufficient context to use the tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'id' documented as 'VM ID to power on'. The description doesn't add any meaning beyond this, such as ID format or sourcing, but the schema adequately covers the parameter, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('power on') and resource ('a virtual machine'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'power_off_vm' or 'reset_vm', which would require explicit differentiation to earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'power_off_vm' or 'reset_vm'. The description lacks context about prerequisites (e.g., VM must be powered off), exclusions, or related workflows, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset/reboot a virtual machine
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | VM ID to reset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a mutation action ('reset/reboot') but fails to specify critical details like whether this requires admin permissions, if it's destructive to data or processes, expected downtime, or error conditions. This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single, front-loaded phrase that directly states the tool's purpose. There is no wasted language or redundancy, making it efficient and easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a mutation operation with no annotations and no output schema, the description is insufficient. It lacks details on behavioral traits, usage context, and expected outcomes, which are critical for safe and effective tool invocation. The description does not compensate for the absence of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'VM ID to reset'. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate since the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('reset/reboot') and resource ('a virtual machine'), making the purpose immediately understandable. It distinguishes itself from siblings like 'power_off_vm' and 'power_on_vm' by specifying a reboot rather than power cycling. However, it could be more specific about what 'reset' entails compared to 'reboot'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'power_off_vm' or 'power_on_vm', nor does it mention prerequisites such as VM state requirements. It lacks context about appropriate scenarios, such as after configuration changes or during troubleshooting, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an action on a tenant (poweron, poweroff, reset)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tenant ID | |
| action | Yes | Action to perform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but lacks critical behavioral details. It implies mutation (poweron/poweroff/reset) but doesn't disclose permissions needed, side effects, reversibility, or error conditions. For a tool that modifies tenant state, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It front-loads the core purpose and lists action types clearly, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'tenant' means in this context, the effects of actions, or what to expect upon success/failure. Given the complexity and lack of structured data, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (id as tenant ID, action with enum values). The description adds no additional parameter semantics beyond what's in the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('perform') and resource ('tenant'), specifying the action types (poweron, poweroff, reset). It distinguishes from most siblings that are 'get' or 'list' operations, though it doesn't explicitly differentiate from similar mutation tools like network_action or power_on_vm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like power_on_vm or reset_vm is provided. The description only lists actions without context about prerequisites, timing, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but there is some overlap between 'get_vm_status' and 'get_vm' (which includes status details), and 'network_action' and 'tenant_action' are generic action tools that could be confused with more specific ones like 'power_on_vm'. Descriptions help clarify, but minor ambiguity exists.
Tool names follow a consistent verb_noun pattern throughout, such as 'get_alarms', 'list_networks', and 'power_off_vm'. All tools use snake_case with clear, predictable naming, making them easily readable and organized.
With 21 tools, the count is slightly high but reasonable for a comprehensive VergeOS management server covering clusters, networks, tenants, VMs, and volumes. It provides detailed operations without being overly bloated, though it borders on heavy.
The tool set offers strong coverage for monitoring and basic VM/network/tenant management, including CRUD-like operations (e.g., list/get and actions). Minor gaps exist, such as no explicit tools for creating or deleting VMs, networks, or tenants, but agents can likely work around this using existing action tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Connects AI assistants to CloudQuell multi-cloud and AI cost, savings, anomaly, and budget data.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dvvincent/vergeos-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
