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., "@Terminal Controller MCP Server Show me the contents of my Downloads directory"
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.
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
Command Execution: Run terminal commands with timeout controls and comprehensive output capture
Directory Management: Navigate and list directory contents with intuitive formatting
Security Measures: Built-in safeguards against dangerous commands and operations
Command History: Track and display recent command executions
Cross-Platform Support: Works on both Windows and UNIX-based systems
File Operations: Read, write, update, insert, and delete file content with row-level precision
Related MCP server: Command Line Interface Enhancer
To install Terminal Controller for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claudePython 3.11+
An MCP-compatible client (such as Claude Desktop)
UV/UVX installed (optional, for UVX method)
Install the package directly from PyPI:
pip install terminal-controllerOr if you prefer to use UV:
uv pip install terminal-controllerIf you prefer to install from source:
Clone this repository:
git clone https://github.com/GongRzhe/terminal-controller-mcp.git
cd terminal-controller-mcpRun the setup script:
python setup_mcp.pyThere are two ways to configure Claude Desktop to use Terminal Controller:
Add this to your Claude Desktop configuration file:
"terminal-controller": {
"command": "uvx",
"args": ["terminal_controller"]
}"terminal-controller": {
"command": "python",
"args": ["-m", "terminal_controller"]
}The configuration path varies by operating system:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
For Cursor, use similar configuration settings as Claude Desktop.
For other clients, refer to their documentation on how to configure external MCP servers.
Once configured, you can use natural language to interact with your terminal through your MCP client:
"Run the command ls -la in the current directory"
"Navigate to my Documents folder"
"Show me the contents of my Downloads directory"
"Show me my recent command history"
"Read the content of config.json"
"Update line 5 in my script.py file with 'print("Hello World")'"
"Delete lines 10-15 from the log file"
"Insert a new line at the beginning of my text file"
Terminal Controller exposes the following MCP tools:
execute_commandExecute a terminal command and return its results.
Parameters:
command: The command line command to execute
timeout: Command timeout in seconds (default: 30)
Returns:
Output of the command execution, including stdout, stderr, and execution status
get_command_historyGet recent command execution history.
Parameters:
count: Number of recent commands to return (default: 10)
Returns:
Formatted command history record
get_current_directoryGet the current working directory.
Returns:
Path of current working directory
change_directoryChange the current working directory.
Parameters:
path: Directory path to switch to
Returns:
Operation result information
list_directoryList files and subdirectories in the specified directory.
Parameters:
path: Directory path to list contents (default: current directory)
Returns:
List of directory contents, formatted with icons for directories and files
write_fileWrite content to a file with overwrite or append options.
Parameters:
path: Path to the file
content: Content to write
mode: Write mode ('overwrite' or 'append', default: 'overwrite')
Returns:
Operation result information including verification of successful write
read_fileRead content from a file with optional row selection.
Parameters:
path: Path to the file
start_row: Starting row to read from (0-based, optional)
end_row: Ending row to read to (0-based, inclusive, optional)
Returns:
File content or selected lines
insert_file_contentInsert content at specific row(s) in a file.
Parameters:
path: Path to the file
content: Content to insert
row: Row number to insert at (0-based, optional)
rows: List of row numbers to insert at (0-based, optional)
Returns:
Operation result information
delete_file_contentDelete content at specific row(s) from a file.
Parameters:
path: Path to the file
row: Row number to delete (0-based, optional)
rows: List of row numbers to delete (0-based, optional)
Returns:
Operation result information
update_file_contentUpdate content at specific row(s) in a file.
Parameters:
path: Path to the file
content: New content to place at the specified row(s)
row: Row number to update (0-based, optional)
rows: List of row numbers to update (0-based, optional)
Returns:
Operation result information
Terminal Controller implements several security measures:
Timeout controls to prevent long-running commands
Blacklisting of dangerous commands (rm -rf /, format, mkfs)
Proper error handling and isolation of command execution
Access only to the commands and directories specifically granted
Only commands that complete within the timeout period will return results
By default, the server has access to the same file system permissions as the user running it
Some interactive commands may not work as expected due to the non-interactive nature of the terminal interface
If you encounter issues:
Check that your Python version is 3.11 or higher
Verify that your Claude Desktop configuration is correct
Try running the terminal controller directly to check for errors:
python -m terminal_controllerFor UVX-related issues, try:
uvx terminal_controllerReview your MCP client's logs for connection errors
Contributions are welcome! Please feel free to submit a Pull Request.
MIT
Change current working directory
Args:
path: Directory path to switch to
Returns:
Operation result information
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the basic action without mentioning side effects (e.g., permission requirements, error handling, or navigational boundaries). The return value 'Operation result information' is vague.
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 short and straightforward, with a clear header and an Args section. It avoids unnecessary text, though placing the key purpose first is good practice but not explicitly front-loaded due to the structure.
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?
Given the lack of annotations and output schema, the description should provide more context about return values, error cases, and interaction with sibling tools. It does not mention that other tools like get_current_directory complement this operation.
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 0% parameter description coverage, so the description compensates slightly by naming the parameter 'path' and adding 'Directory path to switch to'. However, it does not specify path types (absolute/relative), validation, or format, leaving ambiguity beyond the parameter name.
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 'Change current working directory', which is a specific verb+resource (change directory) that directly conveys the action. However, it does not explicitly differentiate from sibling tools like execute_command or list_directory, though the purpose is unambiguous.
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?
No guidance is provided on when to use this tool versus alternatives such as get_current_directory or execute_command. The description does not mention prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete content at specific row(s) from a file
Args:
path: Path to the file
row: Row number to delete (0-based, optional)
rows: List of row numbers to delete (0-based, optional)
substring: If provided, only delete this substring within the specified row(s), not the entire row (optional)
Returns:
Operation result information
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| row | No | ||
| rows | No | ||
| substring | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that substring deletion only removes the substring within the row, not the entire row. However, with no annotations, it fails to mention destructive nature, error handling, or index behavior (e.g., shifting after deletion).
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 structured with Args and Returns, and each parameter is explained in a single line. It is not overly verbose, though it could omit 'Args:' and 'Returns:' for brevity.
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 destructive tool with no annotations and no output schema, the description omits important details: error cases (e.g., invalid row), behavior when both row and rows are provided, and return value. This leaves significant gaps for an agent.
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%, but the description adds full meaning: row is 0-based integer, rows is list, substring optional for partial deletion. This compensates entirely for the missing schema explanations.
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 deletes content at specific rows from a file, using a specific verb and resource. It distinguishes from siblings like update_file_content and insert_file_content by focusing on deletion.
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?
No explicit guidance on when to use this tool versus alternatives such as update_file_content or write_file. The description lacks context for choosing between row deletion and substring deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute terminal command and return results
Args:
command: Command line command to execute
timeout: Command timeout in seconds, default is 30 seconds
Returns:
Output of the command execution
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| timeout | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description lacks disclosure of safety, side effects, or return format. For a command execution tool, this is insufficient 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?
Very concise with a clear Args/Returns structure. Every sentence is meaningful and there is no wasted text.
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 potentially dangerous tool, the description is too minimal. It lacks information on error handling, return format, timeout behavior, and prerequisites.
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%, but the description adds basic meaning: 'command' is a command line string, 'timeout' is in seconds with default 30. This helps but doesn't specify constraints or format details.
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 purpose: executing terminal commands and returning results. It distinguishes itself from sibling tools like file operations and directory navigation.
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?
No guidance on when to use this tool versus alternatives. Sibling tools are listed but the description gives no context for choosing execute_command over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent command execution history
Args:
count: Number of recent commands to return
Returns:
Formatted command history record
| Name | Required | Description | Default |
|---|---|---|---|
| count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states it gets history without disclosing data freshness, persistence, or side effects. Unclear what 'recent' means.
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?
Concise single sentence followed by technical docstring. Front-loaded main action with minimal 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?
No output schema; description says returns 'Formatted command history record' which is vague. Missing details on whether it returns a list, string, or structured data.
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?
Adds explanation for 'count' parameter beyond schema, specifying it controls how many commands to return. Schema coverage is 0%, so this is helpful, though could be more precise.
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 it retrieves recent command execution history. Distinct from sibling execute_command which runs commands.
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?
No guidance on when to use this tool versus alternatives like execute_command. Lacks context about prerequisites or scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current working directory
Returns:
Path of current working directory
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full burden. It only states the basic function and return value but does not disclose any behavioral traits like permissions, failure modes, or side effects.
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?
Extremely concise: two sentences, no wasted words. The purpose is front-loaded, and every sentence adds 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?
For a tool with no parameters and no output schema, this description is complete. It states what the tool does and what it returns, which is sufficient for such a simple operation.
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?
No parameters exist, and schema coverage is 100%. The description adds no parameter semantics beyond the schema, but according to rules a zero-parameter tool gets a baseline of 4.
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 'Get current working directory' which is a specific verb+resource. It distinguishes itself from sibling tools like change_directory (which changes directory) and list_directory (which lists contents).
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?
No guidance provided on when to use this tool versus alternatives. There is no mention of context or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert content at specific row(s) in a file
Args:
path: Path to the file
content: Content to insert (string or JSON object)
row: Row number to insert at (0-based, optional)
rows: List of row numbers to insert at (0-based, optional)
Returns:
Operation result information
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| row | No | ||
| rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present. The description omits behavioral details such as what happens if the file does not exist, if the row index is out of range, or whether the operation can be reversed. The return value is vaguely described as 'Operation result information'.
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 short and begins with the main purpose, then lists parameters in a clear format. However, the docstring-style repetition of parameter info could be more streamlined.
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?
Given the lack of annotations and output schema, the description should provide more context about return values, error behavior, and edge cases. It only covers basic parameter semantics, leaving gaps in understanding how the tool behaves in practice.
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 compensates by explaining each parameter's purpose, including that 'row' and 'rows' are 0-based. It also notes that 'content' can be a string or JSON object, adding value beyond the schema's type string.
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 action ('Insert content') and the resource ('at specific row(s) in a file'). This is distinct from sibling tools like 'write_file' (overwrite) or 'update_file_content' (modify existing content).
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 no guidance on when to use this tool over alternatives such as 'write_file' or 'update_file_content'. It does not mention prerequisites or scenarios where insertion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and subdirectories in the specified directory
Args:
path: Directory path to list contents, default is current directory
Returns:
List of directory contents
| Name | Required | Description | Default |
|---|---|---|---|
| path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only states the basic operation. It does not disclose behaviors such as whether hidden files are listed, how errors (e.g., invalid path) are handled, or if it follows symlinks. For a simple tool, this is adequate but not thorough.
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 concise and front-loaded, with a clear statement of purpose followed by parameter details. Every sentence is informative, though the Args/Returns format is somewhat verbose for such a simple tool.
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?
Given the tool's simplicity and the lack of output schema, the description adequately covers the input and output. It explains the single parameter and the return value (list of contents), which is sufficient for an agent to use the tool 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?
The description adds meaning to the 'path' parameter by explaining its purpose and default value, which is not fully conveyed by the schema alone (which only specifies type and nullability). Schema coverage is 0%, so the description compensates well.
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 'list' and the resource 'files and subdirectories' in a specified directory, which distinguishes it from sibling tools like read_file or write_file.
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?
No guidance is provided on when to use this tool versus alternatives like change_directory or read_file. It does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read content from a file with optional row selection
Args:
path: Path to the file
start_row: Starting row to read from (0-based, optional)
end_row: Ending row to read to (0-based, inclusive, optional)
as_json: If True, attempt to parse file content as JSON (optional)
Returns:
File content or selected lines, optionally parsed as JSON
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| start_row | No | ||
| end_row | No | ||
| as_json | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are present, the description explains that the tool returns file content (optionally as JSON) and selects rows. It implicitly indicates a read-only operation, which is sufficient for this straightforward tool.
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 concise, using a clean Args/Returns format. Every sentence adds value, with no redundancy or unnecessary details.
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?
Given no output schema, the description adequately explains return values (file content or selected lines, optionally as JSON). All four parameters are covered, and the tool's simple behavior is fully described.
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 input schema has 0% description coverage, but the description compensates by detailing each parameter's purpose, type, and defaults (e.g., 0-based rows, optional as_json). This fully clarifies parameter usage.
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 'Read content from a file' specifying the verb and resource. It is distinct from sibling tools like write, delete, or execute commands, making its purpose unambiguous.
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?
No guidance is provided on when to use this tool relative to alternatives such as list_directory or execute_command. The description lacks context on when reading a file is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update content at specific row(s) in a file
Args:
path: Path to the file
content: New content to place at the specified row(s)
row: Row number to update (0-based, optional)
rows: List of row numbers to update (0-based, optional)
substring: If provided, only replace this substring within the specified row(s), not the entire row
Returns:
Operation result information
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| row | No | ||
| rows | No | ||
| substring | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that it updates content at specific rows, optionally only replacing a substring. It does not explicitly state that the operation is destructive or what happens to other rows, but the 'update' verb implies mutation. This is fairly transparent but could be more explicit.
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 structured as a concise docstring with clear Args and Returns sections. Each parameter is explained in a single line, and there is no wasted verbiage. It efficiently conveys the necessary 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 description covers all parameters and returns 'Operation result information', which is generic. However, it does not specify what happens when row or rows are omitted (e.g., does it update the entire file?), nor does it mention file existence or error conditions. This leaves some ambiguity for the agent.
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 JSON schema has no descriptions (0% coverage), so the description fully compensates by explaining each parameter: path, content, row (0-based optional), rows (list optional), and substring (optional replacement). This adds significant meaning beyond the schema.
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 'Update content at specific row(s) in a file', which specifies the verb and resource. It distinguishes from siblings like delete, insert, or write by targeting specific rows, making it clear when this tool is appropriate.
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 a clear action but does not explicitly state when to use this tool over alternatives like write_file or insert_file_content. However, the focus on row-level updates implies its use case, and the description is adequate for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write content to a file
Args:
path: Path to the file
content: Content to write (string or JSON object)
mode: Write mode ('overwrite' or 'append')
Returns:
Operation result information
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| mode | No | overwrite |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It mentions write mode (overwrite/append) but fails to clarify file creation, directory creation, permissions, error handling, or character encoding.
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?
Concise docstring with clear sections. Each sentence provides value, though the Returns section is vague. No wasted words.
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?
Given no output schema and low schema coverage, the description covers the basics but lacks details on return values, edge cases (e.g., path exists, directory missing, large files). Adequate but incomplete.
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 has no parameter descriptions (0% coverage). The description compensates by explaining each Arg, noting content can be string or JSON object, and listing mode options.
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 'Write content to a file' with a specific verb and resource. It effectively distinguishes from sibling tools like read_file, delete_file_content, etc.
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?
No guidance on when to use this tool vs alternatives (e.g., append vs overwrite, or use insert_file_content for inline edits). Lacks any when-to-use or when-not-to-use context.
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.1.9change_directorydelete_file_contentexecute_commandget_command_historyget_current_directoryinsert_file_contentlist_directoryread_fileupdate_file_contentwrite_fileScored across 10 tools
Tools are mostly distinct: directory operations (change, get, list), command execution (execute, history), and file operations (read, write, insert, update, delete content). Overlap exists between insert, update, and delete row-based operations, but descriptions clarify differences.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., change_directory, execute_command, write_file. No deviations or mixed conventions.
With 10 tools, the set is well-scoped for a terminal controller, covering directory navigation, command execution with history, and file content manipulation. Each tool serves a clear purpose without redundancy.
The set covers core terminal operations well but lacks tools for file deletion (only content deletion), directory creation, and file renaming/moving. These gaps can be worked around via execute_command, but are notable omissions.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Run commands and read/write files on your servers over Termalin's keyless tunnels (hosted MCP).
