The SmartCLI MCP server lets agents spawn, perceive, drive, and tear down real terminal/TUI programs through persistent PTY sessions.
Session management: Start detached, persistent sessions for commands (REPLs, vim, htop, lazygit) with configurable cwd/env/size; list, check alive status, resize, and close them.
Perceive the screen: Get semantic snapshots with rendered text, alt-screen status, content hash, visual hash, and optional structured cell/cursor JSON.
Send input: Type literal text without Enter, send full lines with Enter, or send named key tokens and combos (arrows, Ctrl/Meta, function keys) for navigation and control.
Wait/synchronize: Block until a regex matches, any of several patterns matches, screen content changes, visual state changes, or the screen becomes ready/stable — avoiding blind sleeps.
Confirm actions: Use returned hashes as change-detection baselines and snapshot after acting to verify that keystrokes actually landed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SmartCLI Drive lazygit in a terminal and show me the latest commit diff"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Python · MIT · ★4
Read this in: English · 简体中文 · 繁體中文 · 日本語 · 한국어
A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + pyte core.
Let an AI drive, perceive, and render real terminal programs. SmartCLI reads
the actual screen with a pyte cell model — not a byte pipe — so it knows which
menu row is highlighted, presses the right keys, and waits for the screen to
settle. Below: it drives the real lazygit TUI end-to-end (arrow-key
navigation, opening a commit diff, highlighting a branch) — no script, no mock.
pip install smartcli-toolkitRequires Python 3.10 or newer. The install includes the shared Python library, the persistent TUI driver, and the stdio MCP server.
Copy-paste this. It starts a real Python REPL under a PTY, waits for the prompt
(never a blind sleep), types into it, and reads the screen back:
pip install smartcli-toolkit
SID=$(smartcli-tui start --cmd "python3 -i -q" --cols 80 --rows 24 --json | python3 -c "import json,sys;print(json.load(sys.stdin)['sid'])")
smartcli-tui wait-regex --id $SID ">>> " --timeout-ms 15000
smartcli-tui send-line --id $SID "print(6*7)"
smartcli-tui wait-regex --id $SID "42" # prints the cell grid it sees
smartcli-tui close --id $SIDOn Windows use --cmd "py -i -q". Swap the command for vim, htop or
lazygit and the same five verbs drive those too — that is the whole point:
wait-regex and friends react to what the screen actually shows, so an agent
never guesses whether its keystroke landed.
Want the same thing against a real editor, end to end and verifiable?
examples/drive_vim.py drives the actual vim binary —
opens a file, appends a line, saves, and then checks the filesystem, not the
screen:
python examples/drive_vim.py
# [OK ] vim painted its screen
# [OK ] file contents visible on screen
# [OK ] alternate screen is active
# [OK ] vim entered insert mode (so G and o both landed)
# [OK ] typed text appears on screen
# [OK ] vim restored the main screen on exit
# [OK ] file on disk really changedNote the fourth step. It is there because the example itself once sent five
keystrokes back to back with nothing between them, and under load vim had not
processed G by the time o arrived, so nothing was inserted and the run failed
with no useful diagnosis. Confirming insert mode proves both keys landed — the
same discipline the tool exists to provide, applied to its own demo.
Run the same file against smartcli-toolkit==0.1.8 and two steps fail — and the
file is never saved, because a driver that cannot see the alternate screen
mistimes the :wq. That is why the emulation work below matters: a wrong screen
model does not error, it silently succeeds at nothing.
Already running an MCP client (Claude Code, Cursor, VS Code)? The same verbs are MCP tools, with the per-session token attached for you:
smartcli-mcp # stdio MCP server; or `uvx --from smartcli-toolkit smartcli-mcp`SmartCLI is a workspace for terminal work that agents and humans both do: driving
interactive terminal programs, perceiving what a screen actually shows, and
rendering visuals and layouts back out. It is built on one shared, pluggable PTY
backend plus a pyte screen model — chosen over screenshot/vision so a single
structured screen model feeds both perception (read the screen) and rendering
(draw the screen). The PTY layer is intentionally not tmux-bound: local dev runs
on Windows via ConPTY (pywinpty), while target programs can run under POSIX ptys
or tmux elsewhere. Three skills sit on that core, each a self-contained tool you run
in place from the checkout.
Related MCP server: Forge
The demo above is SmartCLI driving lazygit — a real full-screen curses app —
through its perceive → act → confirm loop: it reads the pyte cell grid (which
row is selected, the alt-screen diff), moves with arrow keys, opens a commit's
diff, and highlights a branch. Captured by driving the actual program in a Linux
container, not scripted or mocked. A byte-stream matcher like pexpect can't
perceive "which row is highlighted"; a screen model can.
How we know the perception is right. A screen model is only useful if it
matches what a real terminal shows, so we measure that instead of asserting it:
identical bytes go to a real tmux pane and to our model, and the two cell
grids are diffed. Three suites do it — 34 curated cases, a three-way check that
only trusts a behaviour when tmux and GNU screen agree, and a generative
fuzz over random VT sequences. That campaign found and fixed 12 emulation bugs,
including the alternate screen buffer (pyte implements none of modes
1049/1047/47, so a full-screen program's output used to be painted over the main
screen and never restored). Scope and remaining edges:
LIMITATIONS.md.
Real captures of the cmd-art fx engine — each GIF is the actual effect
rendered frame-by-frame through the project's own pipeline (no screen recorder).
Reproduce any with python -m fx play <name> (see Quickstart).
|
|
|
donut — the classic ASCII torus | fire — demoscene heat field | rain — Matrix digital rain |
🌐 Explore the live showcase → — play with the effect engine, drive a menu with arrow keys, and poke the widgets, right in your browser.
Just want the three Claude Code skills? Download one zip, unzip it, done — no git, no pip, no marketplace:
curl -LO https://github.com/dwgx/SmartCLI/releases/latest/download/smartcli-skills.zipunzip smartcli-skills.zip -d ~/.claude/skills/That gives you cmd-art, drive-tui and tui-ui (309 KiB total). cmd-art and
tui-ui then work with nothing but CPython 3.10+ — verified on a bare virtualenv,
all 30 effects and all 17 widgets load. drive-tui additionally needs pyte, which
the PyPI install below provides. Or install all three via the plugin marketplace:
/plugin marketplace add dwgx/SmartCLI.
Primary — from PyPI (the library, the CLI, and the MCP server):
pip install smartcli-toolkitDistribution vs import name: the PyPI distribution is
smartcli-toolkit(the namessmartcli/smart-cliwere taken or blocked), but the importable package issmartcli_core. So afterpip install smartcli-toolkityou still writefrom smartcli_core import PtySession.
Alternative — reproduce the full dev environment from a source checkout:
git clone https://github.com/dwgx/SmartCLI SmartCLI
cd SmartCLI
python -m pip install -r requirements.txtrequirements.txt installs pyte, the MCP SDK, and pywinpty on Windows only
(POSIX uses the stdlib pty backend). pip install . installs smartcli_core
plus the smartcli-tui, smartcli-mcp, and smartcli-toolkit commands. The
visual cmd-art and tui-ui skills still run in place from a checkout via
python -m fx and python -m ui.
Optional extras (real FIGlet fonts, raster images, authoritative cell widths — all degrade gracefully to stdlib fallbacks when absent):
python -m pip install -r requirements-optional.txt
# or, from the checkout, via pyproject extras:
pip install ".[all]" # pyfiglet + Pillow + wcwidth
pip install ".[art]" # pyfiglet only
pip install ".[image]" # Pillow only (also: the PNG screenshot harness needs it)
pip install ".[width]" # wcwidth onlyWindows note: set UTF-8 output before running any skill so box-drawing and CJK glyphs encode cleanly (the CLIs also auto-reconfigure stdout, but set this to be safe):
set PYTHONIOENCODING=utf-8Verified dep versions on the dev box (Windows 11, CPython 3.14.6): pyte 0.8.2,
pywinpty 3.0.5, pyfiglet 1.0.4, Pillow 12.2.0, wcwidth 0.8.1.
Diagnostics. python -m smartcli_core prints your OS, Python, terminal, PTY
backend, and dependency versions. smartcli-tui doctor reports where the core
was loaded from and whether drive dependencies are present. Include both outputs
when filing a terminal-sensitive bug.
cd skills/cmd-art
python -m fx list # list all 30 effects
python -m fx play donut --seconds 5 # play one effect (bounded)
python -m fx gallery # one frame of each effect
python -m fx show --seq "donut:fire:3,plasma::3"cd skills/tui-ui
python -m ui widgets # list all 17 widgets
python -m ui gallery --width 100 --height 30
python -m ui demo table --width 80 --height 12 --theme dashboardPersistent-session CLI (state survives across shell calls):
smartcli-tui start --cmd "python3 -i -q" --cols 80 --rows 24
smartcli-tui wait-regex --id <SID> ">>> " --timeout-ms 15000
smartcli-tui send-line --id <SID> "print(6*7)"
smartcli-tui snapshot --id <SID>
smartcli-tui close --id <SID>On Windows use py -i -q as the child command. From a source checkout, replace
smartcli-tui with python skills/drive-tui/scripts/tui.py.
Or drive from any MCP client — the same verbs as MCP tools, with the per-session token attached automatically:
pip install smartcli-toolkit
smartcli-mcp # stdio MCP server; smartcli-toolkit is an equivalent aliasThe shared core is importable directly:
import sys
from smartcli_core import PtySession
s = PtySession()
s.start([sys.executable, "-q"])
s.wait_for(r">>> ") # readiness sync, never a blind sleep
print(s.snapshot().to_text()) # pyte-backed structured screen
s.close()For the full command reference, the screenshot/AGENTCLI harnesses, and the regression
suite, see README-USAGE.md.
cmd-art (skills/cmd-art) — a "living-template" effect engine: an Effect ABC +
@register decorator + auto-discovery. 30 effects (donut, solarsystem, fire, plasma,
rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt, spectrum_bars, cbonsai) across 8 themes (mono, fire,
ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
producers; play is bounded by default and always restores the terminal.
tui-ui (skills/tui-ui) — a web-like terminal layout engine emitting tmux-safe
ANSI frames (SGR color runs + newlines only; no cursor moves, no alt-screen). 17
widgets (badge, banner, braille_chart, card, fuzzy_filter_list, gradient_rule, kv,
meter, panel, preview_pane, progress, radial_glow, rule, slider_track, table, tabs,
tree) over an engine of two modules the render path actually calls — field.py
(shader compositors) and raster.py (sub-cell half/quad/braille pixels). Two
further helpers, box_junction.py and color_model.py, shipped unwired through
0.3.2 and were removed in 0.3.3: nothing imported them, and tui-ui has no
auto-discovery over ui/, so no caller could ever reach them.
Display-cell accurate for CJK/emoji/ZWJ so columns never desync.
drive-tui (skills/drive-tui) — drives interactive terminal programs (REPLs,
menus, pagers, y/N prompts, wizards) through a PTY via a
perceive → decide → act → wait → confirm loop, never a blind sleep. A thin CLI
(scripts/tui.py) offers a persistent detached session and a one-shot run mode, with
an importable pattern library of 8 recipes (repl, menu_select, pager, search_filter,
confirm, form, progress, wizard) that classify() a screen and drive() it.
Where the wait capabilities live. The wait family can end when the child
process dies rather than sitting out the remaining timeout — a program that
crashes on your first input then costs one poll cycle instead of the whole
ceiling. It is opt-in and off by default: start --detect-child-exit /
run --detect-child-exit, or detect_child_exit on the MCP start tool. Off
is exactly the previous behaviour. On, every wait reply carries exited, and
wait reports reason=EXITED. Three other core capabilities — the
screen-revision wait baseline, the terminal-mode registry, and the session event
log — are library-only: they are importable from smartcli_core and are
deliberately not on the CLI or MCP surface. See
CHANGELOG.md (Unreleased) for the reasoning per capability.
Shared core (smartcli_core) — the pluggable PTY backend + pyte screen model +
semantic snapshot + readiness sync (pty_backend / screen_model / snapshot / readiness / session). The reusable, importable foundation under all three skills. Since 0.3.0 a
budgeted read path and an io block travel with every observation, so a caller can tell
quiet from not read yet (local_cut, byte watermarks, pending facts — unknown values are
null, never 0), STABLE requires a drained observation, and close reports
closed_confirmed or close_unconfirmed with the last progress instead of assuming a
returned native call means the child is gone.
Knowledge graph (knowledge/) — a wiki-link graph (140+ .md files) of exact
rendering formulas, ANSI sequences, and measured constants, each note carrying a
source and cross-links. See knowledge/INDEX.md.
SmartCLI/
smartcli_core/ shared PTY + pyte engine (importable package)
skills/cmd-art/ fx effect package and CLI (30 effects, 8 themes)
skills/drive-tui/ TUI pattern library and PTY driver CLI (8 recipes)
skills/tui-ui/ terminal UI layout engine and widgets (17 widgets)
tools/screenshot/ pyte -> PNG smoke-test harness
tools/agentcli/ agent-CLI control validation harness
knowledge/ wiki-link knowledge graph, 140+ .md files (see knowledge/INDEX.md)
showcase/ rendered effect PNGs + demo GIFs (shown above)
tests/ direct script-style regressions
research/ archived first-pass research notesREADME-USAGE.md — the full usage cheat-sheet: every skill,
the screenshot and AGENTCLI harnesses, and the regression commands.
knowledge/INDEX.md — the knowledge graph (140+ .md files).
AGENTCLI-VALIDATION.md — agent-CLI control test matrix.
CHANGELOG.md — release history.
Verification evidence tree — archived 2026-10-01. The former verification/
directory (receipts, probes, historical harness revisions) is no longer part
of this repository, and is not distributed with the package. It was moved
byte-for-byte, so nothing was deleted. It was pulled out because it held 8
stale copies of smartcli_core/screen_model.py taken before three bug fixes,
so a repo-wide search returned pre-fix code. The sha256 pins inside it still
resolve — they name files that stayed in the repository.
MIT — see LICENSE.
Check whether the session's child process is still running.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds the specific detail of checking the child process. It does not disclose edge cases like invalid session IDs or return value behavior, but this is minor for a read-only check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, with no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple check tool, the description adequately states the purpose and the tool name implies a boolean result. The lack of explicit return value documentation is a minor gap, but the tool's simplicity mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (sid) with no description, and the tool description only implies sid is the session identifier. It does not explicitly define the parameter format, origin, or constraints, leaving the agent to infer meaning from the purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('check') and a clear resource ('session's child process'), distinguishing it from sibling tools like list_sessions or start. It unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this tool when you need to determine if a session's child process is still running. However, it provides no explicit 'when not to use' or alternatives to other similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Terminate a session and its daemon. Always close sessions when done.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the specific detail that the daemon is also terminated, which is beyond the annotations' destructive hint. However, it does not disclose side effects, reversibility, or return behavior. With annotations already indicating destructiveness, this partial additional context earns a middle score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. Every word earns its place, and the imperative 'Always close sessions when done' is a clear, useful addition without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 param, no output schema), and the description covers the primary action and a usage guideline. However, it omits any mention of return values, potential errors, or what happens to unsaved data, which is relevant for a destructive operation. The presence of annotations helps but does not fully compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'sid' with no description (0% coverage), so the description must compensate. Yet the description does not mention 'sid', its purpose, format, or constraints. It is only inferable from tool context, but the description itself adds no semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('terminate') and names the resource ('a session and its daemon'), clearly distinguishing it from sibling tools like list_sessions or start. It fully communicates the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Always close sessions when done' provides clear context on when to use this tool. It does not explicitly name alternatives or exclusions, but the context is sufficient given the sibling tools and the lifecycle implied by 'close' versus 'start'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active drive-tui sessions.
Returns {"ok", "sessions"}: each entry carries "sid", "port", "pid", "cmd", "cols", "rows", "cwd" and "started".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact return fields and structure, reinforcing that this is a safe, non-mutating observation tool. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action, and the return-field list is compact and information-dense. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter listing tool, the description is nearly complete: it documents the return structure and fields. It does not mention error cases or empty-list behavior, but those are minor in context and not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter semantics. The description's return-field list indirectly confirms that no inputs are needed, which is sufficient for this case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'active drive-tui sessions'. It clearly distinguishes this from sibling tools that modify or send input to sessions, and it even documents the return shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for enumerating active sessions, but it does not explicitly state when to use it instead of alternatives like 'alive' or 'wait_ready'. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resize the session's terminal to cols x rows.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| cols | Yes | ||
| rows | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no additional behavioral context such as side effects, error behavior, or interaction with existing terminal content. It only restates the action without enriching transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and target. Every word earns its place, and there is no verbose or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low complexity, but the description lacks return value information (no output schema) and doesn't mention potential failure modes such as invalid dimensions or non-existent session IDs. It is adequate for a simple resize but leaves open questions about observable effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies 'cols' and 'rows' as dimensions via 'cols x rows,' but it does not explain 'sid' beyond the implication from 'session's.' No constraints, bounds, or format details are given, leaving gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Resize' and the resource 'session's terminal' with the target dimensions 'cols x rows.' It is distinct from sibling tools like close, snapshot, or send_text, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when the terminal needs resizing) but provides no explicit exclusions, alternatives, or relationship to other session tools. It doesn't mention when not to use it or what to consider before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send key tokens, e.g. ["Down", "Down", "Enter"], ["C-c"], ["M-x"].
Named tokens: Enter, Return, Tab, BackTab, Space, Backspace, Delete, Escape, Esc, Up, Down, Right, Left, Home, End, PageUp, PageDown, Insert, F1-F12. Combos: "C-" or "^" (Ctrl — letters plus @, Space, [, , ]) and "M-" (Meta/Alt, ESC prefix). Any other token is not an error — it is typed as literal text.
Arrow keys adapt to the app's cursor-key mode (SS3 under DECCKM, CSI else), so menu navigation works in curses apps.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| keys | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the sparse annotations by disclosing key non-obvious behaviors: unknown tokens are typed as literal text (not errors), and arrow keys automatically adapt to the app's cursor-key mode (SS3 vs CSI) for curses navigation. This gives the agent insight into edge cases that wouldn't be evident from the schema or 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but all content is functional: examples, token list, combos, and two critical behavioral notes (literal text, arrow-key adaptation). It is front-loaded with examples and well-structured. While it could be slightly more concise, it avoids redundancy and earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and minimal annotations, the description covers the tool's complex input format comprehensively, including edge cases like literal text and arrow-key modes. The main gap is the unexplained 'sid' parameter and lack of any note about return behavior or errors. Given the tool's complexity, the description is largely complete but has small omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It thoroughly explains the 'keys' format, including examples, named tokens, combinations, and literal fallback behavior. However, it entirely omits the 'sid' parameter, which is not self-explanatory from its name/type alone. Thus, only half of the parameters are semantically enriched, leaving a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Send key tokens' with concrete examples (["Down", "Down", "Enter"], ["C-c"]). It distinguishes itself from siblings like send_text/send_line by focusing on key tokens (special keys, combos) rather than arbitrary text. The comprehensive list of named tokens leaves no ambiguity about what constitutes a key token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed semantics but does not explicitly compare to alternatives. It implies usage when you need to send key presses, combos, or arrow keys, and notes that unknown tokens are typed as literal text, suggesting overlap with send_text. However, no explicit 'use send_text when you want to type text' guidance is given, so the usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Type text followed by Enter — the common 'run this command' action.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, indicating a mutation. The description adds the key behavioral detail that it appends Enter to the text, which is not captured in annotations or schema. It does not cover side effects or prerequisites, but for a simple typing tool this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential behavior without filler. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and two string parameters, the description covers the core action well. However, the 'sid' parameter is not explained, and the description does not mention any side effects beyond typing, which prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description implicitly references the 'text' parameter but gives no meaning for 'sid'. With two required parameters, the description fails to explain the purpose of 'sid', leaving the agent to guess based on the parameter name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Type text followed by Enter' clearly states a specific verb-action (type text) and the result (followed by Enter), and frames it as 'the common run this command action', which distinguishes it from siblings like send_text or send_keys. It is specific and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'the common run this command action' conveys that this tool is the standard way to execute a command in a session, providing clear usage context. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Type literal text into the session (no Enter). Use for filling fields.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it types literal text and does not press Enter. With readOnlyHint=false and destructiveHint=false, this adds useful behavioral context beyond annotations. However, it does not describe potential side effects like overwriting existing field content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with action. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param tool with annotations, the description covers purpose, usage, and key behavior. Lacks explicit detail on sid and possible side effects, but is sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides no descriptions for sid or text, so description must compensate. It implies sid is the session identifier and text is the literal text, but does not explicitly define sid or elaborate on text limitations. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Type literal text into the session' with a specific verb and resource. Distinguishes from siblings by explicitly noting 'no Enter' and 'filling fields', differentiating from send_line and send_keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives usage context: 'Use for filling fields.' Implicitly indicates when to use (form filling) and excludes sending Enter, but does not explicitly reference sibling tools or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a semantic snapshot of the session's current screen.
Returns {"ok", "alive", "alt_screen", "text", "hash", "visual_hash"}:
alt_screen is true while a full-screen program (vim, less, htop, ...)
owns the screen — keys are commands to that program, not input to a
shell, and text is its frame rather than scrollback. text is the
rendered screen; json (the structured cell/cursor model) is included only
when as_json=true. hash covers text content only — use it as the
wait_change baseline; visual_hash also covers styling, selection and
cursor state — use it as the wait_visual_change baseline. Don't mix the
two. This is the 'perceive' step — always snapshot after acting rather
than assuming an action landed.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| as_json | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, idempotent, and non-destructive. The description adds substantial behavior: alt_screen semantics, json inclusion only with as_json=true, hash vs visual_hash scoping, and a warning not to mix them. This goes well beyond structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs, front-loaded with purpose. Every clause adds value: alt_screen behavior, hash baselines, the perceive-step instruction, and parameter effects. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of return semantics and mostly succeeds, covering ok/alive/alt_screen/text/hash/visual_hash and wait baselines. Minor gaps remain, such as the exact meaning of `sid` and a precise definition of `ok`/`alive`, but the tool is adequately specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains as_json's effect (structured json included only when true) and clarifies text vs json. However, with 0% schema description coverage, the required `sid` parameter is not explicitly described, so the description only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Read a semantic snapshot of the session's current screen' and immediately clarifies its role as the 'perceive' step. This clearly distinguishes snapshot from sibling send/wait/action tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'always snapshot after acting rather than assuming an action landed' and explains how to use hash/visual_hash as baselines for wait_change/wait_visual_change. It does not provide explicit when-not-to-use alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spawn a program in a new detached, persistent session and return its id.
The session survives across tool calls (a localhost-only daemon owns the live
PtySession). cmd is the command line to spawn, e.g. "python3" or
"lazygit". cwd and env configure only the controlled child process.
Returns {"ok", "sid"} on success. Use the returned sid for every other tool.
Server-side limits (violations return an error): at most 8 concurrent
sessions by default (tunable via SMARTCLI_MAX_SESSIONS); sid must be 1-64
chars matching [A-Za-z0-9][A-Za-z0-9_.-]*; env keys must be valid
identifiers and may not start with SMARTCLI_TUI_; cwd must be an existing
directory; terminal size is capped at 1000 cols x 500 rows (100000 cells).
Note: env values pass through the process command line briefly (visible
in ps) — avoid secrets.
detect_child_exit (default false) makes this session's waits END when the
child dies instead of sitting out the remaining timeout: a program that
crashes on your first input costs one poll cycle instead of the whole
ceiling. Off is exactly the previous behaviour. On, every wait tool also
reports exited (true only when the wait ended that way), and wait_ready
reports reason: "EXITED" alongside the usual MARKER/STABLE/TIMEOUT.
| Name | Required | Description | Default |
|---|---|---|---|
| cmd | Yes | ||
| cwd | No | ||
| env | No | ||
| sid | No | ||
| cols | No | ||
| rows | No | ||
| detect_child_exit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing the daemon-owned persistent session model, the 8-session concurrency cap, sid format constraints, env key restrictions, cwd existence requirement, terminal size ceiling, and the ps-visible secret leak risk. It also explains the detect_child_exit behavior change and its effect on wait/reporting semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then organized into constraints and the detect_child_exit note. The detect_child_exit paragraph is longer than strictly necessary, but each sentence adds operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotation coverage of the details, the description supplies the return shape ({ok, sid}), the persistence model, all constraint-based failure modes, and the wait-tool interactions. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load: it documents cmd, cwd, env, sid (with format rules), and detect_child_exit. cols/rows are only implied via the terminal-size cap and are not given names or units, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Spawn a program in a new detached, persistent session') plus the return value ('return its id'), and the 'Use the returned sid for every other tool' line implies its role as the entry point of the sibling family. An agent can distinguish it from close/list_sessions/send_keys without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly indicates this is the first tool to call and that all other tools need the returned sid, and gives explicit guidance on when to enable detect_child_exit (programs that may crash on first input). It does not explicitly name an alternative tool or state when NOT to use it, so it falls short of the 5 bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for ANY of patterns to appear on screen (pexpect expect([...]) style).
Race several possible outcomes at once — e.g. patterns=[">>> ", "Error",
"Password:"] — and learn WHICH happened. Patterns are scanned in list order
each poll, so the earliest in the list wins a same-poll tie (put the most
specific first). Screen lines are right-padded with spaces — end-anchored
patterns never match; use unanchored markers. Returns {"ok", "index",
"matched", "alive", "exited", "text", "json"} where index is the 0-based
position of the matched pattern. Timeout is not an error: the call returns
ok=true with index=-1 and matched=false plus the final screen snapshot.
On a detect_child_exit session whose child died first, index is -1,
matched is false and exited is true — the wait returned at once rather
than running to timeout_ms.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| patterns | Yes | ||
| timeout_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already covering the safety profile (readOnly/idempotent/non-destructive), the description still adds substantial non-obvious behavior: same-poll tie resolution by list order, the right-padding caveat that breaks end-anchored patterns, and the fact that timeout is not an error but an ok=true/index=-1 return. It also discloses the special detect_child_exit path where a dead child short-circuits the wait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and the example before detailing tie-breaks and return shape, so an agent can stop reading early. It is fairly dense and slightly long, but nearly every clause conveys a distinct behavioral fact (padding, tie order, timeout-as-success, child exit) rather than restating the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description spells out the full return object ({ok, index, matched, alive, exited, text, json}) including the sentinel values for timeout and child-exit cases. Combined with the patterns/timeout semantics, an agent has everything needed to call it and interpret both success and timeout outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the param burden and largely does: it defines `patterns` scan order and matching semantics, and explains `timeout_ms` behavior (returns ok=true with index=-1 rather than erroring, or returning at once on child exit). Only `sid` goes unexplained, which is a minor omission against the strong coverage of the other two.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: wait for ANY of `patterns` to appear on screen, explicitly framed as pexpect expect([...]) semantics. It doesn't name its closest siblings (wait_regex, wait_ready, wait_change), so an agent must infer the distinction from the 'race several possible outcomes' framing rather than an explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete usage scenario ('race several possible outcomes at once — e.g. patterns=[">>> ", "Error", "Password:"]') and guidance on ordering ('put the most specific first'), which tells the agent when this tool fits. It stops short of stating when NOT to use it versus wait_regex or the other wait_* siblings, so no alternative is explicitly routed away.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until the screen content changes, then snapshot.
The precise "did my action land?" primitive: call it right after send_line/
send_keys to wait for ANY change from the baseline (default: the screen at
call time; or pass a prior hash to change away from). Returns {"ok",
"changed", "hash", "alive", "exited", "text", "json"} — hash is the new
screen hash, reusable as the next baseline. Timeout is not an error: the
call returns ok=true with changed=false plus the final screen snapshot.
exited is true only on a detect_child_exit session whose child died
first. Can't false-positive on text that was already on screen, unlike
wait_regex.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| timeout_ms | No | ||
| baseline_hash | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: timeout is not an error (ok=true, changed=false plus final snapshot), `exited` is true only on a detect_child_exit session whose child died, and hash is reusable as the next baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the one-line purpose, then layers usage, return shape, and edge cases in dense, purposeful sentences. No filler; every clause adds actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description enumerates the return fields ({ok, changed, hash, alive, exited, text, json}) and explains the non-obvious ones. Timeout, baseline, and exit semantics are all covered, so an agent can invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage the description must carry the burden; it fully explains baseline_hash (default = screen at call time, or a prior hash) and covers timeout semantics. It leaves sid and the timeout_ms unit/default unstated, but the non-obvious parameter is well documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Block until the screen content changes, then snapshot') and frames it as the 'did my action land?' primitive. It explicitly distinguishes itself from siblings by naming send_line/send_keys as the callers and wait_regex as the weaker alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('call it right after send_line/send_keys'), states the baseline default and how to override it, and names the alternative (wait_regex) with the condition that favors this tool ('Can't false-positive on text that was already on screen').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for a regex marker OR for the screen to go quiet (stable), then
snapshot. Use marker="" to wait purely for stability.
Returns a snapshot plus reason: "MARKER" (the regex appeared), "STABLE"
(the screen went quiet), "TIMEOUT", or — only on a session started with
detect_child_exit — "EXITED" (the child died; the wait returned at once
rather than running to max_wait_ms). exited reports the same fact as a
boolean on every wait tool. Timeout is not an error: the call still returns
ok=true with the final screen snapshot. Screen lines are right-padded with
spaces — end-anchored markers never match; use unanchored markers.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| marker | No | ||
| quiet_ms | No | ||
| max_wait_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it enumerates the `reason` outcomes (MARKER/STABLE/TIMEOUT/EXITED), clarifies that timeout is not an error and still returns ok=true, explains the `exited` boolean, and warns that right-padded screen lines break end-anchored markers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior and the marker="" tip are front-loaded in the first two lines, and the return-value discussion follows logically. The parenthetical EXITED clause is slightly dense, but every sentence adds distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain returns, and it does so thoroughly via the `reason` enum and `exited` boolean. The remaining gap is operational detail on the timing parameters and the session id, which the agent must guess from names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden and largely does: it defines `marker` as a regex with the empty-string stability mode, and references `max_wait_ms` (the wait bound) and the stability concept behind `quiet_ms`. Only `sid` and explicit units/defaults for the two timing params are left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific dual-capability verb: wait for a regex marker OR for screen stability, then snapshot. This implicitly distinguishes it from wait_regex (marker only) and wait_change/wait_visual_change (change-based), but it never names those siblings explicitly, so differentiation requires inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use marker="" to wait purely for stability' is a concrete configuration directive, but it explains parameter usage rather than when to choose wait_ready over wait_regex, wait_any, or a plain snapshot. No when-not conditions or alternatives are given, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until pattern (a regex) appears on screen, then snapshot.
Returns {"ok", "matched", "alive", "exited", "text", "json"}. Timeout is
not an error: the call returns ok=true with matched=false plus the final
screen snapshot. exited is true only when the session was started with
detect_child_exit AND the child died before the pattern appeared, in
which case the wait returned at once instead of running to timeout_ms.
Screen lines are right-padded with spaces — end-anchored patterns never
match; use unanchored markers. This is the readiness sync — prefer it over
a blind delay after send_line/send_keys.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| pattern | Yes | ||
| timeout_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: timeout is not an error (ok=true, matched=false plus final snapshot), exited semantics depend on detect_child_exit and child death, and the screen-padding quirk means end-anchored patterns never match. These are non-obvious operational details that annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action, then uses tight sentences for return shape, timeout semantics, exit behavior, and the padding caveat. Every sentence carries distinct, actionable information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description documents the return keys (ok, matched, alive, exited, text, json) and the key edge cases (timeout, early exit, padding). An agent has everything needed to invoke and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, and it explains `pattern` as a regex and clarifies timeout_ms semantics (timeout not an error, runs to timeout_ms). The `sid` parameter is left undocumented, so it doesn't fully close the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: block until a regex pattern appears on screen, then snapshot. This is precise and distinguishable from siblings like wait_change, wait_visual_change, wait_any, and wait_ready, which do not mention regex matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to prefer this over a blind delay after send_line/send_keys, which gives clear when-to-use context. However, it does not directly differentiate itself from the closest siblings (wait_ready, wait_any, wait_change), leaving some routing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for text, selection styling, or cursor position to change.
Prefer this after arrow/navigation keys in full-screen TUIs. Pass a prior
visual_hash, or omit it to use the current rendered state as the baseline.
Timeout is not an error: the call returns ok=true with changed=false plus
the final screen snapshot, with exited true only on a
detect_child_exit session whose child died first.
| Name | Required | Description | Default |
|---|---|---|---|
| sid | Yes | ||
| timeout_ms | No | ||
| baseline_hash | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint and non-destructive, so the safety profile is covered. Beyond that, the description adds genuinely useful behavior: a timeout is not an error, the response carries ok/changed plus a final screen snapshot, and `exited` is only true in a detect_child_exit session. It does not describe detection granularity or polling behavior, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and usage in the first clause, with the return-shape detail following. The timeout paragraph is dense but each clause adds real information; only minor trimming is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description steps up to document the return contract (ok, changed, screen snapshot, exited) and the non-error timeout case. Combined with baseline and usage guidance, an agent has what it needs to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning, and it partly does: it explains that a prior hash is passed or omitted to baseline on the current render, and that timeout is non-fatal. However, it refers to the baseline parameter as `visual_hash` while the schema names it `baseline_hash`, which risks mis-mapping, and no units or defaults are given for timeout_ms.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (wait) and a precise resource (visual change), then enumerates what counts as a change: text, selection styling, or cursor position. Against a sibling set full of other `wait_*` tools, this tells the agent exactly what this one observes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Prefer this after arrow/navigation keys in full-screen TUIs" gives a concrete triggering context. It stops short of explicitly contrasting with the sibling wait_change / wait_any / wait_ready tools, so the routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.4start1 field changedInput schema / properties / detect_child_exitAdded value: +{
+ "default": false,
+ "title": "Detect Child Exit",
+ "type": "boolean"
+}v0.2.1alivecloselist_sessionsresizesend_keyssend_linesend_textsnapshotstartwait_anywait_changewait_readywait_regexwait_visual_changeScored across 14 tools
Most tools are clearly distinct by action and target, but the five wait_* variants overlap conceptually. Their descriptions explicitly differentiate patterns, content hashes, visual hashes, multiple patterns, and readiness modes, so an agent can choose, though some confusion is possible.
Tool names consistently use snake_case and are mostly verb-first or verb_noun (list_sessions, send_keys, wait_regex, close, start). Minor noun/adjective names like snapshot and alive still fit the overall predictable style.
14 tools is a reasonable size for persistent terminal and TUI automation. The five wait tools are somewhat heavy, but each covers a distinct synchronization primitive rather than being redundant.
The set covers session lifecycle (start, list_sessions, close, alive, resize), input (send_text, send_line, send_keys), waits, and screen perception. Minor gaps exist for explicit signal/interrupt operations or scrollback retrieval, but send_keys and snapshots let agents work around them.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
