Skip to main content
Glama
AndersonVitaease

MemoryOS VPS Guardian

MemoryOS VPS Guardian

Give AI responsibility for your VPS — not unrestricted shell access.

Open-source, read-only MCP tools for VPS health, capacity, change observation, incident summary, deployment state, application health, deployment readiness, Docker container health, why-down signal synthesis and log signal explanations — designed so AI agents do not need unrestricted SSH or shell access.

What is MemoryOS VPS Guardian?

MemoryOS VPS Guardian is a public MCP (Model Context Protocol) server for observing and understanding server state. Instead of handing an AI agent a raw shell, it exposes goal-oriented tools that return structured, evidence-based answers to practical operational questions such as:

  • Is my application healthy?

  • Is my VPS healthy?

  • Why is something down?

  • Is my deployment working?

  • Is it safe to deploy right now?

  • What changed recently?

  • Are my containers healthy?

  • What do these log errors mean?

Related MCP server: GhostInTheShell MCP

Why it exists

AI agents are increasingly used to operate infrastructure. Giving them unrestricted shell or SSH access is risky: a single wrong command can take production down, and audit trails become opaque. This project exists to narrow that gap with a small, auditable set of tools that answer operational questions and perform only explicitly bounded, validated operations.

Key principle: goal-oriented safe tools instead of unrestricted shell

  • Each tool answers one specific operational goal, not arbitrary power.

  • All ten public Simple Tools are read-only; no mutation path exists in the current public tool set, and any future mutation path would be explicit, allowlisted and validated.

  • Deterministic evidence comes first; interpretation is layered on top and must never fabricate findings.

See docs/SECURITY-MODEL.md for the full public security model.

Public Simple Tools catalog

The ten tools below are implemented, registered unconditionally in the MCP server, and documented individually under docs/tools/.

#

Tool

Answers

1

engineering.vps.health

Is my VPS healthy?

2

engineering.vps.why_down

Why is my VPS or application having a problem?

3

engineering.deploy.status

Is my deployment working?

4

engineering.vps.capacity

Is my VPS close to its limits?

5

engineering.vps.what_changed

What changed recently?

6

engineering.app.health

What application health state is reported?

7

engineering.vps.incident.summary

What is happening with my VPS right now?

8

engineering.deploy.ready

Are the minimum deterministic deployment prerequisites currently met?

9

engineering.docker.health

Are my containers healthy?

10

engineering.logs.explain

What do these errors/logs mean?

Security model

The public tool surface follows a least-privilege, evidence-first model:

  • No unrestricted shell or SSH channel is exposed to AI agents by default.

  • Tools are read-only wherever possible; changing operations are explicit, bounded and validated afterwards.

  • Evidence gaps are reported as such (for example UNKNOWN or insufficient evidence) and findings are never invented.

Full principles: docs/SECURITY-MODEL.md. Public vs. private scope: docs/PUBLIC-SCOPE.md. Responsible disclosure: SECURITY.md.

Current status

  • Ten public Simple Tools implemented: the MCP server ships engineering.vps.health, engineering.vps.capacity, engineering.vps.what_changed, engineering.vps.incident.summary, engineering.deploy.status, engineering.app.health, engineering.docker.health, engineering.vps.why_down and engineering.logs.explain (read-only, deterministic, evidence-based). what_changed is session-scoped - it compares only observations made by the running MCP process; restarting the server resets its baseline, and it has no visibility into anything before that baseline. incident.summary is a deterministic composition over the same evidence: it reports NORMAL, ATTENTION or UNKNOWN, never a root cause, and calling it counts as one shared change observation. deploy.status reports the deployment state from the operator-configured release-state evidence source (see Available tools below); without configuration it truthfully reports UNAVAILABLE, and app.health answers the application health question from the same source. The application/deployment safe adapter contract (typed evidence, strict validation and pure classifiers - see Safe adapter contract below) is implemented as a code-level seam, with the release-state file transport as its first evidence source.

  • No stable release has been published yet.

Planned public roadmap

  1. v0.1 — public foundation: MCP server/package foundation, the ten Simple Tools, public schemas/types and public documentation — implemented. Packaging, examples and release mechanics remain for the v0.1 release cycle.

  2. Safe adapter contracts: narrow interfaces, as needed, that let the public tools connect to a user's own deployment/monitoring mechanisms.

  3. Documentation-driven hardening: security-model checks, validation guidance and example configurations.

  4. Possible public equivalents of selected private capabilities: evaluated per item, without roadmap commitment (see docs/PUBLIC-SCOPE.md).

Requirements

  • Node.js 18 or newer — the minimum declared in package.json (engines.node: ">=18"). Only this floor is guaranteed by the project; no other specific versions are claimed as tested.

  • npm (bundled with Node.js) to install dependencies from the public npm registry.

Install from source

git clone https://github.com/AndersonVitaease/memoryos-vps-guardian.git
cd memoryos-vps-guardian
npm install

Run

npm start

The server runs over MCP stdio: it is started by the client process and communicates exclusively via standard input/output. There is no HTTP server and no network listener.

MCP client configuration

Generic example for launching the server from source. Exact syntax varies between MCP clients — most accept a command, arguments and a working directory in some form:

{
  "mcpServers": {
    "memoryos-vps-guardian": {
      "command": "npm",
      "args": ["start"],
      "cwd": "<path-to-memoryos-vps-guardian>"
    }
  }
}

Replace <path-to-memoryos-vps-guardian> with the local folder where you cloned this repository.

Available tools

Ten tools are implemented in this MVP:

engineering.vps.health

Input: exactly {} — no parameters; extra properties are rejected.

Output: a deterministic status plus supporting evidence:

  • HEALTHY — memory usage and 1-minute load per CPU are below the documented thresholds.

  • DEGRADED — clear pressure detected: memory usage above 90%, or 1-minute load above 2× the CPU count.

  • UNKNOWN — essential evidence could not be obtained; no diagnosis is invented.

Evidence collected (read-only, via Node.js os APIs — no shell, no SSH, no network):

  • uptime (seconds)

  • CPU count

  • 1-minute load average

  • total memory (bytes)

  • free memory (bytes)

  • memory usage percentage

engineering.vps.capacity

Answers: "Is my VPS close to its limits?"

Input: exactly {} — no parameters; extra properties are rejected.

Output: a deterministic pressure assessment with a per-component view (CPU, memory) and a global status:

  • OK — both CPU load and memory usage are below the documented thresholds.

  • PRESSURED — clear pressure detected on either component.

  • UNKNOWN — essential evidence could not be obtained; no classification is invented.

Current thresholds (raw values are compared; rounding is display-only):

  • memory used > 90% → HIGH

  • 1-minute load / CPU count > 2 → HIGH

Evidence collected (read-only, via the same Node.js os APIs — no shell, no SSH, no network):

  • CPU count

  • 1-minute load average

  • load per CPU

  • total memory (bytes)

  • free memory (bytes)

  • memory usage percentage

Current state only: the result describes the present snapshot — no future capacity prediction and no automatic upgrade recommendation.

engineering.vps.what_changed

Answers: "What changed since the previous observation made by this MCP process?"

Important — session scope: this tool has no historical visibility of the VPS. It keeps its baseline and last observation only in the memory of the running MCP server process. The first call creates the baseline and restarting the server resets all history. It does not provide deployment, file, service, container, configuration or user-action history, and never infers one.

Input: exactly {} — no parameters; extra properties are rejected.

Output: a deterministic status plus the observed changes:

  • BASELINE_CREATED — first observation of this process; nothing could be compared yet (changes is empty). The tool never claims any knowledge from before this baseline.

  • CHANGED — one or more observed differences above the documented thresholds since the previous observation of this process.

  • NO_CHANGE — no observed evidence changed above the thresholds since the previous observation of this process. This does not mean nothing changed on the VPS outside the evidence this tool observes.

  • UNKNOWN — essential evidence was unavailable or inconsistent (including a change of total memory between observations); nothing is fabricated and the previous observation is kept for the next comparison.

Significance thresholds (raw values are compared; rounding is display-only):

  • CPU count differs → cpuCount change

  • uptime decreased → reboot change (factual only; no cause is claimed)

  • free memory changed by more than 1% of total memory → memory change

  • 1-minute load per CPU changed by more than 0.5 → cpu change

Each reported change carries a factual description plus real before/after values. observationsSinceBaseline counts the successful observations of this process (first call = 1, second = 2, and so on), and baselineCapturedAt is the ISO UTC timestamp of the session's first successful observation.

engineering.vps.incident.summary

Answers: "What is happening on this VPS right now, according to local evidence?" — a deterministic composition of the three tools above, not a new evidence source.

Input: exactly {} — no parameters; extra properties are rejected.

Output: a single deterministic verdict plus compact observations:

  • NORMAL — health HEALTHY, capacity OK and no significant change observed (or the change-observation baseline was just created). A freshly created baseline is never treated as an incident or as proof of past stability.

  • ATTENTION — one or more currently observed conditions require attention: health DEGRADED, capacity PRESSURED or a significant change observed. This is not a confirmed incident, outage or failure and never names a cause.

  • UNKNOWN — some required evidence was unavailable or inconsistent; absence of evidence is never reported as NORMAL or ATTENTION.

observations contains exactly one factual note per component (engineering.vps.health, engineering.vps.capacity, engineering.vps.what_changed) and limitations is a fixed deterministic list: no causal conclusion is made; applications, services, containers, deployments and logs are not observed; change observation is scoped to this MCP process/session and facts before its baseline are unknown.

Shared change history: this tool uses the same session-scoped what_changed instance, so calling engineering.vps.incident.summary counts as one change observation — direct engineering.vps.what_changed calls and summary calls advance the same sequence.

Nothing beyond these ten tools is implemented yet.

engineering.deploy.status

Question answered: what deployment state is reported by the configured application/deployment evidence source? Returns a deterministic read-only verdict: OK (source reports SUCCEEDED), IN_FLIGHT (IN_PROGRESS), PENDING (QUEUED), FAILED (FAILED), UNKNOWN (a valid source explicitly reported no deployment status) or UNAVAILABLE (no source is configured, or the configured source returned no valid evidence).

Configuration (optional, operator-controlled): set MEMORYOS_VPS_GUARDIAN_RELEASE_STATE_FILE to the path of one local JSON release-state file (the ReleaseStateFileAdapter format) when launching the server. The variable is read once at startup by the host process; it is never caller-controlled, never echoed, and no MCP argument can supply or change the path. Without it the tool remains registered and truthfully answers UNAVAILABLE.

Output: status, summary, applicationId, source, observedAt, currentReleaseId, lastDeploymentFinishedAt, evidenceAgeSeconds and a fixed limitations list. With no valid evidence all evidence-derived fields are null — nothing is invented. evidenceAgeSeconds is the factual age of the evidence (floor((now − observedAt) / 1000)); it never changes the verdict, and a negative value means observable clock skew. The configured file path, file contents and any filesystem/validation errors are never exposed.

Scope: this tool does not assess application health, VPS health, readiness to deploy, rollback suitability, failure root cause or change safety.

engineering.app.health

Question answered: what application health state is reported by the configured validated application/deployment evidence source? Returns a deterministic read-only verdict: HEALTHY (the source reports applicationHealthy: true), DEGRADED (applicationHealthy: false), UNKNOWN (a valid source explicitly reported no application health) or UNAVAILABLE (no source is configured, or the configured source returned no valid evidence).

Configuration: none beyond engineering.deploy.status. It consumes the SAME operator-configured release-state evidence source (MEMORYOS_VPS_GUARDIAN_RELEASE_STATE_FILE); no new environment variable, transport or adapter exists, and the agent can never supply the path or any evidence value.

Output: status, summary, applicationId, source, observedAt, evidenceAgeSeconds and a fixed limitations list. With no valid evidence all evidence-derived fields are null and nothing is invented. evidenceAgeSeconds is the factual age of the evidence (floor((now - observedAt) / 1000)); it never changes the status, and a negative value means observable clock skew. The configured file path, file contents and any filesystem/validation errors are never exposed.

Scope: this tool reports evidence only. It does NOT probe the application, inspect Docker, call HTTP, infer health from deploymentStatus, or diagnose a root cause. UNAVAILABLE means no valid observation exists; UNKNOWN means a valid observation exists but the source explicitly did not report application health.

Independence: engineering.deploy.status and engineering.app.health consume the same evidence but answer different questions through different certified classifiers. They are never reconciled: deploymentStatus=SUCCEEDED with applicationHealthy=false truthfully reports OK from deploy.status and DEGRADED from app.health.

engineering.deploy.ready

Question answered: based on currently configured validated operational evidence, does the application satisfy the minimum deterministic prerequisites for attempting a deployment? Returns a deterministic read-only advisory verdict: READY, NOT_READY (with factual, non-causal blocking reasons), UNKNOWN (required valid evidence is incomplete) or UNAVAILABLE (a required evidence source is unavailable).

Evidence and reuse: computed only by the certified assessDeployReady classifier over the SAME operator-configured release-state evidence source as engineering.deploy.status and the existing local VPS health/capacity evidence. Four normalized components are reported: deployment, applicationHealth, vpsHealth, vpsCapacity. No new configuration, no new privileged access, no MCP tool-to-tool recursion.

Advisory only: this tool deploys nothing, approves nothing and grants no deployment or recovery authority. It does NOT predict deployment success and does not inspect code, migrations or release contents. UNKNOWN-first: any required component without evidence yields UNKNOWN, never READY or NOT_READY; absence of evidence is never read as a positive. UNAVAILABLE means a required evidence source is unavailable (no application source configured, or it returned no valid evidence).

Output: status, summary, applicationId, components, reasons, evidenceAgeSeconds and a fixed limitations list. evidenceAgeSeconds is factual evidence age; it never changes the verdict. Paths, filenames, raw evidence values and errors are never exposed. The four source Simple Tools are never reinterpreted: engineering.deploy.ready composes their underlying certified classifiers directly.

engineering.docker.health

Question answered: Is the configured Docker/container workload healthy?

Evidence and reuse: answered only from the operator-configured docker-health evidence source (MEMORYOS_VPS_GUARDIAN_DOCKER_HEALTH_FILE, one fixed operator-controlled JSON file produced by the operator's own monitoring stack outside this process) via the pure deterministic assessDockerHealth classifier - no new framework, no MCP tool-to-tool recursion, no Docker socket, no Docker CLI, no shell, no SSH, no network, no child processes, no LLM, no mutation, no deployment or recovery authority. Evidence is aggregated counts only (containers: total, running, unhealthy, restarting, stopped, unknown); no container names, IDs, images, labels, mounts, commands or raw inspect data are ever exposed. The MCP input must be exactly {} - the agent can never select a container, host, path, socket or filter.

Status semantics (deterministic, UNKNOWN-first): UNAVAILABLE when no evidence source is configured or it returns no valid evidence; UNKNOWN when required state is incomplete, any container state is unknown, or the aggregate counts are internally inconsistent - missing data is never converted into DEGRADED or HEALTHY; DEGRADED when the evidence source reports the runtime unavailable or any unhealthy/restarting/stopped containers; HEALTHY only when the runtime is reported available and all configured containers are running. No root causes are inferred. evidenceAgeSeconds is factual only and never changes the verdict. The verdict is computed independently of engineering.vps.health, engineering.deploy.status and engineering.app.health; contradictory states remain possible.

Zero-configuration: without MEMORYOS_VPS_GUARDIAN_DOCKER_HEALTH_FILE the server starts normally, the tool stays registered in tools/list, and it truthfully answers UNAVAILABLE.

engineering.vps.why_down

Question answered: Why does the currently configured VPS/application appear unhealthy? - concretely: is there evidence of a problem, which concrete signals are observed, and what cannot be determined.

Evidence and reuse: a deterministic synthesis of the evidence already available to this server - one local system-health snapshot feeds the existing assessVpsHealth and assessVpsCapacity classifiers, and when configured the operator-controlled release-state and docker-health sources feed assessApplicationHealth, assessDeployStatus and assessDockerHealth directly (no MCP tool-to-tool recursion, no new evidence source, no new environment variable, no Docker socket, no shell, no SSH, no network probe, no child processes, no LLM, no mutation). The input must be exactly {} - the agent can never select a host, application, container or path.

Signals, not causes: each signal is a normalized {category, source, status, summary} line from the existing classifiers (VPS_HEALTH, CAPACITY, APPLICATION_HEALTH, DEPLOYMENT, DOCKER). Problem predicates are factual only: VPS health DEGRADED, capacity PRESSURED, application health DEGRADED, deployment FAILED, Docker DEGRADED. A deployment IN_FLIGHT or PENDING is reported factually and is not a problem signal. When several degraded signals co-occur, all are reported and none is chosen as the cause - correlation is never presented as causation, and no root-cause field exists.

Status semantics (deterministic, UNKNOWN-first): UNAVAILABLE when no evidence source is configured at all; UNKNOWN when any observed signal is UNKNOWN (incomplete or inconsistent evidence) or UNAVAILABLE (a configured source returned nothing this call); DEGRADED when at least one factual problem signal is observed; HEALTHY when all observed signals report no degraded or problem condition. Categories without a configured source are absent from signals and their condition is never read as HEALTHY; Docker evidence being unavailable never by itself implies failure.

Zero-configuration: the server starts normally without the optional application/deployment and docker-health sources; the tool stays registered in tools/list and answers from the local VPS health and capacity signals alone, with missing categories explicit in the limitations.

engineering.logs.explain

Question answered: What do the currently configured operational log signals mean?

Evidence and reuse: answered only from the operator-configured log-evidence source (MEMORYOS_VPS_GUARDIAN_LOG_EVIDENCE_FILE, one fixed operator-controlled structured JSON file of already-normalized, already-sanitized log signals produced by the operator's own monitoring stack outside this process) via the pure deterministic assessLogsExplain classifier. It is NOT a log browser: no raw log files, no tail, no watch, no directories, no grep, no journalctl, no docker logs, no Docker socket, no shell, no SSH, no child processes, no network, no LLM, no mutation. The input must be exactly {} - the agent can never select a path, file, container, service, journal, query, filter or time range, and evidence messages are never returned.

Explanations (deterministic, no AI): a small fixed taxonomy (OUT_OF_MEMORY, CONNECTION_REFUSED, TIMEOUT, PORT_BIND_FAILURE, DNS_FAILURE, HEALTHCHECK_FAILURE, PROCESS_EXIT, PERMISSION_FAILURE) is matched first from producer-supplied structured codes, then - only when no code matches - from a small fixed set of message rules. Unclassifiable signals are reported as UNKNOWN and never guessed. Each explanation is compact and normalized (category, highest observed severity, fixed meaning, advisory plain-language suggestedCheck); no shell commands are ever emitted.

Status semantics (deterministic): UNAVAILABLE when no evidence source is configured or it returns no valid evidence; UNKNOWN when the valid evidence document contains no entries or every entry is unclassifiable; EXPLAINED when at least one signal maps to a known category. Statuses describe explanations, not health.

Zero-configuration: without MEMORYOS_VPS_GUARDIAN_LOG_EVIDENCE_FILE the server starts normally, the tool stays registered in tools/list, and it truthfully answers UNAVAILABLE.

Safe adapter contract (application/deployment evidence)

The code-level seam for the application/deployment tools (engineering.deploy.status, engineering.app.health and engineering.deploy.ready) is implemented, following the same injectable pattern as the host evidence adapter:

  • ApplicationDeploymentEvidence — one typed evidence snapshot (applicationId, observedAt, source, currentReleaseId, previousReleaseId, deploymentStatus, lastDeploymentFinishedAt, applicationHealthy), where every nullable field means "the evidence source cannot observe this".

  • applicationDeploymentEvidenceSchema with parseApplicationDeploymentEvidence / tryParseApplicationDeploymentEvidence — strict zod validation: unknown keys rejected, bounded strings, no control characters, ISO-8601 UTC timestamps only, and lastDeploymentFinishedAt must not be after observedAt. Malformed or inconsistent evidence is never repaired or guessed.

  • ApplicationDeploymentAdapter { name, collect(): evidence | null } — a pure, side-effect-free, read-only evidence seam analogous to SystemHealthAdapter.

  • Pure deterministic classifiers assessApplicationHealth (true/false/nullHEALTHY/DEGRADED/UNKNOWN), assessDeployStatus (SUCCEEDED/IN_PROGRESS/QUEUED/FAILED/nullOK/IN_FLIGHT/PENDING/FAILED/UNKNOWN) and assessDeployReady (advisory only: READY requires no in-flight/queued deployment, a reported-healthy application, no VPS health DEGRADED, no VPS capacity PRESSURED, and no required component UNKNOWN; it triggers nothing and grants no deployment authority).

No transport ships with this contract. It performs no file, socket, container-runtime, environment or credential access of any kind. Evidence authority stays with the host process that constructs the server; MCP tool arguments never carry this evidence. Missing evidence maps deterministically to UNKNOWN/UNAVAILABLE and is never inferred. Its consuming MCP tools are engineering.deploy.status, engineering.app.health and engineering.deploy.ready (see above).

Release-state file transport (ReleaseStateFileAdapter)

createReleaseStateFileAdapter({ path }) in src/adapters/releaseStateFile.ts is the first evidence source for the contract above: it reads one operator-configured local JSON file whose entire content is one ApplicationDeploymentEvidence document (all eight fields, including the required source label).

  • The path is operator-controlled and fixed at construction time. It is validated once (string, 1–4096 characters, no control characters) and resolved once with path.resolve(); invalid configuration throws at construction. The MCP agent can never supply or modify the path, and no MCP tool consumes evidence through its arguments.

  • Read-only, no generic filesystem access. The only I/O is statSync() + readFileSync() against that one absolute path — no writes, renames, deletes, directory listing, globs, watchers, polling, streams, retries, caching, or environment access, and no generic filesystem layer.

  • 64 KiB hard limit (MAX_RELEASE_STATE_BYTES = 65536), enforced before reading (via stat) and re-checked after reading.

  • Fail-closed. A missing file, permission denied, directory/non-regular file, oversized file, empty or malformed JSON, or evidence failing the strict contract schema all map deterministically to null (→ UNAVAILABLE), never a crash, a guessed status, or partially accepted evidence. No staleness is computed here and no clock is used: observedAt passes through exactly as validated, and staleness display/policy belongs to the consuming MCP tool.

  • Consumed by engineering.deploy.status, engineering.app.health and engineering.deploy.ready; the rest of the public catalog is unaffected and works with zero configuration.

  • Producer recommendation: write a temporary file, then atomically rename it over the configured path, so readers never observe a partial write (a partial write anyway fails closed).

Quick validation

From the repository root:

npm run typecheck
npm test

Expected current state: 320 tests passing across 12 test files.

License

Apache License 2.0

Available Tools

10 tools
engineering.app.healthApplication healthA

What application health state is reported by the configured validated application/deployment evidence source? Deterministic read-only verdict (HEALTHY | DEGRADED | UNKNOWN | UNAVAILABLE) built ONLY from the operator-configured release-state evidence source (MEMORYOS_VPS_GUARDIAN_RELEASE_STATE_FILE, read-only JSON file) — the same source and configuration as engineering.deploy.status; no new configuration. UNAVAILABLE means no source is configured or it returned no valid evidence; UNKNOWN means a valid source explicitly reported no application health. evidenceAgeSeconds is factual evidence age and never changes the status. It does NOT probe the application, inspect Docker, call HTTP, infer health from deployment status, or diagnose root cause. Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
sourceYes
statusYes
summaryYes
observedAtYes
limitationsYes
applicationIdYes
evidenceAgeSecondsYes

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and excels: it declares read-only, deterministic behavior, no mutation/shell/SSH/network/secrets, precisely defines the UNAVAILABLE vs UNKNOWN semantics, and clarifies that evidenceAgeSeconds is factual and never alters the status. The negative list of non-behaviors is unusually thorough.

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?

The description is dense but every sentence earns its place: verdict values, source identity, status semantics, exclusions, and safety guarantees. It is front-loaded with the core purpose. It runs long relative to its simple scope, but given there are no annotations or parameter descriptions to lean on, the length is justified.

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?

For a zero-parameter, deterministic read tool with an output schema present, the description is complete: it covers the verdict space, source provenance, status meaning, evidence-age semantics, exclusions, input contract, and safety profile. Nothing an agent needs to invoke it 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?

With zero parameters, the baseline is 4, and the description adds meaningful reinforcement beyond the empty schema by stating 'Input must be exactly {}' and explaining why ('no new configuration'), which helps an agent understand there is genuinely nothing to supply.

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?

The description states a specific verb+resource (reports application health state from the configured evidence source) and enumerates the exact verdict domain (HEALTHY | DEGRADED | UNKNOWN | UNAVAILABLE). It explicitly distinguishes itself from siblings by declaring what it does NOT do: probe the application, inspect Docker, call HTTP, infer from deployment status, or diagnose root cause.

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?

The description gives clear context positioning it as sharing 'the same source and configuration as engineering.deploy.status' and provides explicit when-not boundaries (not for probing, Docker inspection, HTTP calls, root-cause diagnosis). It falls just short of a 5 because it doesn't explicitly name the alternative tool to use for each excluded case.

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

engineering.deploy.readyDeployment readinessA

Based on currently configured validated operational evidence, does the application satisfy the minimum deterministic prerequisites for attempting a deployment? Deterministic read-only advisory verdict (READY | NOT_READY | UNKNOWN | UNAVAILABLE) computed ONLY by the certified readiness classifier over the operator-configured release-state evidence source (MEMORYOS_VPS_GUARDIAN_RELEASE_STATE_FILE, the same source as engineering.deploy.status) and existing local VPS health/capacity evidence — no new configuration. UNKNOWN means required valid evidence is incomplete; UNAVAILABLE means a required evidence source is unavailable. evidenceAgeSeconds is factual and never changes the verdict. Advisory only: this tool deploys nothing, approves nothing, grants no deployment or recovery authority, does not predict deployment success and does not inspect code, migrations or release contents. Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
reasonsYes
summaryYes
componentsYes
limitationsYes
applicationIdYes
evidenceAgeSecondsYes

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations provided, the description fully carries the burden and does an excellent job. It discloses that the tool is deterministic, read-only, advisory, performs no mutation/shell/SSH/network/secrets access, never changes the verdict based on evidenceAgeSeconds, and explains the UNKNOWN vs UNAVAILABLE distinction. This is far more behavioral detail than typical tool descriptions.

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?

The description is front-loaded with the core purpose and verdict types, then systematically covers evidence source, verdict meanings, and safety limitations. It is longer than strictly necessary and contains some redundancy around being advisory and non-mutating, but every sentence carries meaningful operational information for a deployment-related tool.

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?

Despite having zero parameters and an output schema, the tool is safety-sensitive and potentially confusing due to its deployment-related name. The description provides complete context: evidence sources, verdict semantics, advisory scope, input requirements, and explicit non-actions. An agent has enough information to decide whether to call it and what the verdict means.

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?

The tool has zero parameters and the schema already reflects an empty object with additionalProperties false. The description adds explicit reinforcement that 'Input must be exactly {}', which removes any ambiguity about whether optional or unexpected fields could be accepted. This fully addresses parameter semantics even without parameters.

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?

The description opens with a clear, specific question ('does the application satisfy the minimum deterministic prerequisites for attempting a deployment?') and names the exact return values READY | NOT_READY | UNKNOWN | UNAVAILABLE. It distinguishes itself from engineering.deploy.status by explicitly naming it as a sibling using the same evidence source while clarifying this tool is an advisory readiness check.

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?

The description gives strong context for when to use the tool: when a deterministic read-only readiness verdict is needed, based on existing evidence, without new configuration. It names engineering.deploy.status as sharing the same evidence source and clearly states exclusions ('does not predict deployment success', 'does not inspect code, migrations or release contents'), though it does not explicitly say 'use X instead' for alternative scenarios.

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

engineering.deploy.statusDeployment statusA

What deployment state is reported by the configured application/deployment evidence source? Deterministic read-only verdict (OK | IN_FLIGHT | PENDING | FAILED | UNKNOWN | UNAVAILABLE) built ONLY from the operator-configured release-state evidence source (MEMORYOS_VPS_GUARDIAN_RELEASE_STATE_FILE, read-only JSON file). UNAVAILABLE means no source is configured or it returned no valid evidence; UNKNOWN means a valid source explicitly reported no deployment status. evidenceAgeSeconds is factual evidence age and never changes the verdict. It does not assess application health, VPS health, readiness to deploy or failure causes. Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
sourceYes
statusYes
summaryYes
observedAtYes
limitationsYes
applicationIdYes
currentReleaseIdYes
evidenceAgeSecondsYes
lastDeploymentFinishedAtYes

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden. It clearly states the tool is deterministic, read-only, restricted to a single configured JSON source, and performs no mutation, shell, SSH, network, or secret access. It also explains the UNKNOWN/UNAVAILABLE edge semantics and that evidenceAgeSeconds never influences the verdict.

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

Conciseness5/5

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

Every sentence earns its place: source, verdict semantics, evidence-age behavior, exclusions, input constraint, and side-effect denials. The description is longer than average but tightly packed and front-loaded with its core purpose.

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?

The presence of an output schema means return fields need not be enumerated, and the description still covers edge-state semantics, evidence-age behavior, input constraints, and non-effects. An agent has all necessary context to invoke and interpret this tool correctly.

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?

The input schema already exhaustively defines the only valid input as {} with additionalProperties false, so the description adds minimal parameter information beyond restating "Input must be exactly {}." The zero-parameter baseline of 4 applies, as the description confirms the expected empty input.

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?

The description opens with a precise question—"What deployment state is reported by the configured application/deployment evidence source?"—and enumerates the exact deterministic verdict set. It also explicitly distinguishes itself from siblings by ruling out health, capacity, readiness, and failure-cause assessments.

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?

It provides clear when-not-to-use guidance by excluding application health, VPS health, readiness to deploy, and failure causes, which map to sibling tools. It also clarifies the meaning of UNAVAILABLE versus UNKNOWN to aid interpretation, though it stops short of naming alternative tools explicitly.

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

engineering.docker.healthDocker container healthA

Is the configured Docker/container workload healthy? Deterministic read-only advisory verdict (HEALTHY | DEGRADED | UNKNOWN | UNAVAILABLE) computed ONLY from the operator-configured docker-health evidence source (MEMORYOS_VPS_GUARDIAN_DOCKER_HEALTH_FILE, one fixed operator-controlled JSON file produced outside this process; aggregated counts only). This tool does NOT access the Docker socket, does NOT run the docker CLI, and does NOT probe containers: no shell, no SSH, no network, no secrets, no LLM, no mutation, no deployment or recovery authority. It never infers root causes; UNKNOWN means the valid evidence is incomplete or inconsistent, UNAVAILABLE means the evidence source is unavailable; absence of evidence is never read as HEALTHY. Input must be exactly {} — the agent can never select a container, host, path or socket.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
sourceYes
statusYes
summaryYes
findingsYes
containersYes
observedAtYes
limitationsYes
evidenceAgeSecondsYes

TDQS

A4.7/5.0
Behavior5/5

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

No annotations are provided, so the description carries full behavioral disclosure. It explicitly states read-only determinism, the absence of socket/CLI/probe access, no mutation or recovery authority, no root cause inference, and the exact meaning of UNKNOWN vs UNAVAILABLE. It even clarifies that absence of evidence is never read as HEALTHY. This is exceptionally transparent.

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?

The description is longer than minimal but every clause earns its place by constraining an agent's behavior around a nuanced read-only tool. It is front-loaded with the core purpose and statuses, then systematically lists exclusions. The no-shell/no-SSH/no-network/no-secrets enumeration is slightly redundant as a group but serves as a strong safety reminder.

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?

For a zero-parameter tool with an output schema, this description is complete: it defines the evidence source, status semantics, exclusions, and input constraint. The output schema covers return values, so no additional description is needed there. Nothing an agent needs to correctly select and invoke this tool is 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?

The schema has zero parameters, so the baseline is already high, and the description strengthens it by stating the input must be exactly {} and that the agent can never select a container, host, path, or socket. This prevents hallucinated parameter usage better than the schema alone.

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?

The description opens with a direct question and immediately states the tool returns a deterministic advisory verdict from a specific evidence source. It clearly distinguishes Docker/container health from its siblings by explicitly stating it does not access the Docker socket, run the Docker CLI, or probe containers. The status vocabulary (HEALTHY | DEGRADED | UNKNOWN | UNAVAILABLE) and the resource scope are unambiguous.

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?

The description gives clear context that this tool is for operator-configured Docker health evidence only and explicitly lists what the tool does not do (no shell, no SSH, no network, no mutation). It does not name sibling tools or provide explicit conditions for when to choose this tool over engineering.vps.health or engineering.app.health, but the boundaries are strongly implied.

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

engineering.logs.explainLog signal explanationsA

What do the currently configured operational log signals mean? Deterministic read-only advisory explanations (EXPLAINED | UNKNOWN | UNAVAILABLE) computed ONLY from the operator-configured log-evidence source (MEMORYOS_VPS_GUARDIAN_LOG_EVIDENCE_FILE, one fixed operator-controlled structured JSON file of already-normalized log signals produced outside this process). NOT a log browser: it never reads raw logs, never tails or watches files, never runs grep, journalctl or docker logs, and never touches the Docker socket. Classification is a small deterministic taxonomy (out-of-memory, connection refused, timeout, port-bind failure, DNS failure, health-check failure, process exit, permission failure) matched from producer-supplied codes first; unclassifiable signals are reported as UNKNOWN and evidence messages are never returned. Explanations are advisory: no shell, no SSH, no child processes, no network, no LLM, no mutation, no recovery authority. Input must be exactly {} — the agent can never select a path, file, container, service, journal, query or time range.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
sourceYes
statusYes
summaryYes
observedAtYes
limitationsYes
explanationsYes
evidenceAgeSecondsYes

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations provided, the description carries the full disclosure burden and does so admirably. It explicitly states the tool is deterministic, read-only, advisory, has no shell/SSH/child processes/network/LLM/mutation/recovery authority, never touches the Docker socket, and reports unclassifiable signals as UNKNOWN while never returning evidence messages. This goes far beyond what annotations typically provide and leaves no hidden behavior.

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

Conciseness5/5

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

Although the description is long, every sentence contributes distinct information: purpose, source, exclusions, taxonomy, advisory nature, and input constraint. It is well-structured and front-loaded with the core purpose, then layers constraints and exclusions logically. There is no filler or repetition, making the length justified.

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?

The description covers the tool's purpose, operational source, possible classification labels (EXPLAINED | UNKNOWN | UNAVAILABLE), deterministic taxonomy categories, all behavioral constraints, and the exact input shape. Since an output schema exists, it need not detail return structures. An agent has everything needed to invoke this tool correctly without guessing.

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?

The input schema is an empty object with zero properties, so the baseline is 4. The description adds crucial semantic clarity by stating 'Input must be exactly {}' and explicitly enumerating what the agent can never select (path, file, container, service, journal, query, time range). This prevents an agent from hallucinating parameters that the schema alone might not fully convey for such a constrained no-input tool.

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?

The description opens with a clear question defining the tool's purpose: 'What do the currently configured operational log signals mean?' It further specifies deterministic read-only advisory explanations and explicitly distinguishes itself from a log browser by stating what it never does (never reads raw logs, never tails files, never runs grep/journalctl/docker logs). This makes it distinct from all sibling tools and leaves no ambiguity about its scope.

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?

The description gives strong contextual guidance: explanations are computed only from a fixed operator-controlled JSON file of normalized log signals, not from raw logs. It clearly states exclusions ('NOT a log browser'), which tells the agent when not to use this tool, but it does not explicitly name a sibling alternative. Still, the boundary is clear enough for practical selection.

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

engineering.vps.capacityVPS capacityA

Is my VPS close to its capacity limits? Returns a deterministic read-only pressure assessment (OK | PRESSURED | UNKNOWN) for CPU load and memory, built from local OS evidence only. Current state only — no capacity prediction and no upgrade advice. Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
summaryYes
capacityYes

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses determinism, read-only behavior, local OS evidence only, current-state scope, and explicitly states no mutation, shell, SSH, network, or secrets. This gives an agent a complete safety and behavior profile.

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

Conciseness5/5

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

The description is compact and front-loaded: it opens with the user's likely question, then gives the result format, scope, and constraints. Every sentence earns its place with no wasted wording.

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?

An output schema is present, so the description does not need to explain return values. The description covers purpose, input constraints, safety, and scope thoroughly, making it complete for a zero-input read-only tool.

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?

There are zero parameters, so the baseline is 4. The description additionally states 'Input must be exactly {}', which reinforces the schema's empty object requirement and removes any ambiguity about needing arguments.

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?

The description clearly states that the tool returns a deterministic read-only pressure assessment (OK | PRESSURED | UNKNOWN) for CPU load and memory, built from local OS evidence only. It also scopes the behavior to current state and explicitly excludes prediction and upgrade advice, which distinguishes it from the sibling health tool.

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

Usage Guidelines3/5

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

The question form and exclusions imply this tool is for current capacity checks rather than prediction or upgrade guidance. However, it never explicitly names the sibling tool or states when to prefer one over the other, so usage guidance remains implied rather than explicit.

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

engineering.vps.healthVPS healthA

Is my VPS healthy? Returns a deterministic read-only verdict (HEALTHY | DEGRADED | UNKNOWN) built from local OS evidence only (uptime, CPUs, load average, memory). Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
summaryYes
evidenceYes

TDQS

A4.6/5.0
Behavior5/5

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, and it does this well. It states the operation is deterministic, read-only, local-only, and free of mutation, shell, SSH, network, and secrets. This gives the agent a precise and trustworthy safety profile.

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

Conciseness5/5

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

Three short sentences with no filler. The question front-loads the purpose, the verdict and evidence source are stated precisely, and the constraints are packed into a single clear list. Every sentence earns its place.

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?

For a zero-parameter tool with an output schema, the description is complete. It covers purpose, input format, safety, and scope. The only minor omission is an explicit pointer to the sibling capacity tool, but that is not necessary for correctly invoking this tool.

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?

There are zero parameters, so the baseline is 4, but the description adds explicit clarity by stating 'Input must be exactly {}.' This removes any ambiguity about whether an empty body or no body is expected, which is the only possible parameter-semantics concern for this tool.

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

Purpose4/5

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

The description is explicit about what the tool does: it returns a deterministic read-only verdict (HEALTHY | DEGRADED | UNKNOWN) based on local OS evidence. This clearly identifies it as a VPS health check, but it does not explicitly differentiate it from the sibling engineering.vps.capacity tool.

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?

The opening question 'Is my VPS healthy?' provides a clear context for use, and the constraints 'No mutation, no shell, no SSH, no network, no secrets' give the agent strong usage boundaries. However, it does not mention when to prefer this tool over engineering.vps.capacity or state any explicit alternatives.

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

engineering.vps.incident.summaryVPS incident summaryA

Deterministic composition summary: what is happening on this VPS right now according to the local evidence observed by this MCP process? Combines the current health, capacity and change observations. It shares the session history of engineering.vps.what_changed: calling this tool counts as one observation. Returns NORMAL, ATTENTION or UNKNOWN with compact factual notes and fixed limitations. It never claims a root cause and does NOT observe applications, services, containers, deployments or logs. Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
summaryYes
limitationsYes
observationsYes

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses determinism, local evidence, the shared session-history side effect (counts as one observation), the output categories, fixed limitations, and explicit no-mutation/no-shell/no-SSH/no-network/no-secrets guarantees.

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

Conciseness5/5

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

The purpose is front-loaded in the first clause, and every subsequent sentence adds necessary context: output categories, side effects, scope limits, input constraint, and safety guarantees. Dense but not wasteful.

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?

For a zero-parameter compositional tool with an output schema, this describes the semantic composition, return categories, side-effect coupling, and non-observations fully. Nothing needed for correct invocation is 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?

There are zero parameters, and the description still clarifies that the input must be exactly {}, reinforcing the schema's empty-object contract. This is more than the schema alone provides and removes any temptation to pass arguments.

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?

The description uses a specific verb ('combines') and resource ('VPS') and states the deliverable: NORMAL, ATTENTION, or UNKNOWN with factual notes. It also distinguishes itself from siblings by explicitly excluding applications, services, containers, deployments, and logs, making its scope unmistakable.

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?

Clear context is provided: use this for a deterministic composition of health, capacity, and change observations on a VPS right now, not for root-cause claims. It gives exclusions (no apps/services/containers/deployments/logs), though it does not explicitly name which sibling should be used instead.

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

engineering.vps.what_changedVPS what changedA

What changed since the previous observation made by this MCP process? Session/process scoped: the first call creates the baseline (BASELINE_CREATED) and later calls compare the current OS evidence (uptime, CPU count, load, memory) against the previous observation of THIS process. Restarting the server resets all history. It does NOT provide deployment, file, service or container history and knows nothing before its baseline. Input must be exactly {}. No mutation, no shell, no SSH, no network, no secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
changesYes
summaryYes
baselineCapturedAtYes
observationsSinceBaselineYes

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and does so admirably. It discloses stateful behavior (first call creates baseline, server restart resets history), explicitly states no mutation, shell, SSH, network, or secrets, and even mentions the BASELINE_CREATED signal. This is outstanding transparency.

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

Conciseness5/5

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

Every sentence earns its place: the purpose is front-loaded, the scope is clarified, exclusions are explicit, and constraints are listed compactly. No filler or redundancy.

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?

Given the tool's simplicity (0 params, output schema present), the description covers everything needed for correct invocation: what it does, how state is managed, what it does not cover, and input constraints. There are no meaningful gaps.

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?

The tool has zero parameters and the schema coverage is effectively 100%. The description reinforces the contract by stating 'Input must be exactly {}', which aligns with the schema. Per the baseline for 0-param tools, a 4 is appropriate.

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?

The description opens with a specific question, 'What changed since the previous observation made by this MCP process?', and then details exactly what is compared (uptime, CPU count, load, memory). It explicitly excludes deployment, file, service, and container history, which distinguishes it from sibling tools like engineering.deploy.status and engineering.docker.health.

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?

The description clearly states the session/process scoped behavior and the baseline-creation pattern, giving the agent a concrete idea of when to use it. It provides exclusions ('does NOT provide deployment, file, service or container history') but does not name alternative tools explicitly, stopping just short of full routing guidance.

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

engineering.vps.why_downVPS / application problem signalsA

Why does the currently configured VPS/application appear unhealthy? Deterministic read-only diagnostic synthesis of the evidence already available to this server: local VPS health and capacity plus the operator-configured application/deployment and docker-health sources when present. It reports normalized signals (VPS_HEALTH, CAPACITY, APPLICATION_HEALTH, DEPLOYMENT, DOCKER), what is degraded, what is unknown and what is not observable — SIGNALS, not root causes: correlation is never presented as causation and no recovery or deployment authority exists. No shell, no SSH, no network probe, no Docker socket, no logs, no secrets, no LLM, no mutation. Input must be exactly {} — the agent can never select a host, application, container or path.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYes
signalsYes
summaryYes
limitationsYes

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and fully discloses behavior: deterministic, read-only, no shell/SSH/network probe/Docker socket/logs/secrets/LLM, no mutation, and no selection authority. It also details what it reports (normalized signal names, degraded/unknown/not-observable) and explicitly states correlation is not causation. This is exemplary transparency.

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?

The description is dense but efficiently front-loaded with the purpose question, then method, outputs, and constraints. It is longer than typical, but every sentence adds value given the lack of annotations and the need to set firm expectations. Some minor redundancy exists between 'SIGNALS, not root causes' and 'correlation is never presented as causation', but the structure is logical and scannable.

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?

This is a complex diagnostic tool with no annotations, an empty schema, and a rich behavioral profile. The description covers purpose, evidence sources, output signals, known limitations, prohibited actions, and input constraints. Since an output schema exists, return-value details are appropriately omitted. The tool is fully specified and an agent can invoke it without ambiguity.

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?

The schema already documents an empty parameter set with additionalProperties=false. The description reinforces this by stating input must be exactly {} and explains why (the agent can never select a host, application, container, or path). With zero parameters, this goes beyond the schema by clarifying the intent of the empty input, though it largely restates the schema constraint.

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?

The description opens with a clear question ('Why does the currently configured VPS/application appear unhealthy?') and identifies a specific verb/resource: deterministic read-only diagnostic synthesis of existing evidence. It explicitly distinguishes itself from simpler health or capacity tools by emphasizing normalized signals and explicitly denies root-cause authority, making its role distinct among siblings.

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?

The description clearly implies when to use the tool: any time the agent needs a synthesized explanation for why the configured VPS/application appears unhealthy. It provides strong exclusions ('no recovery or deployment authority', 'SIGNALS, not root causes') that guide the agent away from expecting fixes. It does not explicitly name alternative tools for deeper investigation, but the limitations make the decision boundary clear enough.

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

TDQS

A4.5/5.0
Disambiguation4/5

Each tool has a clearly named evidence source or verdict type, and the descriptions are unusually explicit about boundaries. The one real overlap risk is engineering.vps.incident.summary vs engineering.vps.why_down, since both synthesize current VPS/app evidence and an agent might not immediately know which to call.

Naming Consistency4/5

The engineering.<domain>.<suffix> snake_case prefix is consistent and makes tool navigation predictable. The suffix style is somewhat mixed — noun statuses like health, capacity, status coexist with phrasal forms like what_changed, why_down, and explain — but this is a minor inconsistency rather than a serious problem.

Tool Count5/5

Ten tools is well within the ideal range for a read-only diagnostics/observability server. Each tool covers a distinct evidence area or synthesis role, and none feels redundant or superfluous.

Completeness4/5

The set covers VPS OS health, capacity, change detection, deployment status, application health, deployment readiness, Docker health, diagnostic synthesis, and log-signal explanation. Minor gaps exist — disk/network capacity and deployment history are absent — but the tools work together to cover the core 'guardian' workflow without dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    A sandboxed, read-only MCP server that safely exposes system metrics, container diagnostics, and logs to AI agents with intelligent context compression and strict security measures.
    MIT
  • F
    license
    A
    quality
    C
    maintenance
    A secure, read-only MCP server for AI-powered system monitoring. It provides real-time OS metrics, config discovery, and safe log tailing to enable autonomous infrastructure audits without shell access risks.
    4
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to investigate production incidents by exposing service health, logs, and deployment data through MCP tools.
    10

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AndersonVitaease/memoryos-vps-guardian'

If you have feedback or need assistance with the MCP directory API, please join our Discord server