ChannelTerm

Overview Schema Source Related Servers Discussions Admin

Start User-Space Debugging

debug_start

DestructiveIdempotent

Start a native Linux GDB/MI debug session on an idle Bash session via an exclusive managed lease, launching an ELF or attaching to an isolated PID.

Instructions

Start native Linux user-space GDB/MI on an idle Bash Session using an exclusive managed lease. ChannelTerm, GDB, gdbserver, and ELF must share one Linux environment. PID omitted launches with isolated I/O; attach rejects controlling terminals, pipes, sockets, or shared character devices. Single inferior, multithreaded, all-stop only. Reuse owner and request_id unchanged to retry.

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": {
      "owner": "<owner>",
      "session_id": "<session_id>",
      "request_id": "<request_id>",
      "elf": "<elf>"
    },
    "name": "debug_start"
  }
}

Input Schema

Name	Required	Description
`elf`	Yes	Absolute executable ELF path; must match native Linux architecture and attached /proc/PID/exe.
`gdb`	No	Absolute executable path; defaults to executable found on Host PATH.
`pid`	No	Existing isolated process PID; omit or zero to launch. Attach never permits terminate.
`args`	No	Launch arguments; at most 128. No shell expansion.
`owner`	Yes	Secret random capability, 32..128 characters; retain for retries and all calls. Never publish it in events.
`gdbserver`	No	Absolute executable path; defaults to executable found on Host PATH.
`request_id`	Yes	Unique start request ID, 1..128 characters. Conflicting reuse is rejected.
`session_id`	Yes	Active Session ID or short reference.

Output Schema

Name	Required	Description	Default
`status`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.2Oct 25, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the bar is lower, yet the description still adds real substance: exclusive managed lease semantics, the shared-environment requirement, attach-mode rejection rules, the single-inferior/multithreaded/all-stop limitation, and the idempotency mechanism (unchanged owner + request_id). The notable gap is that for a destructiveHint=true tool it never says what is destroyed or what happens to an existing debug session, and it does not mention lease expiry or concurrency conflicts.

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?

Four dense sentences with no filler, front-loaded with the core action and mechanism before the constraints and retry note. The tradeoff is terseness bordering on cryptic ('ChannelTerm, GDB, gdbserver, and ELF must share one Linux environment'), which costs a read or two but wastes no words.

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?

An output schema exists, so return values need no explanation, and the description covers the two operating modes, environment preconditions, and retry semantics for a tool with a destructive, leased, open-world profile. It falls short on failure modes and on the lifecycle after start (which siblings to call next, what debug_stop or lease release does to the session).

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?

With 100% schema description coverage the baseline is 3, and the description earns above that by adding behavior the schema does not: that omitting PID launches with isolated I/O, the attach rejection conditions, and the retry contract for owner/request_id. It still doesn't clarify the gdb/gdbserver default resolution or the 128-argument cap, but those are already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Start native Linux user-space GDB/MI on an idle Bash Session using an exclusive managed lease' — plus the exact environment constraint (ChannelTerm/GDB/gdbserver/ELF must share one Linux environment). An agent knows precisely what is being created. It does not, however, name or differentiate itself from the obvious siblings debug_bridge_start or debug_command, so the agent must infer the boundary between user-space GDB/MI debugging and the bridge tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The launch-vs-attach split is spelled out conditionally ('PID omitted launches with isolated I/O; attach rejects controlling terminals, pipes, sockets, or shared character devices'), and the retry path is explicit ('Reuse owner and request_id unchanged to retry'). What is missing is routing guidance against alternatives: nothing says when to pick this over debug_bridge_start or when to follow with debug_command/debug_stop. Usage is implied by the constraints rather than stated as when-to-use.

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

Deploy Server