Skip to main content
Glama

List conversations

dsh_list
Read-onlyIdempotent

List conversations with live state—running, idle, or detached—so you can track several agents at once. Filter to active turns or include closed disk sessions to see what is running and what can resume.

Instructions

List conversations and their live state, for keeping track of several at once. state: running (a turn is in progress) / idle (process alive, nothing running) / detached (no process; resumable). A running conversation also reports elapsed time, the tool it is executing and how much it has output this turn. Two sources are merged: conversations this server holds, and ones on DSH's disk that are not open (DSH's session/list leaves out open sessions). Pass only_running=true for just the active ones; follow up with dsh_read to see what one is producing.

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

Input Schema

NameRequiredDescriptionDefault
cwdNoOnly conversations in this workspace.
only_runningNoOnly return conversations with a turn in progress. Default false. **This mode skips the disk probe and answers in milliseconds** (a running conversation is always in memory).
include_closedNoWhether to include conversations on disk that are not open (including ones created by other instances or the GUI). Default true. **Cost: it spawns a DSH process to probe the disk, about 1 second measured** (cached for 10 seconds). Pass false to list only what this server has open, in milliseconds.

Output Schema

NameRequiredDescriptionDefault
countYes
runningYes
probe_okNo
probe_errorNo
probe_cachedNo
conversationsYes
orphan_holdersNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.6.8
    • changedInput schema / properties / cwd / description
      Previous value: -"只看某个工作区下的会话。"New value: +"Only conversations in this workspace."
    • changedInput schema / properties / include_closed / description
      Previous value: -"是否包含磁盘上未打开的会话(含别的实例 / GUI 建的),默认 true。**代价:要 spawn 一个 DSH 进程去探测磁盘,实测约 1 秒**(结果缓存 10 秒)。只列本服务已打开的会话就传 false,毫秒级。"New value: +"Whether to include conversations on disk that are not open (including ones created by other instances or the GUI). Default true. **Cost: it spawns a DSH process to probe the disk, about 1 second measured** (cached for 10 seconds). Pass false to list only what this server has open, in milliseconds."
    • changedInput schema / properties / only_running / description
      Previous value: -"只返回正在跑回合的会话,默认 false。**此模式自动跳过磁盘探测,毫秒级**(正在跑的会话必然在内存里)。"New value: +"Only return conversations with a turn in progress. Default false. **This mode skips the disk probe and answers in milliseconds** (a running conversation is always in memory)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "conversations": {
      +      "items": {
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "count": {
      +      "type": "integer"
      +    },
      +    "orphan_holders": {
      +      "items": {
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "probe_cached": {
      +      "type": "boolean"
      +    },
      +    "probe_error": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "probe_ok": {
      +      "type": [
      +        "boolean",
      +        "null"
      +      ]
      +    },
      +    "running": {
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "count",
      +    "running",
      +    "conversations"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already establish the safe-read profile, and the description still adds substantial depth: the three states and their meanings, what a running conversation reports (elapsed time, executing tool, turn output), the merge of in-memory and on-disk sessions, and the noted gap in DSH's own session/list. This is behavior an agent could not infer from readOnlyHint/idempotentHint.

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 action, then state vocabulary, then the source-merge caveat, then the call advice. Dense but every clause carries information; the only mild redundancy is restating the only_running advice that the schema also covers.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema and full parameter coverage, the description only needs to supply operating context, and it does: merge semantics, state meanings, latency tradeoff, and the handoff to dsh_read. Minor residual gaps (failure behavior if the disk probe's DSH process errors) are low-impact.

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

Parameters3/5

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

Schema coverage is 100% and the schema already documents cwd, only_running, and include_closed, including the probe-cost tradeoff. The description reinforces only_running and the state vocabulary but adds no syntax or format detail beyond the structured fields, so the baseline 3 applies.

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?

States a specific verb and resource ('List conversations and their live state') and immediately scopes it to tracking several at once. It explains the two merged sources and explicitly points to dsh_read for content, so an agent can separate this from dsh_read/dsh_status without opening schemas.

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?

Gives clear selection guidance: pass only_running=true for active conversations, and follow up with dsh_read to see output. The alternative is named with its condition. It stops short of an explicit exclusion (e.g., 'do not use when you already know a single session id'), so a 4 rather than a 5.

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