Skip to main content
Glama

Dispatch task

dsh_send
Destructive

Dispatch a task to a conversation. Give a goal, not commands: DSH decides which file, shell, search, skill, subagent and team tools to use, and this server does not preload or proxy DSH's tool surface.

Instructions

Dispatch a task to a conversation. Give a goal, not commands: DSH decides which file, shell, search, skill, subagent and team tools to use, and this server does not preload or proxy DSH's tool surface. Non-blocking by default (wait=false): it returns run_id + sentinel_file at once, the turn runs in the background and you are notified when it ends, so you can do other work and the task is never cut off by a timeout. Pass wait=true to block for the result (optionally with timeout_ms; on expiry it only moves to the background and does not cancel the turn). [A timeout never destroys the task] when wait=true reaches timeout_ms before the turn ends, this tool does not error and does not cancel: it downgrades to background, returns run_id + sentinel_file, and the turn runs to the end with the result delivered through the sentinel file (timeout_ms=0 means wait forever). In both modes a small file holding the final result is written atomically when the turn ends. Wait for it with a background task (Bash run_in_background + until [ -f sentinel_file ]; on Windows/PowerShell a Test-Path loop, and the receipt contains ready-made commands) and you are woken when it lands; no polling needed. Once the file exists, read it for the result, or collect with dsh_get(conversation_id, run_id); dsh_read shows output while the turn is running. Reasoning is hidden by default (answer plus reasoning statistics only). Results and background receipts carry a review ticket (advisory by default): verify, then submit a verdict with dsh_review. If the conversation is busy this tool errors: use dsh_send(queue=true) to enqueue (returns at once), dsh_interject to stop and redirect, or dsh_interrupt to just stop.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "conversation_id": "<conversation_id>",
      "prompt": "<prompt>"
    },
    "name": "dsh_send"
  }
}

Input Schema

NameRequiredDescriptionDefault
teamNoControls the experimental team hint for this dispatch. Pass false to suppress it for this call. From DSH 0.2.2-rc.2, DSH manages team tools and guidance per session.
waitNo**Default false**: return run_id + sentinel_file at once; the turn runs in the background and the sentinel file signals completion (recommended). true = block until the turn ends and return the full result.
queueNoWhether to enqueue when the conversation is busy (default false = error). With true it returns run_id + queue_position at once and runs after the current turn; the sentinel is written only when the run really ends, not when it is queued. Queued prompts stay in memory. After restart, unstarted receipts resolve as cancelled. Manage the queue with dsh_queue. (dsh_interject(mode='queue') also runs after the current turn, but it blocks until the new turn ends and does not use this queue.)
promptYesThe task. It may refer to file paths in the workspace.
reviewNoReview policy for this dispatch, overriding the conversation default (advisory). advisory: the result and sentinel carry a review ticket asking the caller to verify independently and submit a verdict with dsh_review; off: none this time.
reasoningNoHow much reasoning to return. Default hide (answer only, reasoning as statistics). full uses a lot of context.
timeout_msNoUpper bound on the **wait**, in milliseconds, only with wait=true. **Default 0 = wait forever** (no invented 30-minute limit). On expiry the turn is not cancelled; it moves to the background and you get a run_id.
client_run_idNoCaller-generated idempotency key (up to 128 characters, scoped to this conversation and retained with the sentinel). Submitting the same key again does not create a second run: it returns the first run's result or receipt (replayed=true). For safely resending after a response was lost in transport.
conversation_idYesConversation id, from dsh_start or dsh_list.

Output Schema

NameRequiredDescriptionDefault
queuedNo
run_idYes
statusNo
replayedNo
backgroundNo
sentinel_fileYes
conversation_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.5
    • changedInput schema / properties / team / description
      Previous value: -"Whether to prepend the \"form a team first when this needs parallel or multi-role work\" hint to this dispatch (default follows DSH_MCP_TEAM). false turns it off for this call only; DSH_MCP_TEAM=0 turns it off entirely."New value: +"Controls the experimental team hint for this dispatch. Pass false to suppress it for this call. From DSH 0.2.2-rc.2, DSH manages team tools and guidance per session."
  2. Changed3 schema fields changedv0.7.1
    • changedInput schema / properties / client_run_id / description
      Previous value: -"Caller-generated idempotency key (up to 128 characters, scoped to this conversation). Submitting the same key again does not create a second run: it returns the first run's result or receipt (replayed=true). For safely resending after a response was lost in transport."New value: +"Caller-generated idempotency key (up to 128 characters, scoped to this conversation and retained with the sentinel). Submitting the same key again does not create a second run: it returns the first run's result or receipt (replayed=true). For safely resending after a response was lost in transport."
    • changedInput schema / properties / queue / description
      Previous value: -"Whether to enqueue when the conversation is busy (default false = error). With true it returns run_id + queue_position at once and runs after the current turn; the sentinel is written only when the run really ends, not when it is queued. The queue is memory-only and lost on restart; manage it with dsh_queue. (dsh_interject(mode='queue') also runs after the current turn, but it blocks until the new turn ends and does not use this queue.)"New value: +"Whether to enqueue when the conversation is busy (default false = error). With true it returns run_id + queue_position at once and runs after the current turn; the sentinel is written only when the run really ends, not when it is queued. Queued prompts stay in memory. After restart, unstarted receipts resolve as cancelled. Manage the queue with dsh_queue. (dsh_interject(mode='queue') also runs after the current turn, but it blocks until the new turn ends and does not use this queue.)"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "background": {
      +      "type": "boolean"
      +    },
      +    "conversation_id": {
      +      "type": "string"
      +    },
      +    "queued": {
      +      "type": "boolean"
      +    },
      +    "replayed": {
      +      "type": "boolean"
      +    },
      +    "run_id": {
      +      "type": "string"
      +    },
      +    "sentinel_file": {
      +      "type": "string"
      +    },
      +    "status": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "conversation_id",
      +    "run_id",
      +    "sentinel_file"
      +  ],
      +  "type": "object"
      +}
  3. Changed9 schema fields changedv0.6.8
    • changedInput schema / properties / client_run_id / description
      Previous value: -"调用方生成的幂等键(≤128 字符,作用域=本会话)。重复提交同一个键不会创建第二个 run,而是返回首次 run 的结果或收据(replayed=true)。用于\"响应在传输层丢了、想安全重发\"的场景。"New value: +"Caller-generated idempotency key (up to 128 characters, scoped to this conversation). Submitting the same key again does not create a second run: it returns the first run's result or receipt (replayed=true). For safely resending after a response was lost in transport."
    • changedInput schema / properties / conversation_id / description
      Previous value: -"会话 id,来自 dsh_start 或 dsh_list。"New value: +"Conversation id, from dsh_start or dsh_list."
    • changedInput schema / properties / prompt / description
      Previous value: -"任务描述。可以引用工作区里的文件路径。"New value: +"The task. It may refer to file paths in the workspace."
    • changedInput schema / properties / queue / description
      Previous value: -"会话正忙时是否入队(默认 false = 直接报错)。true 时立即返回 run_id + queue_position,本轮结束后自动执行;哨兵只在真正结束时写,入队时不写。队列仅内存、重启丢失,用 dsh_queue 管理。(dsh_interject(mode='queue') 也排在本轮之后,但它会阻塞到新回合跑完,且不进这个队列。)"New value: +"Whether to enqueue when the conversation is busy (default false = error). With true it returns run_id + queue_position at once and runs after the current turn; the sentinel is written only when the run really ends, not when it is queued. The queue is memory-only and lost on restart; manage it with dsh_queue. (dsh_interject(mode='queue') also runs after the current turn, but it blocks until the new turn ends and does not use this queue.)"
    • changedInput schema / properties / reasoning / description
      Previous value: -"思考内容展示档位。默认 hide(只返回正文,思考只给统计)。full 会占用大量上下文。"New value: +"How much reasoning to return. Default hide (answer only, reasoning as statistics). full uses a lot of context."
    • changedInput schema / properties / review / description
      Previous value: -"本次派活的审核策略,覆盖会话默认(默认 advisory)。advisory:结果/哨兵附审核单,提示调用方独立核验后用 dsh_review 提交裁决;off:本次不附。"New value: +"Review policy for this dispatch, overriding the conversation default (advisory). advisory: the result and sentinel carry a review ticket asking the caller to verify independently and submit a verdict with dsh_review; off: none this time."
    • changedInput schema / properties / team / description
      Previous value: -"是否在本次派发前注入\"需要并行/多角色时先建团队\"的提示(默认跟随 DSH_MCP_TEAM,0.4.0 起默认开)。传 false 只对这一次关闭;彻底关闭用 DSH_MCP_TEAM=0。"New value: +"Whether to prepend the \"form a team first when this needs parallel or multi-role work\" hint to this dispatch (default follows DSH_MCP_TEAM). false turns it off for this call only; DSH_MCP_TEAM=0 turns it off entirely."
    • changedInput schema / properties / timeout_ms / description
      Previous value: -"仅 wait=true 时的**等待**上限(毫秒),**默认 0 = 一直等**(不会凭空发明 30 分钟)。到期不会取消回合,只会转成后台并给你 run_id。"New value: +"Upper bound on the **wait**, in milliseconds, only with wait=true. **Default 0 = wait forever** (no invented 30-minute limit). On expiry the turn is not cancelled; it moves to the background and you get a run_id."
    • changedInput schema / properties / wait / description
      Previous value: -"**默认 false**:立即返回 run_id + sentinel_file,回合在后台跑,跑完由哨兵文件通知(推荐用法)。true = 原地阻塞到回合结束再返回完整结果。"New value: +"**Default false**: return run_id + sentinel_file at once; the turn runs in the background and the sentinel file signals completion (recommended). true = block until the turn ends and return the full result."
  4. Changed1 schema field changedv0.6.5
    • changedInput schema / properties / queue / description
      Previous value: -"会话正忙时是否入队(默认 false = 直接报错)。true 时立即返回 run_id + queue_position,本轮结束后自动执行;哨兵只在真正结束时写,入队时不写。队列仅内存、重启丢失,用 dsh_queue 管理。"New value: +"会话正忙时是否入队(默认 false = 直接报错)。true 时立即返回 run_id + queue_position,本轮结束后自动执行;哨兵只在真正结束时写,入队时不写。队列仅内存、重启丢失,用 dsh_queue 管理。(dsh_interject(mode='queue') 也排在本轮之后,但它会阻塞到新回合跑完,且不进这个队列。)"
  5. Changed5 schema fields changedv0.5.1
    • addedInput schema / properties / client_run_id
      Added value: +{
      +  "description": "调用方生成的幂等键(≤128 字符,作用域=本会话)。重复提交同一个键不会创建第二个 run,而是返回首次 run 的结果或收据(replayed=true)。用于\"响应在传输层丢了、想安全重发\"的场景。",
      +  "maxLength": 128,
      +  "type": "string"
      +}
    • addedInput schema / properties / queue
      Added value: +{
      +  "description": "会话正忙时是否入队(默认 false = 直接报错)。true 时立即返回 run_id + queue_position,本轮结束后自动执行;哨兵只在真正结束时写,入队时不写。队列仅内存、重启丢失,用 dsh_queue 管理。",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / review
      Added value: +{
      +  "description": "本次派活的审核策略,覆盖会话默认(默认 advisory)。advisory:结果/哨兵附审核单,提示调用方独立核验后用 dsh_review 提交裁决;off:本次不附。",
      +  "enum": [
      +    "off",
      +    "advisory"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / team
      Added value: +{
      +  "description": "是否在本次派发前注入\"需要并行/多角色时先建团队\"的提示(默认跟随 DSH_MCP_TEAM,0.4.0 起默认开)。传 false 只对这一次关闭;彻底关闭用 DSH_MCP_TEAM=0。",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / timeout_ms / description
      Previous value: -"仅 wait=true 时的**等待**上限(毫秒),默认 30 分钟;0 = 一直等。到期不会取消回合,只会转成后台并给你 run_id。"New value: +"仅 wait=true 时的**等待**上限(毫秒),**默认 0 = 一直等**(不会凭空发明 30 分钟)。到期不会取消回合,只会转成后台并给你 run_id。"
  6. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Goes well beyond the annotations: it discloses that timeout expiry does not cancel the turn and downgrades to background, that a sentinel file is written atomically at turn end, that a busy conversation errors by default, that queued prompts are in-memory and resolve as cancelled after restart, and that reasoning is hidden by default. Given destructiveHint=true and openWorldHint=true, it does not explain what state a dispatch can change or what permissions are required to send into a conversation, which is the remaining gap. It is consistent with idempotentHint=false while documenting client_run_id as an opt-in idempotency key.

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

Conciseness3/5

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

The most important information (give a goal not commands, non-blocking default) is front-loaded and bolded, which helps scanning. However, the timeout-no-cancel behavior is stated three separate times ('on expiry it only moves to the background', 'A timeout never destroys the task', 'does not error and does not cancel'), and bracketed emphasis plus varied bold makes it denser than it needs to be. It is efficient in coverage but not in wording.

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 nine-parameter dispatch tool with a mutation profile and an existing output schema, the description supplies everything an agent needs: dispatch semantics, both waiting modes, the sentinel mechanics, the review ticket loop, and the busy/queue decision tree. Return-value detail is appropriately delegated to the output schema rather than duplicated.

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%, so every one of the nine parameters is already documented in the schema, and the description largely restates those same semantics (timeout_ms=0 waits forever, queue default false, reasoning default hide). It adds some cross-parameter interplay — timeout_ms only applies with wait=true, and the sentinel is written only when a queued run actually ends — but that is marginal over an already-complete schema. Baseline 3 holds.

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 ('Dispatch a task to a conversation') and immediately scopes the request style ('give a goal, not commands') so the agent understands it is handing off autonomy, not calling tools itself. It distinguishes itself from dsh_interject, dsh_interrupt, dsh_get, dsh_read, dsh_queue and dsh_review by name, so an agent can route correctly without opening other schemas.

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 when-to-use guidance: wait=false by default with notification, wait=true to block, queue=true when the conversation is busy, dsh_interject to stop-and-redirect, dsh_interrupt to just stop, dsh_get to collect. It even names the tooling pattern for waiting (Bash run_in_background until the sentinel exists) and the Windows/PowerShell variant.

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