ChatGPT–DSH Bridge

Overview Schema Source Related Servers Discussions Admin

Start a DSH coding task

dsh_start_task

Destructive

Starts an asynchronous headless DSH coding task in a specified absolute workspace, read-only by default; enable workspace writes only with a local write grant.

Instructions

Start an asynchronous headless DSH task in an absolute workspace. Permission mode: read-only (default; cannot write) or workspace-write (requires allow_write=true plus a valid local write grant for this exact workspace). The write grant is created locally; no token is sent to the model. danger-full-access is intentionally unavailable. The default is read-only. Use this only when local work is actually needed, not for ordinary conversation. Poll with dsh_get_status/dsh_get_result using wait_seconds instead of tight loops.

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": {
      "task": "<task>",
      "workspace": "<workspace>"
    },
    "name": "dsh_start_task"
  }
}

Input Schema

Name	Required	Description	Default
`task`	Yes	The concrete task for DSH. Include scope, acceptance checks, and constraints.
`title`	No	Short human-readable label for the task.
`workspace`	Yes	Absolute path to the project directory. DSH runs with this as its cwd.
`allow_write`	No	Set true only when the user requested file modifications. A local write grant is still required; no token is accepted or needed.
`permission_mode`	No	read-only is the default. workspace-write requires allow_write=true plus a valid local write grant for this workspace.	read-only
`timeout_seconds`	No	Maximum runtime in seconds. Bounded by the bridge config.

Output Schema

Name	Required	Description	Default
`ok`	Yes
`next`	No
`task`	Yes
`message`	No
`terminal`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds the material context an agent needs before a mutating call: the two permission modes, the default of read-only, that workspace-write requires allow_write=true plus a valid local write grant for that exact workspace, that danger-full-access is deliberately unavailable, and that no token is sent to the model. The async nature and subsequent polling requirement are also disclosed, none of which is derivable from the annotations alone.

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?

It is front-loaded with the action and workspace, then permissions, then usage constraints, so the important information appears first. The only waste is the redundant restatement of the read-only default, which appears once in the permission-mode parenthetical and again as a standalone sentence.

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 present, return values need not be described, and the async lifecycle and permission model are covered well. The remaining minor gap is that cancellation or failure handling (via dsh_cancel_task) and the meaning of timeout expiry are never mentioned, which matters for a long-running async task.

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 earns above that by explaining the coupling between allow_write and permission_mode and the local-grant prerequisite, which is behavioral meaning a per-field schema string cannot convey. It stops short of 5 because it restates the read-only default already present in the permission_mode schema description and adds nothing about timeout_seconds or title.

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 first sentence names a specific verb and resource ('Start an asynchronous headless DSH task') and pins the scope to an absolute workspace. It is immediately distinguishable from dsh_get_status/dsh_get_result/dsh_cancel_task, which are named as the polling path instead. An agent knows exactly what this call does without opening the 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?

It gives an explicit positive condition (local work is actually needed) and an explicit exclusion ('not for ordinary conversation'). It also routes the agent to the correct sibling pattern ('Poll with dsh_get_status/dsh_get_result using wait_seconds instead of tight loops'), which is the main misuse risk for an async task starter.

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

Deploy Server