bot-relay-mcp

health_check

Reports relay process health and live counts for agents, messages, tasks, channels, and webhooks, enabling liveness probes, version checks during upgrades, and dashboard status displays.

Instructions

Report relay process health + live counts.

When to use: liveness probes (/health HTTP endpoint mirrors this surface), version-pinning checks during upgrades, dashboard footers. Cheaper than get_standup for binary up/down questions.

Behavior: pure read. Counts agents by presence, pending messages, active and queued tasks, channels, and webhook subscriptions. Reports version (from package.json via the v2.1 Phase 4a single source of truth) + protocol_version (the client-compat surface, distinct from package version) + build (the build this process LOADED at start: its code and dependency ids, with commit, build time and node version; on stdio that is your own connector, so a stale one shows here). Works on stdio AND HTTP transports. No capability required, intentionally observable. Also reports surface — your active profile, the tool bundles in effect, and which tools those bundles HIDE — so a capability missing from tools/list can be told apart from one that does not exist.

Returns: { status: 'ok', version, protocol_version, transport, uptime_seconds, legacy_grace_active, agents: {...counts}, messages: {...counts}, tasks: {...counts}, channels, webhooks }. When the caller presents a token (arg / header / env), the response also includes token_validated: true, auth_error: boolean, and (on validation failure) auth_error_reason, plus agent_name + auth_state on success.

Errors: none expected (status='ok' is the only success shape).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "health_check"
  }
}

Input Schema

Name	Required	Description	Default
`agent_token`	No	Your agent token (from register_agent response). Optional here — also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header.

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 4, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations exist, so the description carries the full burden and does so: it declares 'pure read', 'No capability required, intentionally observable', works on both stdio and HTTP, and states 'Errors: none expected'. It further explains the subtle semantics of version vs protocol_version vs build (including that build is what the process LOADED, so a stale connector shows here) and that `surface` reveals hidden tool bundles.

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?

Strongly front-loaded and cleanly sectioned into purpose / When to use / Behavior / Returns / Errors, so an agent can stop reading early. Some sentences are over-loaded with internal implementation detail ('via the v2.1 Phase 4a single source of truth') that does not help tool selection and could be trimmed.

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?

There is no output schema, and the description compensates by spelling out the full return shape including the conditional auth fields. Combined with the explicit error contract and transport coverage, nothing an agent needs to invoke or interpret this tool 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?

The single parameter has 100% schema coverage and the schema already explains the env/header fallbacks. The description still adds real value by explaining the consequence of presenting a token — token_validated, auth_error, auth_error_reason, plus agent_name/auth_state on success — which is behavior the schema does not convey.

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?

Opens with a specific verb+resource ('Report relay process health + live counts') and immediately names the sibling it substitutes for ('Cheaper than get_standup for binary up/down questions'). An agent can distinguish it from get_standup, whoami, and report_liveness without opening any 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?

Explicitly enumerates when to use it: liveness probes (with the note that /health mirrors this surface), version-pinning checks during upgrades, and dashboard footers. It also gives the selecting condition against the closest alternative — 'cheaper than get_standup for binary up/down questions'.

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