Skip to main content
Glama
Sign In
Heming9

Agenterm

by Heming9
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Remote

list_clients

Read-onlyIdempotent

Lists online devices for a client token and can wait up to 20 seconds until a device connects, returning immediately when online; omit wait_ms for an instant snapshot.

Instructions

List online devices belonging to this client_token. Set wait_ms=20000 to wait server-side while no device is online; a connection returns immediately. After creating an invitation, show display_text in a progress message and keep calling with wait_ms=20000 until the target connects, the invitation expires, or the user cancels. An empty result is only a wait timeout: continue waiting without ending the turn or asking the user to check. Immediately notify the user when connected. With wait_ms omitted or 0, return a snapshot immediately. Use client_id to execute commands or start sessions. For multi-device tokens, any online device completes the wait; use snapshots to discover additional devices.

Input Schema

NameRequiredDescriptionDefault
wait_msNoWait up to this many milliseconds while no device is online (0-20000, default 0). After creating an invitation, use 20000 and repeat empty results until connection, invitation expiry, or user cancellation.
client_tokenYesTarget client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token.

Output Schema

NameRequiredDescriptionDefault
statusNoConnection wait status: waiting or connected. Session-stop status: stopping, stopped or finished.
clientsYesOnline devices owned by this token; an empty array means none are currently online.
next_actionNoNext step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.3.1-stdio.2
    • changedInput schema / properties / client_token / description
      Previous value: -"Target client connection token (required when authenticated with the management key)"New value: +"Target client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token."
    • changedOutput schema / additionalProperties
      Previous value: -trueNew value: +false
    • addedOutput schema / properties
      Added value: +{
+  "clients": {
+    "description": "Online devices owned by this token; an empty array means none are currently online.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "client_id": {
+          "description": "Six-character device identifier. Required to select a device for multi-device tokens.",
+          "type": "string"
+        },
+        "connected_at": {
+          "description": "UTC connection time in RFC 3339 format.",
+          "type": "string"
+        },
+        "hostname": {
+          "description": "Device-reported hostname for display only, not authentication.",
+          "type": "string"
+        },
+        "platform": {
+          "description": "Device-reported operating system and architecture.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "client_id",
+        "hostname",
+        "platform",
+        "connected_at"
+      ],
+      "type": "object"
+    },
+    "type": [
+      "null",
+      "array"
+    ]
+  },
+  "next_action": {
+    "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
+    "type": "string"
+  },
+  "status": {
+    "description": "Connection wait status: waiting or connected. Session-stop status: stopping, stopped or finished.",
+    "type": "string"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "clients"
+]
  2. First observedv0.3.1-stdio.1

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety bar is met. The description then adds non-obvious behavior: long-poll semantics, the fact that an empty result means timeout rather than no devices, and that notification should fire on connect. This is real added context beyond the annotations, though it does not cover limit/output shape (an output schema exists).

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 purpose, then the wait/snapshot distinction, then the workflow loop. Nearly every sentence carries operational instruction. It runs long and partially restates the wait_ms schema text, which keeps it from a 5.

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 exists, so return-value documentation is not required. Given a 2-parameter long-poll tool, the description covers purpose, polling cadence, empty-result interpretation, termination conditions, and the follow-up tool — everything an agent needs to call it correctly inside a multi-turn flow.

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 100%, so baseline is 3, but the description goes further by explaining the polling loop pattern for wait_ms and its interaction with invitation expiry, and by noting that for multi-device tokens any online device completes the wait. The client_token access-model caveat is left 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?

Opens with a specific verb and resource: 'List online devices belonging to this client_token.' It is immediately distinguishable from siblings like create_client, execute_command, and session_start, and the scope (online devices only, scoped by token) is explicit.

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 branching guidance: use wait_ms=20000 to block after creating an invitation, omit or use 0 for an immediate snapshot. It also states what to do on an empty result (keep waiting, do not end the turn) and names the downstream handoff ('Use client_id to execute commands or start sessions'), leaving nothing to inference.

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