docent-terminal-mcp

session_create

Start a terminal session for interactive programs or long-running tasks; logs all output and allows human observation and takeover. Use instead of one-shot shell calls when a prompt is needed.

Instructions

Start a terminal session: a tmux pane a human can watch or type into, whose output is logged in full and kept as numbered regions. Use one instead of a one-shot shell call for anything that runs a program with a prompt (gdb, python, ssh, any REPL), takes more than a few seconds (a build, a testsuite), prints more than a reply holds, may ask a question (y/n), or that the user may want to watch or take over; a one-shot call stays right for reading and editing files and for quick commands whose whole output you want. Open one at the start of a task and do the task's shell work in it with the run tool: sessions are cheap, keep running between calls and across your own restarts (session_list finds them), and keep their cwd, environment and running programs -- cd once, start gdb once.

With no command (or "bash"), the session is bash with shell integration: exact command boundaries and exit statuses, and programs are started from it with the run tool (make, gdb, python, ssh, ...). command runs another program as the session itself instead, e.g. "gdb -q -ex 'break main' -ex run ./prog" or "ssh host"; when it exits the session is over. One session per job is the usual shape: a shell for the build and the tests, a second one for gdb while the first is busy.

Tell the user the session's name and attach command (in the reply) on a line of its own, so they can watch or step in. First time here: load the terminal-sessions skill if one is listed, else guide.

By default the pane follows the window of a human who attaches, so cols/rows apply only until then; fixed_size keeps them (the human then sees the pane clipped or padded). session_resize changes either later.

Input Schema

TableJSON Schema

Name	Required	Description
`cwd`	No	working directory (default: the server process's own)
`env`	No	environment variables set in the session, on top of the server's environment
`cols`	No	terminal width in columns
`name`	No	a name for the session (default: t1, t2, ...); the name of a closed session archives its old logs
`rows`	No	terminal height in rows
`command`	No	the program to run instead of bash with shell integration, e.g. "gdb -q ./prog" or "ssh host"; "bash" or "zsh" (with -i/-l) is that shell with the integration, "bash --norc" or "zsh -f" a plain one
`fixed_size`	No	keep cols x rows even when a human attaches (the default lets the pane follow their window)
`prompt_pattern`	No	the session's default prompt regex for `run`/`expect` into a program; not for bash, and rarely needed (see `run`)
`delete_logs_on_close`	No	delete the session's logs when it closes, for one that may show something sensitive (see session_logs)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so: sessions are cheap, persist between calls and across agent restarts, retain cwd/environment/running programs, and are discoverable via `session_list`. It also discloses non-obvious behavior such as the pane following the human's window unless `fixed_size` is set, and that a `command` session ends when the program exits.

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 core purpose and the use/don't-use rule before the mechanics. It is long and dense with parentheticals, but nearly every sentence carries operational information for a genuinely complex tool; there is little outright padding.

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?

An output schema exists, so return values need no explanation, and all 9 parameters are covered by the schema. The description supplies the surrounding context an agent needs — lifecycle, persistence, human-attach behavior, and pointers to sibling tools (`run`, `session_list`, `session_resize`, `session_logs`, `guide`).

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, but the description adds real meaning: `command` semantics (bash/zsh with integration vs plain vs arbitrary program, and that session ends on exit), `cols`/`rows` applying only until a human attaches, and `name` defaults plus the archiving behavior of reused names. It stops short of explaining `env`, `prompt_pattern`, or `delete_logs_on_close` beyond what the schema already says.

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 ('Start a terminal session') and immediately defines the resource as a tmux pane a human can watch or type into, with full logging and numbered regions. It explicitly distinguishes itself from a one-shot shell call, so an agent can tell it apart from `run`/`shell_integrate` 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?

Gives explicit when-to-use criteria (programs with a prompt like gdb/python/ssh/REPLs, long-running builds or testsuites, output larger than a reply, may ask y/n, user may want to watch) and explicit when-not (one-shot calls stay right for reading/editing files and quick commands). It also prescribes the workflow: open one at task start, do shell work via `run`, one session per job.

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

Deploy Server