Skip to main content
Glama
bacarrdy

VPSnet

by bacarrdy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Write service file

write_service_file
Destructive

Write or replace a small service file (≤1 MiB) with compare-and-swap: pass expectedVersion/SHA256 to update safely or createOnly for a new file; conflicts return 409.

Instructions

Write a small file (at most 1 MiB) with compare-and-swap. Pass the content as text (UTF-8) or contentBase64, and exactly one precondition: expectedVersion or expectedSha256 from stat_service_file/read_service_file to replace an existing file, or createOnly=true for a new one. A file changed meanwhile answers 409 filesVersionConflict (+currentVersion) and is not touched; re-read it instead of forcing. A replaced file keeps its owner, mode, SELinux label and ACL. Use upload_service_file for larger files. 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:manage on a FULL-access API key as an explicit grant; the hosted connector needs vm:files:write. Execution-equivalent targets (authorized_keys, cron, systemd units, sudoers, PAM, profile files) are refused to every API key (filesExecEquivalentScopeMissing). 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
modeNoOctal permission bits for a NEW file, e.g. 0644
pathYesAbsolute path inside the server (UTF-8, at most 4096 bytes, no . or .. components)
contentNoNew content as UTF-8 text
orderNoYesTenant-owned service order number, e.g. VP12345
createOnlyNo
waitSecondsNoHow long this tool waits for a slow guest's operation before returning its operationId (default 30, recursive delete and extract 60)
contentBase64NoNew content as base64 (binary)
expectedSha256No
expectedVersionNo
confirmSystemPathNoSet true only after the user explicitly approved changing this operating-system path (otherwise 409 filesSystemPathConfirmRequired)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.3.17

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only flag it as destructive/non-idempotent; the description goes far beyond, disclosing 409 filesVersionConflict with currentVersion, preservation of owner/mode/SELinux/ACL on replace, 202 async polling behavior, required files:manage grant, refusal of execution-equivalent paths, 423 under 2FA lock, and per-platform availability reasons.

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 the operation and size limit, then preconditions, error semantics, permissions, and availability in a logical order. It is dense but nearly every clause carries behavioral weight; the waitSeconds default/recursive-delete parenthetical slightly duplicates the schema.

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 fully carries return semantics (final answer vs operationId after waitSeconds, 409 payload with currentVersion) and the full error/permission surface. Nothing an agent needs to invoke this destructive write correctly is missing.

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

Parameters4/5

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

Schema coverage is 70%, and the description adds the critical cross-parameter constraint the schema cannot express: exactly one of expectedVersion/expectedSha256 or createOnly=true, with those preconditions sourced from stat_service_file/read_service_file. It also explains the content vs contentBase64 choice, but leaves mode, path, and orderNo semantics entirely to the schema.

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 (write a service file) plus its defining constraints (at most 1 MiB, compare-and-swap). It explicitly distinguishes itself from the sibling upload_service_file for larger files, so an agent can route between them without opening either schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use rules: one precondition required to replace, createOnly=true for a new file, upload_service_file for larger files. It also states what to do on conflict (re-read, don't force) and forbids re-calling on a 202 (continue with get_service_file_operation instead), which is exactly the guidance an agent needs.

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