The editor-mcp server is a Python-based text editor designed for managing and editing files with a structured workflow, particularly useful for LLMs and AI assistants.
Core Capabilities:
File Selection and Reading: Set target files using absolute paths, read entire files with line numbers, or read specific line ranges
Multi-step Editing: Two-step editing workflow with diff preview - select line ranges, propose changes, then confirm or cancel
Code-Specific Search: Find text matches and extract function/method definitions in Python and JavaScript/JSX files
File Management: Create new files (with automatic directory creation), delete files, and list directory contents
Development Support: Run Python tests with pytest and configure Python paths for proper module resolution
Safety Features: Content ID verification, line count limits, syntax checking for Python and JavaScript/React files, and protected paths to restrict access to sensitive files
Uses Babel for JavaScript and React JSX syntax validation before committing code changes, ensuring JavaScript/React code maintains proper syntax.
Provides syntax checking for JavaScript files (.js) to maintain code integrity when editing JavaScript code.
Requires Node.js to perform JavaScript/JSX syntax validation through Babel when editing these file types.
Integrates with pytest for running tests with coverage reporting during development of the editor.
Offers syntax checking for Python files (.py) to ensure code integrity when making changes to Python code.
Supports editing and syntax validation for React JSX files (.jsx), ensuring code changes maintain proper React syntax.
Click on "Install 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., "@editor-mcp read the last 20 lines of my config.py file"
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 Python-based text editor server built with FastMCP that provides powerful tools for file operations. This server enables reading, editing, and managing text files through a standardized API with a unique multi-step approach that significantly improves code editing accuracy and reliability for LLMs and AI assistants.
File Selection: Set a file to work with using absolute paths
Read Operations:
Read entire files with line numbers using skim
Read specific line ranges with prefixed line numbers using read
Find specific text within files using find_line
Find and extract function definitions in Python and JavaScript/JSX files using find_function
Edit Operations:
Two-step editing process with diff preview
Select and overwrite text with ID verification
Clean editing workflow with select → overwrite → confirm/cancel pattern
Syntax checking for Python (.py) and JavaScript/React (.js, .jsx) files
Create new files with content
File Management:
Create new files with proper initialization
Delete files from the filesystem
List directory contents with listdir
Testing Support:
Run Python tests with run_tests
Set Python paths for proper module resolution
Safety Features:
Content ID verification to prevent conflicts
Line count limits to prevent resource exhaustion
Syntax checking to maintain code integrity
Protected paths to restrict access to sensitive files
Related MCP server: MCP File Manager
The editor-mcp includes powerful capabilities that come with certain security considerations:
Jailbreak Risk: The editor-mcp can potentially be jailbroken when reading a file that has harmful instructions embedded inside. Malicious content in files being edited could contain instructions that manipulate the AI assistant.
Arbitrary Code Execution: If running tests is enabled, there is a risk of arbitrary code execution through manipulated test files or malicious Python code.
Data Exposure: Access to file system operations could potentially expose sensitive information if proper path protections aren't configured.
To mitigate these risks:
Use the PROTECTED_PATHS environment variable to restrict access to sensitive files and directories.
Disable test running capabilities in production environments unless absolutely necessary.
Carefully review files before opening them, especially if they come from untrusted sources.
Consider running the editor in a sandboxed environment with limited permissions.
This text editor's unique design solves critical problems that typically affect LLM code editing:
Prevents Loss of Context - Traditional approaches often lead to LLMs losing overview of the codebase after a few edits. This implementation maintains context through the multi-step process.
Avoids Resource-Intensive Rewrites - LLMs typically default to replacing entire files when confused, which is costly, slow, and inefficient. This editor enforces selective edits.
Provides Visual Feedback - The diff preview system allows the LLM to actually see and verify changes before committing them, dramatically reducing errors.
Enforces Syntax Checking - Automatic validation for Python and JavaScript/React ensures that broken code isn't committed.
Improves Edit Reasoning - The multi-step approach gives the LLM time to reason between steps, reducing haphazard token production.
The editor implements several safeguards to ensure system stability and prevent resource exhaustion:
Maximum Edit Lines: By default, the editor enforces a 50-line limit for any single edit operation
This MCP was developed and tested with Claude Desktop. You can download Claude Desktop on any platform. For Claude Desktop on Linux, you can use an unofficial installation script (uses the official file), recommended repository: https://github.com/emsi/claude-desktop/tree/main
Once you have Claude Desktop installed, follow the instructions below to install this specific MCP:
The easiest way to install the Editor MCP is using the provided installation script:
# Clone the repository
git clone https://github.com/danielpodrazka/editor-mcp.git
cd editor-mcp
# Run the installation script
chmod +x install.sh
./install.shThis script will:
Check if UVX is installed and install it if necessary
Install the Editor MCP in development mode
Make the editor-mcp command available in your PATH
# Install directly from GitHub
uvx install git+https://github.com/danielpodrazka/mcp-text-editor.git
# Or install from a local clone
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
uvx install -e .pip install git+https://github.com/danielpodrazka/mcp-text-editor.git
# Or from a local clone
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
pip install -e .Install from the lock file:
uv pip install -r uv.lockuv pip compile requirements.in -o uv.lockAfter installation, you can start the Editor MCP server using one of these methods:
# Using the installed script
editor-mcp
# Or using the Python module
python -m text_editor.serverYou can add the Editor MCP to your MCP configuration file:
{
"mcpServers": {
"text-editor": {
"command": "editor-mcp",
"env": {
"MAX_SELECT_LINES": "100",
"ENABLE_JS_SYNTAX_CHECK": "0",
"FAIL_ON_PYTHON_SYNTAX_ERROR": "1",
"FAIL_ON_JS_SYNTAX_ERROR": "0",
"PROTECTED_PATHS": "*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/.ssh/id_rsa"
}
}
}
}The Editor MCP supports several environment variables to customize its behavior:
MAX_SELECT_LINES: "100" - Maximum number of lines that can be edited in a single operation (default is 50)
ENABLE_JS_SYNTAX_CHECK: "0" - Enable/disable JavaScript and JSX syntax checking (default is "1" - enabled)
FAIL_ON_PYTHON_SYNTAX_ERROR: "1" - When enabled, Python syntax errors will automatically cancel the overwrite operation (default is enabled)
FAIL_ON_JS_SYNTAX_ERROR: "0" - When enabled, JavaScript/JSX syntax errors will automatically cancel the overwrite operation (default is disabled)
PROTECTED_PATHS: Comma-separated list of file patterns or paths that cannot be accessed, supporting wildcards (e.g., ".env,.env,/etc/passwd")
{
"mcpServers": {
"text-editor": {
"command": "/home/daniel/pp/venvs/editor-mcp/bin/python",
"args": ["/home/daniel/pp/editor-mcp/src/text_editor/server.py"],
"env": {
"MAX_SELECT_LINES": "100",
"ENABLE_JS_SYNTAX_CHECK": "0",
"FAIL_ON_PYTHON_SYNTAX_ERROR": "1",
"FAIL_ON_JS_SYNTAX_ERROR": "0",
"PROTECTED_PATHS": "*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/.ssh/id_rsa"
}
}
}
}The Editor MCP provides 13 powerful tools for file manipulation, editing, and testing:
set_fileSets the current file to work with.
Parameters:
filepath (str): Absolute path to the file
Returns:
Confirmation message with the file path
skimReads full text from the current file. Each line is prefixed with its line number.
Returns:
Dictionary containing lines with their line numbers, total number of lines, and the max edit lines setting
Example output:
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"total_lines": 4,
"max_select_lines": 50
}readReads text from the current file from start line to end line.
Parameters:
start (int): Start line number (1-based indexing)
end (int): End line number (1-based indexing)
Returns:
Dictionary containing lines with their line numbers as keys, along with start and end line information
Example output:
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"start_line": 1,
"end_line": 4
}selectSelect a range of lines from the current file for subsequent overwrite operation.
Parameters:
start (int): Start line number (1-based)
end (int): End line number (1-based)
Returns:
Dictionary containing the selected lines, line range, and ID for verification
Note:
This tool validates the selection against max_select_lines
The selection details are stored for use in the overwrite tool
This must be used before calling the overwrite tool
overwritePrepare to overwrite a range of lines in the current file with new text.
Parameters:
new_lines (list): List of new lines to overwrite the selected range
Returns:
Diff preview showing the proposed changes
Note:
This is the first step in a two-step process:
First call overwrite() to generate a diff preview
Then call confirm() to apply or cancel() to discard the pending changes
This tool allows replacing the previously selected lines with new content
The number of new lines can differ from the original selection
For Python files (.py extension), syntax checking is performed before writing
For JavaScript/React files (.js, .jsx extensions), syntax checking is optional and can be disabled via the ENABLE_JS_SYNTAX_CHECK environment variable
confirmApply pending changes from the overwrite operation.
Returns:
Operation result with status and message
Note:
This is one of the two possible actions in the second step of the editing process
The selection is removed upon successful application of changes
cancelDiscard pending changes from the overwrite operation.
Returns:
Operation result with status and message
Note:
This is one of the two possible actions in the second step of the editing process
The selection remains intact when changes are cancelled
delete_fileDelete the currently set file.
Returns:
Operation result with status and message
new_fileCreates a new file and automatically sets it as the current file for subsequent operations.
Parameters:
filepath (str): Path of the new file
Returns:
Operation result with status, message, and selection info
The first line is automatically selected for editing
Behavior:
Automatically creates parent directories if they don't exist
Sets the newly created file as the current working file
The first line is pre-selected, ready for immediate editing
Protected Files Note:
Files matching certain patterns (like *.env) can be created normally
However, once you move to another file, these protected files cannot be reopened
This allows for a "write-once, protect-after" workflow for sensitive configuration files
Example: You can create config.env, populate it with example config, but cannot reopen it later
Note:
This tool will fail if the current file exists and is not empty
find_lineFind lines that match provided text in the current file.
Parameters:
search_text (str): Text to search for in the file
Returns:
Dictionary containing matching lines with their line numbers and total matches
Example output:
{
"status": "success",
"matches": [
[2, " print(\"Hello, world!\")"]
],
"total_matches": 1
}Note:
Returns an error if no file path is set
Searches for exact text matches within each line
The id can be used for subsequent edit operations
find_functionFind a function or method definition in the current Python or JavaScript/JSX file.
Parameters:
function_name (str): Name of the function or method to find
Returns:
Dictionary containing the function lines with their line numbers, start_line, and end_line
Example output:
{
"status": "success",
"lines": [
[10, "def hello():"],
[11, " print(\"Hello, world!\")"],
[12, " return True"]
],
"start_line": 10,
"end_line": 12
}Note:
For Python files, this tool uses Python's AST and tokenize modules to accurately identify function boundaries including decorators and docstrings
For JavaScript/JSX files, this tool uses a combination of approaches:
Primary method: Babel AST parsing when available (requires Node.js and Babel packages)
Fallback method: Regex pattern matching for function declarations when Babel is unavailable
Supports various JavaScript function types including standard functions, async functions, arrow functions, and React hooks
Returns an error if no file path is set or if the function is not found
listdirLists the contents of a directory.
Parameters:
dirpath (str): Path to the directory to list
Returns:
Dictionary containing list of filenames and the path queried
run_tests and set_python_pathTools for running Python tests with pytest and configuring the Python environment.
Set to "0", "false", or "no" to disable JavaScript syntax checking
Useful if you don't have Babel and related dependencies installed
FAIL_ON_PYTHON_SYNTAX_ERROR: Controls whether Python syntax errors automatically cancel the overwrite operation (default: 1)
When enabled, syntax errors in Python files will cause the overwrite action to be automatically cancelled
The lines will remain selected so you can fix the error and try again
FAIL_ON_JS_SYNTAX_ERROR: Controls whether JavaScript/JSX syntax errors automatically cancel the overwrite operation (default: 0)
When enabled, syntax errors in JavaScript/JSX files will cause the overwrite action to be automatically cancelled
The lines will remain selected so you can fix the error and try again
DUCKDB_USAGE_STATS: Controls whether usage statistics are collected in a DuckDB database (default: 0)
Set to "1", "true", or "yes" to enable collection of tool usage statistics
When enabled, records information about each tool call including timestamps and arguments
STATS_DB_PATH: Path where the DuckDB database for statistics will be stored (default: "text_editor_stats.duckdb")
Only used when DUCKDB_USAGE_STATS is enabled
PROTECTED_PATHS: Comma-separated list of file patterns or absolute paths that will be denied access
Example: *.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt
Supports both exact file paths and flexible glob patterns with wildcards in any position:
*.env - matches files ending with .env, like .env, dev.env, prod.env
.env* - matches files starting with .env, like .env, .env.local, .env.production
*secret* - matches any file containing 'secret' in the name
Provides protection against accidentally exposing sensitive configuration files and credentials
The lines will remain selected so you can fix the error and try again
The editor-mcp requires:
Python 3.7+
FastMCP package
black (for Python code formatting checks)
Babel (for JavaScript/JSX syntax checks if working with those files)
Install development dependencies:
# Using pip
pip install pytest pytest-asyncio pytest-cov
# Using uv
uv pip install pytest pytest-asyncio pytest-covFor JavaScript/JSX syntax validation, you need Node.js and Babel. The text editor uses npx babel to check JS/JSX syntax when editing these file types:
# Required for JavaScript/JSX syntax checking
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react
# You can also install these globally if you prefer
# npm install -g @babel/core @babel/cli @babel/preset-env @babel/preset-reactThe editor requires:
@babel/core and @babel/cli - Core Babel packages for syntax checking
@babel/preset-env - For standard JavaScript (.js) files
@babel/preset-react - For React JSX (.jsx) files
# Run tests
pytest -v
# Run tests with coverage
pytest -v --cov=text_editorThe test suite covers:
set_file tool
Setting valid files
Setting non-existent files
read tool
File state validation
Reading entire files
Reading specific line ranges
Edge cases like empty files
Invalid range handling
select tool
Line range validation
Selection validation against max_select_lines
Selection storage for subsequent operations
overwrite tool
Verification of selected content using ID
Content replacement validation
Syntax checking for Python and JavaScript/React files
Generation of diff preview for changes
confirm and cancel tools
Applying or canceling pending changes
Two-step verification process
delete_file tool
File deletion validation
new_file tool
File creation validation
Handling existing files
find_line tool
Finding text matches in files
Handling specific search terms
Error handling for non-existent files
Handling cases with no matches
Handling existing files
Unlike traditional code editing approaches where LLMs simply search for lines to edit and make replacements (often leading to confusion after multiple edits), this editor implements a structured multi-step workflow that dramatically improves editing accuracy:
set_file - First, the LLM sets which file it wants to edit
skim - The LLM reads the entire file to gain a complete overview
read - The LLM examines specific sections relevant to the task, with lines shown alongside numbers for better context
select - When ready to edit, the LLM selects specific lines (limited to a configurable number, default 50)
overwrite - The LLM proposes replacement content, resulting in a git diff-style preview that shows exactly what will change
confirm/cancel - After reviewing the preview, the LLM can either apply or discard the changes
This structured workflow forces the LLM to reason carefully about each edit and prevents common errors like accidentally overwriting entire files. By seeing previews of changes before committing them, the LLM can verify its edits are correct.
The server uses FastMCP to expose text editing capabilities through a well-defined API. The ID verification system ensures data integrity by verifying that the content hasn't changed between reading and modifying operations.
The ID mechanism uses SHA-256 to generate a unique identifier of the file content or selected line ranges. For line-specific operations, the ID includes a prefix indicating the line range (e.g., "L10-15-[hash]"). This helps ensure that edits are being applied to the expected content.
The main TextEditorServer class:
Initializes with a FastMCP instance named "text-editor"
Sets a configurable max_select_lines limit (default: 50) from environment variables
Maintains the current file path as state
Registers thirteen primary tools through FastMCP:
set_file: Validates and sets the current file path
skim: Reads the entire content of a file, returning a dictionary of line numbers to line text
read: Reads lines from specified line range, returning a structured dictionary of line content
select: Selects lines for subsequent overwrite operation
overwrite: Takes a list of new lines and prepares diff preview for changing content
confirm: Applies pending changes from the overwrite operation
cancel: Discards pending changes from the overwrite operation
delete_file: Deletes the current file
new_file: Creates a new file
find_line: Finds lines containing specific text
find_function: Finds function or method definitions in Python and JavaScript/JSX files
listdir: Lists contents of a directory
run_tests and set_python_path: Tools for running Python tests
The server runs using FastMCP's stdio transport by default, making it easy to integrate with various clients.
For optimal results with AI assistants, it's recommended to use the system prompt (see system_prompt.md) that helps guide the AI in making manageable, safe edits.
This system prompt helps the AI assistant:
Make incremental changes - Breaking down edits into smaller parts
Maintain code integrity - Making changes that keep the code functional
Work within resource limits - Avoiding operations that could overwhelm the system
Follow a verification workflow - Doing final checks for errors after edits
By incorporating this system prompt when working with AI assistants, you'll get more reliable editing behavior and avoid common pitfalls in automated code editing.
The text editor MCP can collect usage statistics when enabled, providing insights into how the editing tools are being used:
Data Collection: Statistics are collected in a DuckDB database when DUCKDB_USAGE_STATS is enabled
Tracked Information: Records tool name, arguments, timestamp, current file path, tool response, and request/client IDs
Storage Location: Data is stored in a DuckDB file specified by STATS_DB_PATH
Privacy: Everything is stored locally on your machine
The collected statistics can help understand usage patterns, identify common workflows, and optimize the editor for most frequent operations.
You can query the database using standard SQL via any DuckDB client to analyze usage patterns.
If you encounter issues:
Check file permissions
Verify that the file paths are absolute
Ensure the environment is using Python 3.7+
Inspired by a similar project: https://github.com/tumf/mcp-text-editor, which at first I forked, however I decided to rewrite the whole codebase from scratch so only the general idea stayed the same.
Cancel action
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Cancel action' gives no information about what the tool actually does behaviorally - whether it's a read-only status change, a destructive operation, what permissions are required, what side effects occur, or what the typical response looks like. The description is completely inadequate for understanding the tool's behavior.
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?
While 'Cancel action' is extremely brief, this is under-specification rather than effective conciseness. The two words fail to provide necessary information about the tool's purpose and usage. True conciseness would efficiently convey essential information, but this description is so sparse that it's essentially non-functional as documentation.
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 that the tool has no parameters but likely performs some meaningful action (cancellation), the description is incomplete. With no annotations to provide behavioral context and a description that offers only the most minimal information, an agent would struggle to understand when and how to use this tool appropriately. The existence of an output schema helps somewhat, but the description itself provides insufficient context for effective tool selection and 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 0 parameters with 100% schema description coverage, so the schema fully documents the parameter situation (none). The description doesn't need to compensate for any parameter documentation gaps. The baseline for zero parameters with full schema coverage is 4, as there are no parameters whose semantics need explanation beyond what the schema provides.
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 'Cancel action' is a tautology that essentially restates the tool name 'cancel'. It doesn't specify what type of action gets canceled, what resource is affected, or what the cancellation entails. While the name suggests a general cancellation function, the description adds no meaningful clarification beyond the name itself.
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 absolutely no guidance on when to use this tool versus alternatives. With sibling tools like 'confirm', 'delete_file', 'overwrite', and others that might represent different actions or states, there's no indication of what context triggers a cancellation, what prerequisites exist, or what alternatives might be appropriate in different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm action
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Confirm action' implies a mutation (confirmation typically changes state), but it doesn't specify what gets confirmed, whether it's reversible, what permissions are needed, or what the response contains. This leaves significant gaps for a tool that likely modifies workflow state.
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 extremely concise ('Confirm action') but arguably under-specified rather than efficiently informative. While it wastes no words, it fails to provide the minimal context needed to understand what's being confirmed, making this brevity problematic rather than virtuous.
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 likely performs a state-changing confirmation (implied by the name and sibling tools like 'cancel'), the description is incomplete. With no annotations, no parameter documentation needed, but an output schema exists, the description should at least clarify what action is confirmed and in what context, which it fails to do.
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 with 100% schema description coverage, so the schema already fully documents the absence of inputs. The description doesn't need to compensate for any parameter gaps, and 'Confirm action' appropriately implies no additional inputs are required for a simple confirmation operation.
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 'Confirm action' is a tautology that essentially restates the tool name 'confirm' without specifying what action is being confirmed or what resource is involved. It provides no differentiation from sibling tools like 'cancel' or 'select' that might also involve confirmation-like operations.
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. The description doesn't indicate what context triggers its use, what prerequisites exist, or how it differs from sibling tools like 'cancel' (which might abort an action) or 'select' (which might choose among options).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete current file
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't disclose if deletion is permanent, requires permissions, has side effects, or what happens on success/failure. 'Delete' implies destructive mutation, but specifics are missing.
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 at two words, front-loaded with the core action. Every word earns its place with no wasted text, though this brevity contributes to vagueness in other dimensions.
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 mutation tool with no annotations, the description is incomplete. It lacks context on what 'current' means, deletion behavior, permissions, or output. The presence of an output schema helps, but the description doesn't leverage it to explain return values or error conditions.
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 0 parameters with 100% schema coverage, so no parameter documentation is needed. The description doesn't add param info, but that's appropriate here, meeting the baseline for zero-param tools.
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 'Delete current file' clearly states the action (delete) and target (current file), but it's vague about what 'current' refers to in context. It doesn't distinguish this from potential sibling operations like 'overwrite' or 'cancel' that might also modify files.
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 'overwrite' or 'cancel'. The description implies it's for deletion but doesn't specify prerequisites, conditions, or what makes a file 'current'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a function or method definition in a Python or JS/JSX file. Uses AST parsers.
Args: function_name (str): Name of the function or method to find
Returns: dict: function lines with their line numbers, start_line, and end_line
| Name | Required | Description | Default |
|---|---|---|---|
| function_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool's behavior: it finds function/method definitions using AST parsers and returns line numbers and ranges. However, it doesn't mention error handling (e.g., if file doesn't exist or function isn't found), performance characteristics, or whether it searches recursively in directories. It adds value beyond the minimal schema but lacks comprehensive behavioral details.
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 efficiently structured with a clear purpose statement followed by Args and Returns sections. Every sentence earns its place: the first sentence defines the tool's core functionality, and the subsequent lines provide essential parameter and return value information 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?
Given the tool's moderate complexity (AST parsing across two languages), no annotations, and an output schema that likely defines the return dict structure, the description is reasonably complete. It covers what the tool does, the parameter meaning, and return format. However, it could better address error cases or language-specific quirks (e.g., JSX vs JS differences) for full completeness.
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% description coverage, so the description must compensate. It clearly explains the single parameter 'function_name' as 'Name of the function or method to find', which adds essential semantic meaning not present in the bare schema. However, it doesn't specify case-sensitivity, partial matching, or handling of nested methods (e.g., 'ClassName.method_name'), leaving some ambiguity.
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 specific action ('Find a function or method definition'), the target resources ('in a Python or JS/JSX file'), and the implementation method ('Uses AST parsers'). It distinguishes itself from siblings like 'find_line' (general line search) and 'skim' (likely file overview) by focusing specifically on function/method definitions with AST parsing.
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 usage context by specifying 'Python or JS/JSX file' and 'function or method definition', suggesting it should be used when searching for function definitions in those file types. However, it doesn't explicitly state when NOT to use it or name alternatives like 'find_line' for non-function searches or 'skim' for file overviews.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find lines that match provided text in the current file.
Args: search_text (str): Text to search for in the file
Returns: dict: Matching lines with their line numbers, and full text
| Name | Required | Description | Default |
|---|---|---|---|
| search_text | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool finds matching lines but does not disclose behavioral traits such as case sensitivity, regex support, search scope (e.g., whole file vs. visible portion), or performance considerations (e.g., large file handling). The description is minimal beyond the basic operation.
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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by structured Args and Returns sections. Every sentence earns its place with no redundant information, making it efficient and easy to parse.
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 low complexity (one parameter) and the presence of an output schema (which covers return values), the description is mostly complete. It explains what the tool does and the parameter, but lacks behavioral details (e.g., search behavior) that would be helpful despite the output schema.
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 (schema has no descriptions), the description must compensate. It adds meaning by specifying that 'search_text' is 'Text to search for in the file', clarifying the parameter's purpose. However, it does not detail constraints (e.g., length, special characters) or examples, leaving some gaps.
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 specific action ('Find lines that match provided text') and resource ('in the current file'), distinguishing it from siblings like 'find_function' (which likely searches for functions) and 'read' (which reads the entire file). The verb+resource combination is precise and 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?
The description implies usage for text matching in a file, but does not explicitly state when to use this tool versus alternatives like 'find_function' (for functions) or 'skim' (purpose unclear). No exclusions or prerequisites are mentioned, leaving the agent to infer context from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| dirpath | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new file.
After creating new file, the first line is automatically selected for editing. Automatically creates parent directories if they don't exist.
Args: filepath (str): Path of the new file Returns: dict: Status message with selection info
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it creates a file, automatically selects the first line for editing, and creates parent directories if missing. This covers mutation behavior and side effects, though it doesn't mention permissions, error handling, or rate limits, which are gaps for a tool with no 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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by important behavioral details, and ends with structured Args and Returns sections. Every sentence adds value without redundancy, making it efficient and easy to parse.
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 moderate complexity (file creation with side effects), no annotations, and an output schema present, the description is fairly complete. It explains the action, behavioral traits, and parameter semantics, but could improve by addressing error cases or interaction with siblings. The output schema handles return values, so the description's focus on other aspects is appropriate.
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 meaningful context for the single parameter 'filepath' by explaining it's the 'Path of the new file', which clarifies its purpose beyond the schema's basic type definition. With 0% schema description coverage and only one parameter, this compensation is effective, though it doesn't detail format constraints or examples.
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 with the verb 'creates' and resource 'new file', making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'overwrite' or 'set_file', which might also involve file creation or modification, leaving room for ambiguity in tool selection.
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 usage for creating new files and automatically handling parent directories, but provides no explicit guidance on when to use this tool versus alternatives like 'overwrite' or 'set_file'. It mentions automatic post-creation actions (first line selection), which hints at context, but lacks clear when-to-use or when-not-to-use directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overwrite the selected lines with new text. Amount of new lines can differ from the original selection
Args: new_lines (dict): Example: {"lines":["line one", "second line"]}
Returns: dict: Diff preview showing the proposed changes, and any syntax errors for JS or Python
| Name | Required | Description | Default |
|---|---|---|---|
| new_lines | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool overwrites lines and returns a diff preview with syntax errors for JS or Python, which adds useful context about output and language-specific behavior. However, it lacks details on permissions, side effects (e.g., whether changes are immediate or require confirmation), or error handling, leaving gaps for a mutation 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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by key behavioral details. The Args and Returns sections are structured but could be more integrated. There's minimal waste, though the example in Args might be slightly verbose; overall, it earns its place efficiently.
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 complexity (mutation with 1 parameter, nested objects, and an output schema), the description is partially complete. It explains the action and return values, and the output schema likely covers the diff preview details, reducing the burden. However, with no annotations and low schema coverage, it misses critical context like safety, prerequisites, and full parameter semantics, making it adequate but with clear gaps.
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 description coverage is 0%, so the description must compensate. It provides an example for the 'new_lines' parameter (a dict with a 'lines' key containing an array of strings), which adds meaning beyond the generic object type in the schema. However, it doesn't explain the structure fully (e.g., other possible keys, constraints) or cover nested object details, resulting in incomplete parameter documentation.
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: 'Overwrite the selected lines with new text' specifies the verb (overwrite) and resource (selected lines). It distinguishes from siblings like 'delete_file' or 'set_file' by focusing on line-level text replacement rather than file operations. However, it doesn't explicitly differentiate from similar text-editing siblings that might exist, keeping it at 4 instead of 5.
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. The description mentions that the amount of new lines can differ from the original selection, which implies a context of line editing, but it doesn't specify prerequisites (e.g., needing a selection first), exclusions, or direct comparisons to siblings like 'set_file' or 'confirm'. This leaves the agent without clear usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read lines from the current file from start line to end line, returning them in a dictionary like {"lines":[[1,"text on first line"],[2,"text on second line"]]}. This makes it easier to find the precise lines to select for editing.
Args: start (int, optional): Start line number end (int, optional): End line number
Returns: dict: lines, start_line, end_line
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes | ||
| end | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool reads lines and returns them in a specific dictionary format, which is useful. However, it lacks details on error handling, file state changes, or permissions needed, leaving behavioral gaps for a read operation.
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 appropriately sized and front-loaded with the core functionality in the first sentence. The Args and Returns sections are structured but slightly verbose; every sentence adds value, though it 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 tool's low complexity, no annotations, and an output schema present, the description is fairly complete. It explains the purpose, parameters, and return format adequately. However, it could improve by addressing error cases or interaction with sibling tools for better context.
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 description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'start' and 'end' are line numbers and are optional in the Args section, clarifying their role in selecting lines. However, it doesn't detail default behaviors or constraints beyond basic types.
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 specific action ('Read lines from the current file') and resource ('current file'), distinguishing it from siblings like 'skim' or 'select'. It precisely defines what the tool does without being vague or 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 description implies usage for editing by mentioning 'easier to find the precise lines to select for editing', but does not explicitly state when to use this tool versus alternatives like 'skim' or 'find_line'. No exclusions or clear alternatives are provided, leaving usage context somewhat implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run pytest tests using the specified Python virtual environment.
Args: test_path (str, optional): Directory or file path containing tests to run test_name (str, optional): Specific test function/method to run verbose (bool, optional): Run tests in verbose mode collect_only (bool, optional): Only collect tests without executing them
Returns: dict: Test execution results including returncode, output, and execution time
| Name | Required | Description | Default |
|---|---|---|---|
| test_path | No | ||
| test_name | No | ||
| verbose | No | ||
| collect_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but provides minimal behavioral context. It mentions the tool runs tests in a virtual environment but doesn't disclose critical behaviors like: whether it modifies files, what happens if tests fail, if it requires specific permissions, execution timeouts, or how results are structured beyond the basic return dict. The description doesn't contradict annotations (none exist).
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 well-structured with clear sections (purpose statement, Args, Returns) and appropriately sized. The opening sentence efficiently states the core purpose. The Args section is necessary given the 0% schema coverage. Only minor improvement possible by integrating parameter explanations more seamlessly.
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 4 parameters with 0% schema coverage and no annotations, the description does a good job explaining parameters and return values. However, for a test execution tool that could have significant behavioral implications (modifying state, long-running processes, failure modes), the description lacks important context about execution environment, error handling, and behavioral constraints that would be needed for safe agent use.
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 well by clearly explaining all 4 parameters in the Args section, adding meaningful context about what each parameter controls. The description provides semantic value beyond the bare schema by explaining test_path accepts 'Directory or file path', test_name is for 'Specific test function/method', and what collect_only actually does ('Only collect tests without executing them').
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 specific action ('Run pytest tests') and resource ('using the specified Python virtual environment'), distinguishing it from all sibling tools which are file/function operations rather than test execution. The verb 'Run' is precise and 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 about when to use this tool versus alternatives. While it's clearly for running pytest tests, there's no mention of prerequisites (e.g., needing a virtual environment setup), when to use collect_only versus full execution, or how it relates to other testing tools (none exist among siblings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select lines from for subsequent overwrite operation.
Args: start (int): Start line number (1-based) end (int): End line number (1-based)
Returns: dict: status, lines, start, end, id, line_count, message
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes | ||
| end | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but provides minimal behavioral information. It mentions this is for a 'subsequent overwrite operation' which implies this is a preparatory step, but doesn't describe what happens during the selection (does it lock lines? create a temporary buffer? require specific permissions?). No information about side effects, error conditions, or performance characteristics.
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 appropriately brief with clear sections (purpose statement, Args, Returns). The first sentence could be more polished ('Select lines from' is incomplete), but overall the structure is efficient with no wasted words. Each section serves a clear purpose.
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 there's an output schema (Returns section), the description doesn't need to explain return values in detail. However, for a tool with no annotations and only 2 parameters, the description provides adequate but minimal context. It explains what the tool does and documents parameters, but lacks information about error conditions, prerequisites, or how it integrates with the 'overwrite' sibling 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?
The description includes an Args section that clearly documents both parameters with their types and meaning (line numbers, 1-based). With 0% schema description coverage and only 2 parameters, this documentation fully compensates for the schema gap. The parameter information is complete and adds meaningful context beyond the bare 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 states the tool 'Select lines from for subsequent overwrite operation' which indicates a selection function but is grammatically awkward and vague about what resource is being selected from. It distinguishes from siblings like 'overwrite' by indicating this is a preparatory step, but doesn't clarify what type of content or file is involved.
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 mentions this is 'for subsequent overwrite operation' which provides some context about when to use it, but doesn't explicitly state when NOT to use it or what alternatives exist. No guidance is given about prerequisites or how this tool relates to other file operations in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the current file to work with.
This is always the first step in the workflow. You must set a file before you can use other tools like read, select etc.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool sets a file as a prerequisite for other operations, implying a stateful context, but doesn't disclose behavioral traits like whether the file must exist, what happens on invalid paths, if this persists across sessions, or any error conditions. For a tool with no annotations, this leaves significant gaps.
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 well-structured: two sentences that efficiently convey purpose and usage guidelines without redundancy. Every sentence adds value, and it's front-loaded with the core action.
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 moderate complexity (stateful operation with a prerequisite role), no annotations, and an output schema present (which may cover return values), the description is partially complete. It explains the workflow role but lacks details on parameter semantics and behavioral transparency, making it adequate but with clear gaps.
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 1 parameter with 0% description coverage. The description doesn't add any meaning beyond the schema—it doesn't explain what 'filepath' represents (e.g., absolute/relative path, format, constraints). With low schema coverage, the description fails to compensate, but since there's only one parameter, the baseline is slightly higher than minimal.
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: 'Set the current file to work with.' This is a specific verb ('set') and resource ('current file'), making the action understandable. However, it doesn't explicitly differentiate from sibling tools like 'new_file' or 'delete_file' beyond workflow context.
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 explicit usage guidance: 'This is always the first step in the workflow. You must set a file before you can use other tools like read, select etc.' It clearly states when to use it (first step) and why (prerequisite for other tools), with named alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set it before running tests so the project is correctly recognized
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a configuration change ('set') but doesn't disclose behavioral traits like whether it's persistent, requires specific permissions, or has side effects. For a mutation tool with no annotations, this is inadequate.
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, efficient sentence that is front-loaded with the key information. It wastes no words and is appropriately sized for its purpose, earning full marks for conciseness.
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 complexity as a configuration setter with no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks details on behavior, parameter usage, and expected outcomes, making it insufficient for effective tool 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 input schema has 1 parameter with 0% description coverage, and the tool description doesn't add any meaning about the 'path' parameter. It fails to explain what the path represents, its format, or examples, leaving the parameter semantics unclear.
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 the tool's purpose is to 'set' something 'before running tests' for project recognition, which is clear but vague. It doesn't specify what exactly is being set (Python path) or distinguish it from siblings like 'set_file', making it moderately helpful but lacking specificity.
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 explicit context for when to use it ('before running tests'), which is helpful guidance. However, it doesn't mention when not to use it or alternatives among siblings, such as how it differs from 'set_file', leaving some gaps in usage differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read text from the current file, truncated to the first SKIM_MAX_LINES lines.
Returns: dict: lines, total_lines, max_select_lines
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'Read text'), truncates output based on `SKIM_MAX_LINES`, and returns a dict with specific keys. However, it doesn't mention permissions, error conditions, or how `SKIM_MAX_LINES` is defined (e.g., environment variable, default value), leaving some gaps.
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 highly concise and well-structured: the first sentence states the core action and constraint, and the second sentence clearly outlines the return format. Every sentence earns its place with no wasted words, making it easy to parse and front-loaded with essential 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?
Given the tool's low complexity (0 parameters, read-only operation) and the presence of an output schema (implied by 'Returns: dict'), the description is mostly complete. It covers purpose, behavior, and output structure. However, it lacks details on `SKIM_MAX_LINES` (e.g., source or default) and any prerequisites (e.g., needing a file set via 'set_file'), which would enhance completeness 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?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on behavior and output. A baseline of 4 is applied since no parameters exist, and the description adds value by explaining the tool's operation beyond the empty 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 the tool's purpose with specific verbs ('Read text from the current file') and resource ('current file'), distinguishing it from siblings like 'read' (which presumably reads the entire file) by specifying truncation behavior. It explicitly mentions the truncation limit ('first `SKIM_MAX_LINES` lines'), making the scope 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?
The description implies usage context by specifying it reads from 'the current file' (suggesting a file must already be selected/opened) and truncates output, which differentiates it from tools like 'read' (full file reading) or 'select' (line selection). However, it doesn't explicitly state when NOT to use it or name alternatives, missing full sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but 'cancel' and 'confirm' are ambiguous without context, and 'find_function' and 'find_line' could be confused as both search within files. The core editing tools like 'read', 'select', and 'overwrite' are clearly differentiated, supporting a coherent workflow.
The naming is mixed with some consistency: verbs like 'find', 'set', and 'run' are used, but patterns vary (e.g., 'listdir' vs. 'new_file', 'overwrite' vs. 'select'). There's no uniform verb_noun structure, making it readable but not predictable across all tools.
With 14 tools, this is well-scoped for an editor server, covering file operations, editing, searching, and testing. Each tool serves a specific role in the workflow, and the count is neither too sparse nor overwhelming for the domain.
The toolset provides strong coverage for file editing and testing workflows, including create, read, update, and delete operations. Minor gaps exist, such as no explicit 'save' or 'undo' tools, but agents can work around these using existing tools like 'overwrite' and workflow steps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A simple MCP server built with FastMCP and python
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/danielpodrazka/editor-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
