一个基于 Python 的文本编辑器服务器，使用 FastMCP 构建，提供强大的文件操作工具。该服务器通过标准化 API 实现文本文件的读取、编辑和管理，并采用独特的多步骤方法，显著提高了法学硕士 (LLM) 和 AI 助手的代码编辑准确性和可靠性。
文件选择：使用绝对路径设置要使用的文件
读取操作：
使用skim读取带有行号的整个文件
使用read读取带有前缀行号的特定行范围
使用find_line查找文件中的特定文本
使用find_function查找并提取 Python 和 JavaScript/JSX 文件中的函数定义
编辑操作：
带有差异预览的两步编辑流程
选择并覆盖带有身份验证的文本
通过选择→覆盖→确认/取消模式简化编辑工作流程
Python（.py）和 JavaScript/React（.js、.jsx）文件的语法检查
创建具有内容的新文件
文件管理：
使用适当的初始化创建新文件
从文件系统中删除文件
使用listdir列出目录内容
测试支持：
使用run_tests运行 Python 测试
设置 Python 路径以进行正确的模块解析
安全特性：
内容 ID 验证以防止冲突
限制行数以防止资源耗尽
语法检查以维护代码完整性
受保护的路径以限制对敏感文件的访问
Related MCP server: MCP File Manager
editor-mcp 包含强大的功能，但同时也考虑了一定的安全问题：
越狱风险：editor-mcp 在读取嵌入有害指令的文件时，可能会被越狱。正在编辑的文件中可能包含操纵 AI 助手的指令。
任意代码执行：如果启用运行测试，则存在通过操纵的测试文件或恶意 Python 代码执行任意代码的风险。
数据暴露：如果未配置适当的路径保护，访问文件系统操作可能会暴露敏感信息。
为了减轻这些风险：
使用PROTECTED_PATHS环境变量来限制对敏感文件和目录的访问。
除非绝对必要，否则禁用生产环境中的测试运行功能。
打开文件之前请仔细检查，尤其是来自不受信任来源的文件。
考虑在权限有限的沙盒环境中运行编辑器。
该文本编辑器的独特设计解决了通常影响 LLM 代码编辑的关键问题：
防止上下文丢失——传统方法通常会导致 LLM 在几次编辑后就失去对代码库的概览。此实现可在多步骤过程中保持上下文。
避免资源密集型重写- LLM 通常默认在发生混淆时替换整个文件，这既耗时又慢，效率也低。此编辑器强制执行选择性编辑。
提供视觉反馈- 差异预览系统允许 LLM 在提交更改之前实际查看和验证更改，从而大大减少错误。
强制语法检查——Python 和 JavaScript/React 的自动验证确保不会提交损坏的代码。
改进编辑推理- 多步骤方法使 LLM 有时间在步骤之间进行推理，从而减少随意的标记生成。
编辑器实施了多项保护措施以确保系统稳定性并防止资源耗尽：
最大编辑行数：默认情况下，编辑器对任何单个编辑操作强制执行 50 行的限制
此 MCP 是基于 Claude Desktop 开发和测试的。您可以在任何平台上下载 Claude Desktop。对于 Linux 上的 Claude Desktop，您可以使用非官方安装脚本（使用官方文件），推荐的仓库： https://github.com/emsi/claude-desktop/tree/main
安装 Claude Desktop 后，请按照以下说明安装此特定的 MCP：
安装 Editor MCP 最简单的方法是使用提供的安装脚本：
# Clone the repository
git clone https://github.com/danielpodrazka/editor-mcp.git
cd editor-mcp
# Run the installation script
chmod +x install.sh
./install.sh该脚本将：
检查是否安装了UVX，如有必要则安装
以开发模式安装 Editor MCP
使editor-mcp命令在你的 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 .从锁定文件安装：
uv pip install -r uv.lockuv pip compile requirements.in -o uv.lock安装后，您可以使用以下方法之一启动 Editor MCP 服务器：
# Using the installed script
editor-mcp
# Or using the Python module
python -m text_editor.server您可以将编辑器 MCP 添加到您的 MCP 配置文件中：
{
"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"
}
}
}
}Editor MCP 支持多个环境变量来定制其行为：
MAX_SELECT_LINES ：“100” - 一次操作中可编辑的最大行数（默认值为 50）
ENABLE_JS_SYNTAX_CHECK ：“0”-启用/禁用 JavaScript 和 JSX 语法检查（默认为“1”-启用）
FAIL_ON_PYTHON_SYNTAX_ERROR : “1” - 启用时，Python 语法错误将自动取消覆盖操作（默认启用）
FAIL_ON_JS_SYNTAX_ERROR ：“0” - 启用时，JavaScript/JSX 语法错误将自动取消覆盖操作（默认禁用）
PROTECTED_PATHS ：以逗号分隔的无法访问的文件模式或路径列表，支持通配符（例如“ .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"
}
}
}
}Editor MCP 提供了 13 个强大的文件操作、编辑和测试工具：
set_file设置要使用的当前文件。
参数：
filepath （str）：文件的绝对路径
返回：
带有文件路径的确认消息
skim从当前文件读取全文。每行都以行号作为前缀。
返回：
包含行及其行号、总行数和最大编辑行数设置的字典
示例输出：
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"total_lines": 4,
"max_select_lines": 50
}read从当前文件读取从起始行到结束行的文本。
参数：
start （int）：起始行号（从 1 开始索引）
end （int）：结束行号（从 1 开始索引）
返回：
字典包含以行号为键的行，以及开始和结束行的信息
示例输出：
{
"lines": [
[1, "def hello():"],
[2, " print(\"Hello, world!\")"],
[3, ""],
[4, "hello()"]
],
"start_line": 1,
"end_line": 4
}select从当前文件中选择一定范围的行以进行后续的覆盖操作。
参数：
start （int）：起始行号（从 1 开始）
end （int）：结束行号（从 1 开始）
返回：
包含所选行、行范围和用于验证的 ID 的字典
笔记：
此工具根据 max_select_lines 验证选择
选择详细信息将存储在覆盖工具中以供使用
必须在调用覆盖工具之前使用
overwrite准备用新文本覆盖当前文件中的一系列行。
参数：
new_lines （列表）：用于覆盖所选范围的新行列表
返回：
显示建议更改的差异预览
笔记：
这是两步流程的第一步：
首先调用 overwrite() 来生成差异预览
然后调用confirm()来应用或调用cancel()来放弃待处理的更改
此工具允许用新内容替换先前选择的行
新行的数量可以与原始选择的数量不同
对于 Python 文件（.py 扩展名），在写入之前执行语法检查
对于 JavaScript/React 文件（.js、.jsx 扩展名），语法检查是可选的，可以通过ENABLE_JS_SYNTAX_CHECK环境变量禁用
confirm应用覆盖操作中未完成的更改。
返回：
带有状态和消息的操作结果
笔记：
这是编辑过程第二步中可能采取的两种操作之一
成功应用更改后，选择将被删除
cancel放弃覆盖操作中未完成的更改。
返回：
带有状态和消息的操作结果
笔记：
这是编辑过程第二步中可能采取的两种操作之一
取消更改后，选择保持不变
delete_file删除当前设置的文件。
返回：
带有状态和消息的操作结果
new_file创建新文件。
参数：
absolute_file_path (str)：新文件的路径
返回：
操作结果，包括状态和内容 ID（如果适用）
笔记：
如果当前文件存在且不为空，此工具将失败
find_line在当前文件中查找与提供的文本匹配的行。
参数：
search_text （str）：要在文件中搜索的文本
返回：
包含匹配行及其行号和总匹配数的字典
示例输出：
{
"status": "success",
"matches": [
[2, " print(\"Hello, world!\")"]
],
"total_matches": 1
}笔记：
如果没有设置文件路径则返回错误
在每一行中搜索精确的文本匹配
该 ID 可用于后续的编辑操作
find_function在当前 Python 或 JavaScript/JSX 文件中查找函数或方法定义。
参数：
function_name (str)：要查找的函数或方法的名称
返回：
包含函数行及其行号、起始行和结束行的字典
示例输出：
{
"status": "success",
"lines": [
[10, "def hello():"],
[11, " print(\"Hello, world!\")"],
[12, " return True"]
],
"start_line": 10,
"end_line": 12
}笔记：
对于 Python 文件，此工具使用 Python 的 AST 和 tokenize 模块来准确识别函数边界，包括装饰器和文档字符串
对于 JavaScript/JSX 文件，此工具使用以下方法组合：
主要方法：Babel AST 解析（需要 Node.js 和 Babel 包）
后备方法：Babel 不可用时，函数声明的正则表达式模式匹配
支持各种 JavaScript 函数类型，包括标准函数、异步函数、箭头函数和 React hooks
如果未设置文件路径或未找到函数，则返回错误
listdir列出目录的内容。
参数：
dirpath （str）：要列出的目录的路径
返回：
包含文件名列表和查询路径的字典
run_tests和set_python_path使用 pytest 运行 Python 测试和配置 Python 环境的工具。
设置为“0”、“false”或“no”以禁用 JavaScript 语法检查
如果你没有安装 Babel 和相关依赖项，则很有用
FAIL_ON_PYTHON_SYNTAX_ERROR ：控制 Python 语法错误是否自动取消覆盖操作（默认值：1）
启用后，Python 文件中的语法错误将导致覆盖操作自动取消
这些行将保持选中状态，以便您可以修复错误并重试
FAIL_ON_JS_SYNTAX_ERROR ：控制 JavaScript/JSX 语法错误是否自动取消覆盖操作（默认值：0）
启用后，JavaScript/JSX 文件中的语法错误将导致覆盖操作自动取消
这些行将保持选中状态，以便您可以修复错误并重试
DUCKDB_USAGE_STATS ：控制是否在 DuckDB 数据库中收集使用情况统计信息（默认值：0）
设置为“1”、“true”或“yes”以启用工具使用情况统计信息的收集
启用后，记录每个工具调用的信息，包括时间戳和参数
STATS_DB_PATH ：存储统计信息的 DuckDB 数据库的路径（默认值：“text_editor_stats.duckdb”）
仅在启用DUCKDB_USAGE_STATS时使用
PROTECTED_PATHS ：将被拒绝访问的文件模式或绝对路径的逗号分隔列表
例如： *.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt
支持精确的文件路径和任意位置带有通配符的灵活 glob 模式：
*.env - 匹配以 .env 结尾的文件，例如.env 、 dev.env 、 prod.env
.env* - 匹配以 .env 开头的文件，例如.env 、 .env.local 、 .env.production
*secret* - 匹配名称中包含“secret”的任何文件
提供保护，防止意外暴露敏感配置文件和凭据
这些行将保持选中状态，以便您可以修复错误并重试
editor-mcp 需要：
Python 3.7+
FastMCP 包
黑色（用于 Python 代码格式检查）
Babel（用于检查使用这些文件时的 JavaScript/JSX 语法）
安装开发依赖项：
# Using pip
pip install pytest pytest-asyncio pytest-cov
# Using uv
uv pip install pytest pytest-asyncio pytest-cov要进行 JavaScript/JSX 语法验证，您需要 Node.js 和 Babel。文本编辑器在编辑以下文件类型时使用npx babel检查 JS/JSX 语法：
# 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-react编辑器要求：
@babel/core和@babel/cli - 用于语法检查的核心 Babel 包
@babel/preset-env - 用于标准 JavaScript (.js) 文件
@babel/preset-react - 用于 React JSX（.jsx）文件
# Run tests
pytest -v
# Run tests with coverage
pytest -v --cov=text_editor测试套件涵盖：
set_file 工具
设置有效文件
设置不存在的文件
阅读工具
文件状态验证
读取整个文件
读取特定行范围
诸如空文件之类的边缘情况
无效范围处理
选择工具
行范围验证
针对 max_select_lines 的选择验证
后续操作的选择存储
覆盖工具
使用 ID 验证所选内容
内容替换验证
Python 和 JavaScript/React 文件的语法检查
生成变更的差异预览
确认和取消工具
应用或取消待处理的更改
两步验证流程
delete_file 工具
文件删除验证
new_file 工具
文件创建验证
处理现有文件
find_line 工具
在文件中查找文本匹配
处理特定搜索词
不存在文件的错误处理
处理无匹配项的案例
处理现有文件
与传统的代码编辑方法不同，在传统的代码编辑方法中，LLM 只是搜索要编辑的行并进行替换（多次编辑后通常会造成混乱），而此编辑器实现了结构化的多步骤工作流程，可显著提高编辑准确性：
set_file - 首先，LLM 设置要编辑的文件
skim - LLM 阅读整个文件以获得完整的概述
阅读- LLM 检查与任务相关的特定部分，并在数字旁边显示行，以便更好地理解上下文
选择- 准备编辑时，LLM 选择特定行（限制为可配置数量，默认为 50）
覆盖- LLM 建议替换内容，从而生成一个 git diff 样式的预览，准确显示将要更改的内容
确认/取消- 审阅预览后，LLM 可以应用或放弃更改
这种结构化的工作流程迫使法学硕士 (LLM) 仔细推敲每一次编辑，并避免诸如意外覆盖整个文件之类的常见错误。通过在提交更改之前查看预览，LLM 可以验证其编辑是否正确。
服务器使用 FastMCP 通过定义明确的 API 公开文本编辑功能。身份验证系统通过验证内容在读取和修改操作之间是否发生变化来确保数据完整性。
ID 机制使用 SHA-256 生成文件内容或选定行范围的唯一标识符。对于特定行的操作，ID 包含指示行范围的前缀（例如，“L10-15-[hash]”）。这有助于确保编辑操作应用于预期内容。
主要的TextEditorServer类：
使用名为“text-editor”的 FastMCP 实例进行初始化
从环境变量设置可配置的max_select_lines限制（默认值：50）
保持当前文件路径为状态
通过 FastMCP 注册十三个主要工具：
set_file ：验证并设置当前文件路径
skim ：读取文件的全部内容，返回行号字典到行文本
read ：从指定的行范围内读取行，返回行内容的结构化字典
select ：选择用于后续覆盖操作的行
overwrite ：获取新行列表并准备差异预览以更改内容
confirm ：应用覆盖操作中未完成的更改
cancel ：放弃覆盖操作中未完成的更改
delete_file ：删除当前文件
new_file ：创建一个新文件
find_line ：查找包含特定文本的行
find_function ：在 Python 和 JavaScript/JSX 文件中查找函数或方法定义
listdir ：列出目录的内容
run_tests和set_python_path ：运行 Python 测试的工具
服务器默认使用 FastMCP 的 stdio 传输运行，从而可以轻松与各种客户端集成。
为了获得 AI 助手的最佳效果，建议使用系统提示（参见system_prompt.md ），以帮助指导 AI 进行可管理、安全的编辑。
该系统提示可以帮助AI助手：
进行增量更改- 将编辑分解为更小的部分
维护代码完整性——进行修改以保持代码正常运行
在资源限制内工作- 避免可能使系统不堪重负的操作
遵循验证工作流程- 编辑后进行最终错误检查
通过在使用 AI 助手时加入此系统提示，您将获得更可靠的编辑行为并避免自动代码编辑中常见的陷阱。
文本编辑器 MCP 在启用时可以收集使用情况统计信息，从而提供有关编辑工具使用方式的见解：
数据收集：启用DUCKDB_USAGE_STATS后，统计信息将收集到 DuckDB 数据库中
跟踪信息：记录工具名称、参数、时间戳、当前文件路径、工具响应和请求/客户端 ID
存储位置：数据存储在STATS_DB_PATH指定的DuckDB文件中
隐私：所有内容都存储在您的本地计算机上
收集到的统计数据有助于了解使用模式、识别常见的工作流程并针对最常见的操作优化编辑器。
您可以通过任何 DuckDB 客户端使用标准 SQL 查询数据库来分析使用模式。
如果您遇到问题：
检查文件权限
验证文件路径是否是绝对路径
确保环境使用的是 Python 3.7+
受到类似项目的启发： https://github.com/tumf/mcp-text-editor ，起初我分叉了它，但我决定从头开始重写整个代码库，因此只有总体思路保持不变。
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0find_function1 field changedInput schema / properties / function_name / titleRemoved value: -"Function Name"find_line1 field changedInput schema / properties / search_text / titleRemoved value: -"Search Text"listdir1 field changedInput schema / properties / dirpath / titleRemoved value: -"Dirpath"new_file1 field changedInput schema / properties / filepath / titleRemoved value: -"Filepath"overwrite1 field changedInput schema / properties / new_lines / titleRemoved value: -"New Lines"read2 fields changedInput schema / properties / end / titleRemoved value: -"End"Input schema / properties / start / titleRemoved value: -"Start"run_tests4 fields changedInput schema / properties / collect_only / titleRemoved value: -"Collect Only"Input schema / properties / test_name / titleRemoved value: -"Test Name"Input schema / properties / test_path / titleRemoved value: -"Test Path"Input schema / properties / verbose / titleRemoved value: -"Verbose"select2 fields changedInput schema / properties / end / titleRemoved value: -"End"Input schema / properties / start / titleRemoved value: -"Start"set_file3 fields changedInput schema / properties / filepath / titleRemoved value: -"Filepath"Output schema / properties / result / titleRemoved value: -"Result"Output schema / titleRemoved value: -"_WrappedResult"set_python_path1 field changedInput schema / properties / path / titleRemoved value: -"Path"cancelconfirmdelete_filefind_functionfind_linelistdirnew_fileoverwritereadrun_testsselectset_fileset_python_pathskimScored across 14 tools
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.
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.
