mcp

List Machines

list_machines

Read-onlyIdempotent

List ALL of the user's saved machines with each one's access state and, when available, live status. USE THIS for fleet-wide questions or when the user has not named a machine yet. Requires account auth; without an account there is no list, so fall back to session_status with a specific AIC- code. Signing in with a free AI Commander account (https://aicommander.dev/dashboard/) adds this list and saved aliases. A user with no linked machine yet links one by installing the AI Commander agent on it from https://aicommander.dev, which provides an AIC- session code. Each entry includes blocked (operator approval/block state) and planRestricted (account-plan state); these are independent and can both be true. Free keeps every saved record but only the 10 oldest by creation time, then id, are usable. Newer records have planRestricted:true; deleting an older record promotes the next oldest. Pro accounts can use up to 100 saved records; plans are described at https://aicommander.dev/pricing/. NEVER attempt another tool against a plan-restricted entry: it will fail with reason:"plan_device_limit". Restricted entries intentionally expose no liveness or telemetry: online:false, lastSeenAt:null, with platform, agent version, and GPU details omitted. This is not evidence that the machine itself is offline. For an unrestricted entry, platform selects the shell dialect ('win32' means cmd.exe), offline platform/GPU data is last-known, and GPU details help pick a compute box. WHICH PHYSICAL BOX IS WHICH: each entry also reports the machine's own hostname and, when its agent sends them, its local IP addresses — the alias is only what the account typed when it saved the machine, so an account holding aic-wfs-pc, aic-wfs-pc2 and aic-wfs-pc3 has nothing else to tell them apart. Use those when the user asks which machine is which, or to confirm you are about to act on the box they mean. They are the machine's OWN addresses on its OWN network: a label, never a route — you cannot reach a machine at one, every command still goes through this relay — and DHCP may reassign one, so never treat an address as an identity. A missing address list means the machine's agent did not report one (older agents do not), NEVER that the machine has no network; for an offline entry both are last-known, exactly like platform and GPU data. Takes no arguments.

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": "list_machines"
  }
}

Input Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

AddedJun 18, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the readOnly/idempotent annotations: it discloses the two independent state flags (blocked vs planRestricted), the free-tier rule that only the 10 oldest records are usable and that deletion promotes the next oldest, the hard failure mode 'reason:"plan_device_limit"' if another tool is tried against a restricted entry, and that restricted entries expose no liveness so online:false is not evidence the machine is offline.

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

Conciseness4/5

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

Front-loaded with purpose and when-to-use before the field semantics, and the emphasized sections (plan limits, identity caveats) each carry decision-relevant content. It is long and repeats the last-known-data caveat twice, but little of it is filler for a tool whose output must be interpreted without an output 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-value meaning: blocked, planRestricted, online, lastSeenAt, platform selecting the shell dialect, GPU details, hostname and local IPs, including what omission of those fields does and does not mean. An agent has everything needed to call and interpret it.

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?

No parameters exist, so the baseline is 4; the closing 'Takes no arguments' merely confirms the empty schema. The description instead spends its budget on interpreting returned fields, which is the right trade for a zero-arg 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?

Opens with a specific verb and resource: list ALL of the user's saved machines, including access state and live status. It also names the sibling it defers to (session_status) when there is no account, so an agent can place it in the toolset without opening a 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?

Explicit routing: 'USE THIS for fleet-wide questions or when the user has not named a machine yet', plus the exclusion that without account auth there is no list and the agent must fall back to session_status with a specific AIC- code. It also states the preconditions for the list existing (free account sign-in, linking a machine via the agent).

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

All mcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?