Skip to main content
Glama

oc_agents

List available local OpenClaw agents, including names, aliases, default status, and execution risk, so you can confirm valid agent identifiers before dispatching tasks.

Instructions

列出本机 OpenClaw 可用的 agent:id、名字、别名、是否默认、execRisk(allow=可落地动作,deny=只读或纯回复)。agent 名单来自本机的 config.json,每台机器都不同——用户提到某个名字、或你不确定能点名谁时,先调本工具确认,不要凭猜测点名。返回的 name 或 aliases 可以直接当作其他工具的 agent 参数。结果缓存 60 秒,refresh=true 强制刷新。Gateway 不在时返回 GATEWAY_UNAVAILABLE。语音场景只报名字和默认 agent,不要把 JSON 读出来。

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

Input Schema

NameRequiredDescriptionDefault
refreshNo强制刷新缓存,重新从 Gateway 获取 agent 列表。

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full disclosure burden and does so: cached results for 60 seconds, refresh=true to bypass the cache, a named failure mode (GATEWAY_UNAVAILABLE), the config.json source, and per-machine variance. It even prescribes output handling for voice contexts ('report only names and the default agent, don't read the JSON aloud'), which is behavioral detail an agent could not infer from the schema.

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 content is dense and front-loaded: purpose and returned fields come first, usage rule second, cache and error semantics last. Every sentence carries information, though it is delivered as one long run-on paragraph where error handling and voice-mode guidance could be visually separated for faster scanning.

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, yet the description compensates by enumerating the returned fields, their semantics (execRisk allow/deny), the error state, caching behavior, and how to reuse the returned identifiers. Nothing an agent needs in order to call this correctly and interpret the result is missing.

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

Parameters4/5

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

Schema coverage is 100% for the single refresh parameter, so the baseline is 3. The description adds value beyond the schema by stating the 60-second cache window, which explains when forcing a refresh is actually warranted, plus the GATEWAY_UNAVAILABLE outcome that makes a retry-with-refresh decision meaningful.

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 verb and resource ('list the agents available on this machine') and then enumerates exactly what comes back: id, name, aliases, default flag, and execRisk with its allow/deny meaning interpreted for the agent. It also states the data source (local config.json, machine-specific), which clearly separates this discovery tool from siblings like oc_run or oc_wait.

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 gives an explicit trigger ('when the user mentions a name, or you are unsure who you can name, call this tool first') and an explicit prohibition ('do not guess names'). It also explains the downstream use of the output ('name or aliases can be passed directly as the agent parameter to other tools'). It does not name a sibling as an alternative path, but no sibling here is a real substitute for discovery, so the routing guidance is effectively complete.

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