Skip to main content
Glama
bacarrdy

VPSnet

by bacarrdy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Stat service file

stat_service_file
Read-onlyIdempotent

Retrieve detailed metadata for a file or directory on a VPSnet service order, including type, size, mode, owner, mtime, version, kind, and optional SHA-256 hash.

Instructions

Describe one entry: type, size, mode, owner, mtime, version and kind (text, image, binary, directory, other). A symlink is followed to its canonical target unless follow=false. hash=true adds the SHA-256 (files up to 4 GiB, 30 s budget; otherwise hashSkipped). A slow guest answers 202 with an operation: this tool polls it itself and returns the final answer, or, after waitSeconds, the operationId to continue with get_service_file_operation (never repeat the call). Requires files:read on the API key as an explicit grant (a key whose permission list was left empty does not hold it), read or full access; the hosted connector needs vm:files:read. Availability: Firecracker servers need the updated guest agent (filesUnavailable reason agent_update_required; node_update_required while the host node is not updated yet) and Cloud VPS (KVM) servers need the VDS file-manager switch (reason feature_disabled while it is off); relay any unavailable reason verbatim and never work around it. A server whose 2FA lock is on answers 423.

Input Schema

NameRequiredDescriptionDefault
hashNo
pathYesAbsolute path inside the server (UTF-8, at most 4096 bytes, no . or .. components)
followNo
orderNoYesTenant-owned service order number, e.g. VP12345
waitSecondsNoHow long this tool waits for a slow guest's operation before returning its operationId (default 30, recursive delete and extract 60)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.3.17

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/idempotent annotations: async 202 polling behavior, hash size/time budget with hashSkipped fallback, required files:read grant (including the empty-permission-list caveat), Firecracker/VDS availability reasons, and the 423 2FA response. This is unusually rich disclosure of edge behavior for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then parameters, then async/auth/availability, so each block is placed where an agent needs it. The availability and auth sentences are dense and stacked, but every sentence carries non-redundant operational detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still names the returned fields, and it covers auth grants, connector scope, availability failure reasons, async continuation, and the 423 case. Nothing an agent needs to call this correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 60% (path, orderNo, waitSeconds), and the description compensates for the undocumented follow and hash by explaining symlink resolution and SHA-256 with its 4 GiB / 30 s limits. It also clarifies waitSeconds' role in returning an operationId, adding meaning the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Describe one entry') and enumerates exactly what is returned (type, size, mode, owner, mtime, version, kind), which cleanly separates it from siblings like read_service_file and list_service_files. An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to get_service_file_operation when a 202 operation is returned and warns 'never repeat the call', which is strong continuation guidance. It gives auth and availability preconditions but never states when to prefer this over list_service_files or read_service_file, so it stops short of full alternative coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools