dsh-baton

Overview Schema Source Related Servers Discussions Admin

dsh_wait

Read-onlyIdempotent

Wait for runs sent with dsh_send to finish and return their state and final reply, including when a run stops to ask a person. Wait on multiple run ids at once and continue with the returned cursor.

Instructions

Wait for a run sent with dsh_send to end and return its state and final reply. Prefer the background wait_command from dsh_send if your client wakes you when a background command exits: it costs no turns. It also returns at once when the run stops to ask a person: needs_input answer (reply with dsh_answer) or harness-ui (an approval in the Harness window). Each call waits up to 50 s; if it returns timed_out: true, call dsh_wait again with the same run_id, without a progress note. Parallel runs: all ids in run_ids, never one by one; returns once any ends or asks (ended; the rest in still_running); then wait again with the rest plus your fixes. A run in a session with a Harness goal is followed on until the goal stops, with every round since the run began. With session_id instead of run_id it follows that session's Harness goal (see until) without sending anything; it also returns when Harness needs a person or will not go on by itself. Pass back the cursor each result gives.

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_wait"
  }
}

Input Schema

Name	Required	Description
`until`	No	Harness goal: goal (default) reports once when it stops; turn (only if the user asked for progress reports) at a round end once every_minutes passed since the last report, with every round since
`cursor`	No	The cursor from the previous result (nothing is reported twice or missed)
`run_id`	No	Run id from dsh_send
`run_ids`	No	Several run ids, to wait for whichever ends first
`session_id`	No	Follow this session's Harness goal instead of waiting for a run (no message is sent)
`every_minutes`	No	With until turn: least minutes between reports

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.6.11Nov 10, 2026

changedInput schema / properties / cursor / description

Previous value: -"The cursor from the previous result, so nothing is reported twice or missed (also when switching until)"New value: +"The cursor from the previous result (nothing is reported twice or missed)"

addedInput schema / properties / run_ids

Added value: +{
+  "description": "Several run ids, to wait for whichever ends first",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed5 schema fields changedNov 3, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "The cursor from the previous result, so nothing is reported twice or missed (also when switching until)",
+  "type": "string"
+}

addedInput schema / properties / every_minutes

Added value: +{
+  "default": 10,
+  "description": "With until turn: least minutes between reports",
+  "type": "integer"
+}

addedInput schema / properties / session_id

Added value: +{
+  "description": "Follow this session's Harness goal instead of waiting for a run (no message is sent)",
+  "type": "string"
+}

addedInput schema / properties / until

Added value: +{
+  "description": "Harness goal: goal (default) reports once when it stops; turn (only if the user asked for progress reports) at a round end once every_minutes passed since the last report, with every round since",
+  "enum": [
+    "goal",
+    "turn"
+  ],
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "run_id"
-]
```

First observedv0.5.4Oct 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare this a safe, idempotent read, and the description adds substantial behavior beyond them: a 50-second per-call cap, the timed_out/retry loop, early return when a run asks for a person (needs_input or harness-ui), any-of-N semantics for run_ids with the remainder in still_running, and cursor-based continuation with no duplication or gaps. Nothing here contradicts readOnlyHint or 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 primary behavior and dense with operational detail rather than filler, which suits a tool with this much conditional behavior. A few sentences are hard to parse on first read, notably 'A run in a session with a Harness goal is followed on until the goal stops, with every round since the run began,' which could be tightened without losing content.

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?

For a six-parameter tool with no output schema, the description still covers the return values an agent must branch on (timed_out, needs_input, harness-ui, ended, still_running, cursor) as well as all invocation modes. An agent can drive the full wait/retry/answer loop from this text alone.

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 the baseline is 3; the description still adds real meaning by explaining how run_id, run_ids, and session_id are mutually exclusive modes, and by emphasizing that the cursor must be passed back because 'nothing is reported twice or missed'. The 'rest in still_running' and 'rest plus your fixes' framing further clarifies how run_ids is expected to be re-invoked.

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 opening sentence states a specific verb and resource ('Wait for a run sent with dsh_send to end') and names the return payload ('state and final reply'). It immediately differentiates itself from dsh_send's background wait_command, so an agent can choose between them 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 is given: prefer the background wait_command from dsh_send when the client wakes on exit, use dsh_wait otherwise; use dsh_answer for needs_input; use run_ids for parallel runs, 'never one by one'; use session_id to follow a goal. Retry behavior on timed_out is spelled out, including the instruction not to add a progress note.

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

Deploy Server