A
licenseNot graded
qualityF
maintenanceGo server implementing Model Context Protocol (MCP) for filesystem operations.
695
MIT
Filesystem MCP Server
OfficialThis server lets an MCP client securely read, write, search, and manage files and directories only within allowed roots.
Read complete text files with optional
head/taillimits, including the deprecatedread_filealias.Read media files as image/audio/embedded resource content and read multiple files in one call.
Write/overwrite files and perform line-based edits, with optional dry-run diff previews.
Create directories; list directory contents with optional sizes/sorting; generate recursive directory trees.
Search files and directories by glob pattern with exclusions; move/rename files and directories.
Get file/directory metadata and list allowed directories.
Enforce allowed-directory access control, run in read-only mode exposing only read/list tools, and support deprecated Roots for 2025-era clients.
Read files through
file://resource URIs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Filesystem MCP Serverlist the files in my Documents folder"
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.
Filesystem MCP Server
Node.js server implementing Model Context Protocol (MCP) for filesystem operations.
Published on npm as @modelcontextprotocol/server-filesystem.
Features
Read/write files
Create/list/delete directories
Move files/directories
Search files
Get file metadata
Directory access control from command-line arguments, with Roots as a deprecated, 2025-era convenience
Serves both protocol eras on stdio: 2026-07-28 clients (
server/discover, no handshake) and 2025-era clients (initialize)
Related MCP server: Filesystem MCP Server
Directory Access Control
The server may touch only its allowed directories. Pass them on the command line. A 2025-era client that supports Roots can also replace them at runtime, but Roots is deprecated as of protocol version 2026-07-28 and a 2026-07-28 connection cannot use it.
Method 1: Command-line Arguments (Recommended)
Specify Allowed directories when starting the server:
mcp-server-filesystem /path/to/dir1 /path/to/dir2This is the only method that works on every protocol version, so it is the one to use.
Read-only Mode
Add --read-only to serve only the tools that cannot change the filesystem:
mcp-server-filesystem --read-only /path/to/dir1 /path/to/dir2The server then registers only the tools annotated readOnlyHint: true in the Tool annotations table, the ones that read and list. Every tool not annotated readOnlyHint: true, that is every tool that writes (such as write_file and edit_file), is left out, so a client never lists it and a call to it fails as an unknown tool. A tool added later follows the same rule through its annotation. The server enforces this, whatever the client is configured to allow, and it works the same with npx as with Docker. It applies on both protocol eras, and to directories that come from a client's Roots.
The flag may appear anywhere among the arguments. -- ends the options, so a directory literally named --read-only can be given after it.
Read-only mode covers every allowed directory. To make only some of them read-only, run two servers: one with --read-only for the directories to protect, and one without it for the rest. That separation holds only while the writable server keeps its command-line directories: a 2025-era client that supports Roots replaces them (see Method 2), so it could expose a protected directory to the writable server, unless that server is started with --confine-roots (see below). Where that matters, make the protected directories read-only at the operating-system level as well, with file permissions or, with Docker, a bind mount's ro flag.
Method 2: MCP Roots (Deprecated, 2025-era clients only)
A client that connects with a 2025-era protocol version (the initialize handshake) and supports Roots can dynamically update the Allowed directories.
Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
Confining Roots to the command-line directories
To keep a client's Roots inside the directories you gave on the command line, add --confine-roots:
mcp-server-filesystem --confine-roots /path/to/dir1 /path/to/dir2The client's Roots can then narrow the command-line directories but never replace or widen them. The server allows the overlap of the two:
A root inside a command-line directory is allowed as given, so a client can narrow access to one project.
A root that contains a command-line directory (for example
/) is narrowed to that directory.A root outside every command-line directory is ignored and logged. If every root is ignored, the server treats the update as one with no valid roots: before any root has been in force the command-line directories stay; once one has, access is revoked until the client exposes a root inside them again.
This suits an operator who decides what may be shared (the command line) while letting a client say what it wants to work on (its Roots), and it keeps a client from discarding the command-line directories by advertising its working directory. Without command-line directories the flag has no effect, and the server warns at startup. Without the flag, Roots replace the command-line directories as described above.
A Root reached through a symlink is allowed in both its advertised form and its resolved form, as a command-line directory is: a Root of file:///tmp/project on macOS allows /tmp/project and /private/tmp/project. Every requested path is still resolved and checked against the resolved directories, so a symlink inside a Root that points outside it is refused.
Important: If server starts without command-line arguments AND a 2025-era client doesn't support roots protocol, the server fails at initialization: it logs the reason to stderr, closes the connection and exits with status 1. A client that supports roots but provides none (or none that are valid) keeps the connection, with no allowed directories until it sends roots/list_changed with valid roots.
The 2026-07-28 protocol has no initialize handshake and no server-to-client roots/list request, so a 2026-07-28 client's roots are never asked for: the command-line directories are the whole allow-list. A server started with none answers every tool call on such a connection with an error saying so.
How It Works
The server's directory access control follows this flow:
Server Startup
Server starts with directories from command-line arguments (if provided)
If no arguments provided, server starts with empty allowed directories
Client Connection
The client's first message picks the protocol era of the connection
A 2026-07-28 client sends
server/discover(or any request carrying the per-request_metaenvelope): the server uses the command-line directories, and steps 3 and 4 do not applyA 2025-era client sends
initializewith its capabilities, and the server checks whether it supports roots (capabilities.roots)
Roots Protocol Handling (2025-era clients that support roots)
On initialization: Server requests roots from client via
roots/listClient responds with its configured roots
Server replaces ALL allowed directories with client's roots (with
--confine-roots, with their overlap with the command-line directories)Tool calls that arrive before the initial roots are loaded wait for them, so they are checked against the client's roots
On runtime updates: Client can send
notifications/roots/list_changedServer requests updated roots and replaces allowed directories again
Tool calls that arrive while an update is being fetched wait for it, so none runs against a root the client has just withdrawn
Once the client's roots are in force, an update with no valid roots revokes access: every path is refused ("Access denied - no allowed directories") until the client exposes a root again. Before any root has been in force, such an update keeps the command-line directories
Fallback Behavior (2025-era clients that don't support roots)
Server continues using command-line directories only
No dynamic updates possible
With no command-line directories either, the server logs an error, closes the connection and exits with status 1
Access Control
All filesystem operations are restricted to allowed directories
Use
list_allowed_directoriestool to see current directoriesThe server also logs the effective allowed directories to stderr, with where they came from (the command line, or the client's Roots and whether those replaced the command-line directories), at startup and whenever they change: after
initialize, after each Roots update, and when a withdrawal leaves none. For example:Effective allowed directories (from the client's Roots, which replaced the command-line directories): /Users/username/projectServer requires at least ONE allowed directory to operate
Note: The server will only allow operations within directories specified either via args or, for a 2025-era client, via Roots.
API
Resources
Files inside the allowed directories are also resources, so a client application can read one with resources/read and decide itself what to do with it (attach it to the model's context, show it to the user), rather than relaying it through a tool result.
Resource template
file://{+path}(namefile)Read any file by its absolute
file://URI, for examplefile:///home/user/project/README.md. A path with spaces or other reserved characters is percent-encoded, as in anyfile://URL.Text files are returned as
text, with a MIME type from the extension (text/plainfor an unknown extension whose bytes are UTF-8). Images, audio, PDFs and other binary files are returned as a base64blobwith their MIME type (application/octet-streamwhen unknown).Confined exactly as the tools are: a URI outside the allowed directories, or a symlink whose target is outside them, is refused with an
Access deniederror (-32602). A missing file is "resource not found" (-32602with the URI in the error data), and a directory is not a resource.resources/listreturns nothing: the server never enumerates the disk. Find files withlist_directory,directory_treeorsearch_files, then read them by URI.Results carry a cache hint of
ttlMs: 0,cacheScope: "private"(2026-07-28), since a file can change at any time.
Tools
read_text_file
Read complete contents of a file as text
Inputs:
path(string)head(non-negative integer, optional): First N lines;0returns no linestail(non-negative integer, optional): Last N lines;0returns no lines
Always treats the file as UTF-8 text regardless of extension
Cannot specify both
headandtailsimultaneously
read_media_file
Read a file and return it as a base64-encoded content block with its MIME type
Inputs:
path(string)
Streams the file and returns base64 data with the corresponding MIME type. Image and audio files are returned as
image/audiocontent; any other file type is returned as an embeddedresource(a valid MCP content block for arbitrary binary data)
read_multiple_files
Read multiple files simultaneously
Input:
paths(string[])Failed reads won't stop the entire operation
write_file
Create new file or overwrite existing (exercise caution with this)
Inputs:
path(string): File locationcontent(string): File content
An existing file is overwritten in place, so it keeps its inode, creation time, hard links and permissions (
edit_filewrites the same way). The overwrite is not crash-atomic: a crash mid-write can leave the file partly written. A read-only file is refused rather than replacedAllowed-directory checks are path-based: they check the name you pass, not every name the file has. A hard link is a real name of the same file, so when a file inside an allowed directory is also hard-linked from somewhere else (pnpm, for example, hard-links package files into
node_modulesfrom its store), overwriting or editing it changes the content at every name, inside the allowed directories or not.get_file_inforeports a file'shardLinkscount; more than 1 means the file has other names
append_file
Append text to the end of a file, creating the file if it does not exist
Inputs:
path(string): File locationcontent(string): Text to append
The text is appended exactly as given: no newline is added before or after it. To build a file line by line, end each
contentwith\nThe existing content is never changed. The file is appended to in place, so it keeps its inode, creation time, hard links and permissions, and a path that is not a regular file (a directory, say) is refused. The same hard-link caveat as
write_fileapplies
edit_file
Make selective edits using advanced pattern matching and formatting
Features:
Line-based and multi-line content matching
Whitespace normalization with indentation preservation
Multiple simultaneous edits with correct positioning
Indentation style detection and preservation: when only whitespace differs, each replacement line takes the indentation of the line it replaces
Preserves the file's line endings (LF or CRLF)
Git-style diff output with context
Preview changes with dry run mode
Inputs:
path(string): File to editedits(array): List of edit operationsoldText(string): Text to search for (can be substring)newText(string): Text to replace with
dryRun(boolean): Preview changes without applying (default: false)
Returns detailed diff and match information for dry runs, otherwise applies changes
Matching:
oldTextmust match the file's text exactly, except that line endings never matter and, when there is no exact match, a run of whole lines matches if each line is equal once leading and trailing whitespace is ignored. Whitespace inside a line must match; nothing fuzzier is triedIf any edit has no match, no edits are applied, and the error names the edit, quotes the closest lines of the file with line numbers, and shows the first line that differs (JSON-quoted, so tabs and trailing spaces are visible)
Best Practice: Always use dryRun first to preview changes before applying them
create_directory
Create new directory or ensure it exists
Input:
path(string)Creates parent directories if needed
Succeeds silently if directory exists
list_directory
List directory contents with [FILE] or [DIR] prefixes
Input:
path(string)
list_directory_with_sizes
List directory contents with [FILE] or [DIR] prefixes, including file sizes
Inputs:
path(string): Directory path to listsortBy(string, optional): Sort entries by "name" or "size" (default: "name")
Returns detailed listing with file sizes and summary statistics
Shows total files, directories, and combined size
An entry that cannot be stat'd (unreadable, a dangling symlink, or a symlink leaving the allowed directories) is listed with size
unknownand left out of the combined size
move_file
Move or rename files and directories
Inputs:
source(string)destination(string)
Fails if destination exists
Across filesystems (the source and destination on different mounts or disks), a regular file is moved by copying it to a newly created destination, with its permissions and modification time, and then removing the source. If the copy fails, the partial destination is removed and the source is left in place. A directory cannot be moved across filesystems and fails with an error; move its files one at a time instead
copy_file
Copy a file to a new location, without its content passing through the conversation
Inputs:
source(string): The file to copydestination(string): Where to create the copy
Fails if destination exists: it never overwrites
Copies one regular file, with its permissions and modification time, into a newly created destination. A directory, or anything else that is not a regular file, is refused; create the directory and copy its files one at a time instead. If the copy fails, the partial destination is removed. The source is never changed
search_files
Recursively find files/directories by name (a glob over their paths), not by content: it never reads or searches inside files
Inputs:
path(string): Starting directorypattern(string): Glob matched, case-sensitively, against each entry's path relative topath:*.extmatches entries directly underpath,**/*.extor**/namematches at any depthexcludePatterns(string[]): Exclude any patterns. An excluded entry is skipped before it is resolved or read, so excluding a slow folder keeps the search out of it entirely.
Glob-style pattern matching
Returns full paths to matches
Bounded: see Slow and very large trees
A subdirectory that cannot be read (no permission, say) is skipped, and the result says so: after the matches, a note that the search is incomplete lists each unreadable directory with its error code. Paths outside the allowed directories are still skipped silently.
directory_tree
Get recursive JSON tree structure of directory contents
Inputs:
path(string): Starting directoryexcludePatterns(string[]): Exclude any patterns. Glob formats are supported.depth(positive integer, optional): How many levels to descend.1lists only the entries directly inpath,2adds their children, and so on. Omitted, the whole tree is returned
Returns:
JSON array where each entry contains:
name(string): File/directory nametype('file'|'directory'): Entry typechildren(array): Present only for directoriesEmpty array for empty directories
Omitted for files
Omitted for directories at the last level when
depthis set: they are not read, so whether they hold anything is not reported
A
depthlimit also keeps the walk out of deeper levels entirely, so entries below it do not count toward the 100,000-entry boundOutput is formatted with 2-space indentation for readability
Bounded: see Slow and very large trees
get_file_info
Get detailed file/directory metadata
Input:
path(string)Returns:
Size
Creation time
Modified time
Access time
Type (file/directory)
Permissions
Hard-link count (
hardLinks): the number of names the file has. More than 1 means a write through this name changes the file at its other names too (seewrite_file)
list_allowed_directories
List all directories the server is allowed to access
No input required
Returns:
Directories that this server can read/write from. A directory reached through a symlink is listed twice, in the form it was given and in its resolved form
Slow and very large trees
A folder backed by a cloud-storage provider (macOS ~/Library/CloudStorage,
iCloud Drive) or a slow network mount can make a single filesystem call block
for minutes while the provider fetches metadata. Two fixed limits keep one
request from stalling the server:
Resolving a path (in any tool), and each directory read in
search_filesanddirectory_tree, waits at most 15 seconds. A call that takes longer ends the request with an error naming the path (Filesystem call timed out after 15000 ms: ...). A path whose real location cannot be read in time is refused, never admitted.search_filesanddirectory_treevisit at most 100,000 entries. A walk that reaches the cap ends with an error (... stopped after visiting 100000 entries ...) rather than a partial result. Excluded entries do not count.
Either error means: narrow path, or name the slow or large folder in
excludePatterns. A timed-out call cannot be cancelled and finishes in the
background, so a provider that stalls repeatedly can still slow the server's
other file operations until it answers.
Tool annotations (MCP hints)
This server sets MCP ToolAnnotations on each tool so clients can:
Distinguish read‑only tools from write‑capable tools.
Understand which write operations are idempotent (safe to retry with the same arguments).
Highlight operations that may be destructive (overwriting or heavily mutating data).
Signal that a tool does not reach an open or external world (every filesystem tool sets
openWorldHint: false).
The mapping for filesystem tools is:
Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
|
|
|
| Deprecated alias of |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Pure read |
|
|
|
| Re‑creating the same dir is a no‑op |
|
|
|
| Overwrites existing files |
|
|
|
| Adds to a file; repeating it appends again |
|
|
|
| Re‑applying edits can fail or double‑apply |
|
|
|
| Deletes source file |
|
|
|
| Never overwrites; a repeat fails, changing nothing |
Note: the MCP spec gives
idempotentHintanddestructiveHintmeaning only whenreadOnlyHintisfalse, but every tool sets them anyway, so a client that reads them without checkingreadOnlyHintfirst still sees the truth: a read can be repeated safely and changes nothing. Every tool also setsopenWorldHint: false— this server only accesses the local filesystem within its allowed directories, never an open or external world.
Requirements
Node.js 24 or later, when the server runs through npx or from source.
Usage with Claude Desktop
Add this to your claude_desktop_config.json:
Note: you can provide sandboxed directories to the server by mounting them to /projects. Adding the ro flag will make the directory readonly by the server.
Docker
Note: all directories must be mounted to /projects by default.
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
"--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
"mcp/filesystem",
"/projects"
]
}
}
}NPX
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}On Windows, use cmd /c to launch npx:
{
"mcpServers": {
"filesystem": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}Usage with VS Code
For quick installation, click the installation buttons below...
For manual installation, you can configure the MCP server using one of these methods:
Method 1: User Configuration (Recommended)
Add the configuration to your user-level MCP configuration file. Open the Command Palette (Ctrl + Shift + P) and run MCP: Open User Configuration. This will open your user mcp.json file where you can add the server configuration.
Method 2: Workspace Configuration
Alternatively, you can add the configuration to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.
For more details about MCP configuration in VS Code, see the official VS Code MCP documentation.
You can provide sandboxed directories to the server by mounting them to /projects. Adding the ro flag will make the directory readonly by the server.
Docker
Note: all directories must be mounted to /projects by default.
{
"servers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
"mcp/filesystem",
"/projects"
]
}
}
}NPX
{
"servers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}On Windows, use:
{
"servers": {
"filesystem": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}Build
Docker build:
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Available Tools
14 toolscreate_directoryCreate DirectoryAIdempotent
Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation. If the directory already exists, this operation will succeed silently. Perfect for setting up directory structures for projects or ensuring required paths exist. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotent and non-destructive; description adds that existing directories succeed silently and that operation is scoped to allowed directories, providing full behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each adding distinct value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers behavior, constraints, and use cases; missing return value info but not critical for simple creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no description for 'path' and description doesn't specify format or examples; since coverage is low, this is a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'create' and resource 'directory'; distinguishes from sibling tools by mentioning nested creation and idempotent behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states ideal use cases (setting up structures, ensuring paths) and constraint (only within allowed directories), giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
directory_treeDirectory TreeBRead-only
Get a recursive tree view of files and directories as a JSON structure. Each entry includes 'name', 'type' (file/directory), and 'children' for directories. Files have no children array, while directories always have a children array (which may be empty). The output is formatted with 2-space indentation for readability. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| excludePatterns | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
B3.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond the readOnlyHint annotation by specifying the recursive nature and JSON structure of the output. It also mentions the constraint of working only within allowed directories, which is useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and well-structured, with no redundant information. Every sentence adds meaningful detail about the tool's behavior and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description mentions 'within allowed directories', it fails to explain the required 'path' parameter or the optional 'excludePatterns' parameter. Given the schema has no descriptions and the output schema is not visible, the description is insufficient for full usage clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, and the tool description does not explain any of the two parameters (path and excludePatterns). Without compensation, the agent cannot fully understand what values are valid or how they affect the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource (recursive tree view). It distinguishes from sibling tools like list_directory by emphasizing 'recursive', making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. It does not mention that list_directory or search_files are better suited for flat or filtered needs, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_fileEdit FileADestructive
Make line-based edits to a text file. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| edits | Yes | ||
| dryRun | No | Preview changes using git-style diff format |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by revealing that the tool returns a git-style diff and is restricted to allowed directories. It confirms the destructive nature (edits) consistent with the destructiveHint annotation but adds useful behavioral context about the output and scope. It does not fully disclose edge-case behaviors (e.g., multiple matches, error handling), but the additional information is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two short sentences. It packs essential information—purpose, mechanism, output, and constraint—without any redundant or fluff content. Every sentence adds value, and the structure is straightforward and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and a nested edits array, the description provides sufficient context to understand the main functionality: line-based edits with exact matching and a diff result. It also covers the directory restriction. It omits details like error handling when oldText is not found, the exact format of the diff, and the behavior of dryRun, but these are not critical for a basic understanding. The description is complete enough for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the core semantics of the edits array by stating that each edit replaces exact line sequences (oldText) with new content (newText). It also indirectly describes the path via the allowed-directories constraint and mentions the diff output, which relates to the dryRun parameter (though not explicitly named). However, it does not clarify the dryRun flag's purpose or behavior, and path semantics are only implied, so coverage is partial given three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: making line-based edits to a text file. It specifies the action (edits), the resource (text file), and the specific mechanism (replacing exact line sequences). It also distinguishes itself from sibling tools by mentioning the git-style diff output and the restriction to allowed directories, making its scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (for precise line-based changes) by explaining that it replaces exact line sequences and returns a diff, but it does not explicitly compare it to alternatives like write_file or search_files. The constraint 'Only works within allowed directories' is more of a limitation than a usage guideline, so the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_file_infoGet File InfoARead-only
Retrieve detailed metadata about a file or directory. Returns comprehensive information including size, creation time, last modified time, permissions, and type. This tool is perfect for understanding file characteristics without reading the actual content. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately reflects the readOnlyHint annotation by framing the operation as retrieval with no side effects. It adds the meaningful constraint that it only works within allowed directories, though it does not describe error behavior for invalid paths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using two sentences to convey purpose, output content, and constraints without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple metadata-retrieval tool, the description covers the key aspects: what it returns, that it does not read content, and the access boundary. It lacks explicit error/edge-case details, but these are not critical given the read-only, closed-world annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the 'path' parameter at all, and the input schema provides only its type and required status. Since schema coverage is 0%, the description fails to compensate by explaining what the path should refer to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Retrieve') and resource ('detailed metadata about a file or directory'), and explicitly distinguishes itself from content-reading tools by noting it returns metadata without reading content. This clearly differentiates it from siblings like read_file and list_directory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use it ('understanding file characteristics without reading actual content') and states the allowed-directory constraint. It does not explicitly enumerate alternative tools, but the intended use case is evident from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_allowed_directoriesList Allowed DirectoriesARead-only
Returns the list of directories that this server is allowed to access. Subdirectories within these allowed directories are also accessible. Use this to understand which directories and their nested paths are available before trying to access files.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns allowed directories and that subdirectories are also accessible, adding useful behavioral context. Since readOnlyHint=true is already annotated, the description does not need to restate read-only behavior but still provides additional scope information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and then provides usage context. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters) and the presence of an output schema, the description fully covers the purpose and usage. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is 100% by definition. Baseline for 0 params is 4; the description appropriately does not need to add parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the list of allowed directories, distinguishing it from sibling tools like list_directory or read_file. It is specific about the resource (allowed directories) and the action (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use it: before trying to access files, to understand which directories and nested paths are available. This provides clear guidance and implicitly contrasts with guessing directory paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_directoryList DirectoryBRead-only
Get a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is essential for understanding directory structure and finding specific files within a directory. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
B3.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation indicates no modifications, and the description does not contradict this. It adds the constraint of working only within allowed directories, which is useful context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with the purpose stated first and the prefix detail second. The third sentence contains some redundant fluff about being essential, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions the [FILE] and [DIR] prefixes but does not specify whether the listing is recursive or how the paths are formatted. It also lacks information about error handling or the exact output structure, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'path' is described merely as 'a specified path' in the description, with no details on format (relative/absolute) or constraints. Since the schema has no description, the tool description fails to adequately define the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists files and directories in a given path and highlights the [FILE] and [DIR] prefixes. It distinguishes from sibling tools by focusing on a simple listing, though it doesn't explicitly contrast with directory_tree or list_directory_with_sizes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exploring directory structure and finding files, but it does not explicitly specify when to prefer this over search_files or directory_tree. It provides a constraint that it only works within allowed directories, but lacks direct comparisons to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_directory_with_sizesList Directory with SizesBRead-only
Get a detailed listing of all files and directories in a specified path, including sizes. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is useful for understanding directory structure and finding specific files within a directory. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| sortBy | No | Sort entries by name or size | name |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
B3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the readOnlyHint and openWorldHint annotations by stating that the tool only works within allowed directories and that results use [FILE] and [DIR] prefixes. This does not contradict the annotations and gives the agent additional expectations about output and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise at three sentences, but the sentence 'This tool is useful for understanding directory structure and finding specific files within a directory' adds little value and could be removed or replaced with more specific guidance. The core information is present without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return-value details are not required, but the description omits important operational details such as whether listing is recursive, how hidden files are handled, and what path values are valid. It also lacks differentiation from list_directory, leaving the agent without enough context to confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: sortBy has a description and enum, but path has no description. The tool description does not compensate by explaining path format, whether it must be absolute/relative, or how it relates to allowed directories. This leaves a key parameter underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get a detailed listing of files and directories in a specified path, including sizes. It also mentions the distinguishing [FILE] and [DIR] prefixes, which sets it apart from the sibling list_directory, though it does not explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus the sibling list_directory or other tools. The phrase 'useful for understanding directory structure and finding specific files' is generic and applies equally to list_directory, so it does not help an agent choose between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
move_fileMove FileADestructive
Move or rename files and directories. Can move files between directories and rename them in a single operation. If the destination exists, the operation will fail. Works across different directories and can be used for simple renaming within the same directory. Both source and destination must be within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| destination | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals a key behavioral trait: the operation fails if the destination already exists, which prevents accidental overwrites. This complements the annotations (destructiveHint=true, readOnlyHint=false) by specifying a concrete safety behavior. However, it does not explicitly state that the source is removed after a successful move, though this is implied by the semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and to the point, but it contains slight redundancy (e.g., 'Can move files between directories and rename them in a single operation' appears twice with similar phrasing). Overall, it is efficient and not verbose, fitting within a couple of sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary behavior and a critical failure condition, which is sufficient for a basic move operation. It does not describe the output (likely void or a confirmation), but this is not essential for the agent to invoke the tool correctly. The context provided by the description and annotations is adequate for the given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names (source, destination) with no descriptions. The tool's name and description imply they are file paths, but the description does not elaborate on expected formats, relative vs. absolute paths, or whether directories are allowed. The basic intent is clear, but the lack of explicit detail leaves some ambiguity for edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: moving and renaming files/directories. It explicitly differentiates between moving across directories and renaming, and the verb 'Move' is specific enough to distinguish it from other file operation tools like read, write, or edit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., copy, edit). The mention of 'move between directories or rename' gives some context, but no direct comparison or conditional advice is given, leaving the decision to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_fileRead File (Deprecated)ARead-only
Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.
| Name | Required | Description | Default |
|---|---|---|---|
| head | No | If provided, returns only the first N lines of the file | |
| path | Yes | ||
| tail | No | If provided, returns only the last N lines of the file |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful non-annotation context: the tool is deprecated and returns file contents as text. This goes beyond what the structured annotations alone communicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences contain the core operation and the deprecation directive. The critical information is front-loaded, and there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated read-only tool with an output schema present, this description is complete: it states the operation, the return type, the deprecation status, and the replacement tool. Remaining behavioral details such as partial reads are already present in the schema, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%; head and tail are documented in the schema, and path is self-evident from its name and type. The description adds no further parameter-level meaning, but the existing schema coverage is adequate enough that the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Read the complete contents of a file as text.' The DEPRECATED label and pointer to read_text_file make the differentiation from sibling tools explicit. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'DEPRECATED: Use read_text_file instead.' This is direct when-not-to-use guidance and names the exact alternative. An agent can immediately route to the correct tool without needing sibling-tool inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_media_fileRead Media FileARead-only
Read a file and return it as a base64-encoded content block with its MIME type. Image and audio files are returned as image/audio content; any other file type is returned as an embedded resource. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the constraint about allowed directories, which is not present in the annotations. It is consistent with the readOnlyHint and does not introduce any side effects, but does not describe error behavior or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and directly to the point. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough information about the output format and behavior for different file types for an agent to use the tool effectively. It does not detail the output schema or error handling, but these are not critical for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The path parameter is not described in the schema or the tool description beyond the context of reading a file. This is adequate for a simple string path, but lacks any detail about expected format or validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a file and returns a base64-encoded content block with its MIME type. It also distinguishes behavior for image/audio versus other file types, making its purpose distinct from sibling tools like read_file and read_text_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the restriction that it only works within allowed directories, but does not explicitly state when to prefer this tool over alternatives such as read_file or read_text_file. This leaves some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_multiple_filesRead Multiple FilesARead-only
Read the contents of multiple files simultaneously. This is more efficient than reading files one by one when you need to analyze or compare multiple files. Each file's content is returned with its path as a reference. Failed reads for individual files won't stop the entire operation. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | Array of file paths to read. Each path must be a string pointing to a valid file within allowed directories. |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds valuable behavioral detail: operation can partially succeed, individual file failures don't stop the batch, results include the path as a reference, and access is limited to allowed directories. These are the kind of behaviors an agent needs to know and the annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, each adding relevant information: purpose, when to use it, return shape, failure behavior, and scope. There is no filler, and the most important content comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, complete schema coverage, an output schema, and helpful annotations, the description covers everything needed to call it correctly: partial-failure semantics, per-file path referencing, and directory restrictions. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single 'paths' parameter is 100%, so the baseline is 3. The description adds some context about multi-file behavior but does not provide any per-parameter semantics beyond what the schema already states about paths pointing to valid files within allowed directories.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read the contents of multiple files simultaneously.' It further distinguishes itself from single-file reads by noting its efficiency when analyzing or comparing multiple files, so an agent can clearly tell it apart from read_file and similar siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool: 'more efficient than reading files one by one when you need to analyze or compare multiple files.' It also notes the allowed-directory constraint. However, it does not explicitly address read_text_file or read_media_file, so the guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_text_fileRead Text FileARead-only
Read the complete contents of a file from the file system as text. Handles various text encodings and provides detailed error messages if the file cannot be read. Use this tool when you need to examine the contents of a single file. Use the 'head' parameter to read only the first N lines of a file, or the 'tail' parameter to read only the last N lines of a file. Operates on the file as text regardless of extension. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| head | No | If provided, returns only the first N lines of the file | |
| path | Yes | ||
| tail | No | If provided, returns only the last N lines of the file |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint and openWorldHint. The description adds context about error messages and the restriction to allowed directories, which goes beyond the annotations and clarifies expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense without being verbose. It front-loads the core purpose and then explains the head/tail options and constraints. All sentences contribute meaningful details, though a slight redundancy exists in repeating the purpose at the start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers when to use the tool, what it does, and its constraints (allowed directories, encoding handling). Since an output schema is present (as indicated), the absence of return-format details is acceptable. Overall, an agent has sufficient context to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers head and tail descriptions (67% coverage). The description explicitly explains the head and tail parameters and their partial-read behavior. The path parameter is not described in the schema, but its role is implied by the tool's purpose and the 'single file' wording, so the description compensates adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (read), the resource (file), and the scope (complete contents as text). It distinguishes itself from siblings like read_media_file and read_multiple_files by explicitly mentioning 'as text' and 'single file', so an agent can select it appropriately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('when you need to examine the contents of a single file') and explains head/tail for partial reads. It does not explicitly state when not to use it, but the sibling names and the 'single file' and 'as text' qualifiers provide implicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_filesSearch FilesARead-only
Recursively search for files and directories matching a pattern. The patterns should be glob-style patterns that match paths relative to the working directory. Use pattern like '.ext' to match files in current directory, and '**/.ext' to match files in all subdirectories. Returns full paths to all matching items. Great for finding files when you don't know their exact location. Only searches within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| pattern | Yes | ||
| excludePatterns | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: recursive search, returning full paths, glob-style pattern matching, and restricting to allowed directories. It does not contradict the readOnlyHint annotation. However, it omits details about edge cases (e.g., no matches) which might be expected but are covered by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-organized. It provides essential information in a few sentences, includes illustrative examples, and avoids unnecessary jargon or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality, usage context, and constraints (allowed directories). It does not address error conditions or performance implications, but the output schema likely defines return structure, and the sibling tools list offers alternatives. Overall it is reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'pattern' parameter well with examples and clarifies path relativity, but it does not explicitly define the 'path' parameter or mention 'excludePatterns' at all. Since schema coverage is 0%, the description only partially compensates for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Recursively search for files and directories matching a pattern.' It also provides concrete examples of pattern usage, making the intended action and resource unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it is 'Great for finding files when you don't know their exact location,' which gives a clear use case. It also implies a contrast with tools like read_file or list_directory, though it does not explicitly name alternatives or provide a decision tree.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_fileWrite FileADestructiveIdempotent
Create a new file or completely overwrite an existing file with new content. Use with caution as it will overwrite existing files without warning. Handles text content with proper encoding. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds behavioral details: overwrites without warning, handles text encoding, and only works within allowed directories. This provides transparency about side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences covering purpose, caution, and constraints. It is well-structured and contains no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: purpose, caution, text handling, and directory restrictions. It does not mention output/return values, but an output schema exists, so that is not required. It could mention idempotency or error conditions, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only types for path and content with no descriptions, and the description does not elaborate on these parameters. While straightforward, the description adds no meaning beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create/overwrite), the resource (file), and the scope (new content vs. existing file), distinguishing it from sibling tools like edit_file or create_directory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly warns about overwriting without confirmation and notes the constraint of allowed directories, giving clear guidance on when to use this tool and what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v2026.7.10- Changed
read_media_file5 fields changed- removed
Output schema / properties / content / items / additionalPropertiesRemoved value: -false - added
Output schema / properties / content / items / anyOfAdded value: +[ + { + "additionalProperties": false, + "properties": { + "data": { + "type": "string" + }, + "mimeType": { + "type": "string" + }, + "type": { + "enum": [ + "image", + "audio" + ], + "type": "string" + } + }, + "required": [ + "type", + "data", + "mimeType" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "resource": { + "additionalProperties": false, + "properties": { + "blob": { + "type": "string" + }, + "mimeType": { + "type": "string" + }, + "uri": { + "type": "string" + } + }, + "required": [ + "uri", + "blob" + ], + "type": "object" + }, + "type": { + "const": "resource", + "type": "string" + } + }, + "required": [ + "type", + "resource" + ], + "type": "object" + } +] - removed
Output schema / properties / content / items / propertiesRemoved value: -{ - "data": { - "type": "string" - }, - "mimeType": { - "type": "string" - }, - "type": { - "enum": [ - "image", - "audio", - "blob" - ], - "type": "string" - } -} - removed
Output schema / properties / content / items / requiredRemoved value: -[ - "type", - "data", - "mimeType" -] - removed
Output schema / properties / content / items / typeRemoved value: -"object"
14 tool updates
v1.0.0- Changed
create_directory2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
directory_tree3 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - added
Input schema / properties / excludePatternsAdded value: +{ + "default": [], + "items": { + "type": "string" + }, + "type": "array" +} - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
edit_file3 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - removed
Input schema / properties / edits / items / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
get_file_info2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
list_allowed_directories3 fields changed- added
Input schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#" - removed
Input schema / requiredRemoved value: -[] - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
list_directory2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
list_directory_with_sizes2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
move_file2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
read_file2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
read_media_file2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "items": { + "additionalProperties": false, + "properties": { + "data": { + "type": "string" + }, + "mimeType": { + "type": "string" + }, + "type": { + "enum": [ + "image", + "audio", + "blob" + ], + "type": "string" + } + }, + "required": [ + "type", + "data", + "mimeType" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
read_multiple_files4 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - added
Input schema / properties / paths / descriptionAdded value: +"Array of file paths to read. Each path must be a string pointing to a valid file within allowed directories." - added
Input schema / properties / paths / minItemsAdded value: +1 - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
read_text_file2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
search_files2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
- Changed
write_file2 fields changed- removed
Input schema / additionalPropertiesRemoved value: -false - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "properties": { + "content": { + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" +}
14 tool updates
- First observed
create_directory - First observed
directory_tree - First observed
edit_file - First observed
get_file_info - First observed
list_allowed_directories - First observed
list_directory - First observed
list_directory_with_sizes - First observed
move_file - First observed
read_file - First observed
read_media_file - First observed
read_multiple_files - First observed
read_text_file - First observed
search_files - First observed
write_file
TDQS
A3.6/5.0
Scored across 14 tools
Disambiguation3/5
Some tools overlap in purpose: list_directory and list_directory_with_sizes are nearly identical except for size output; read_file is deprecated in favor of read_text_file, causing confusion. Other tools are distinct but descriptions could be clearer to avoid misselection.
Naming Consistency4/5
Most tools follow a verb_noun pattern (e.g., create_directory, edit_file, read_text_file). directory_tree is a minor deviation as noun_noun. Overall consistent with one exception.
Tool Count5/5
14 tools is well-scoped for a filesystem server. Each tool serves a clear purpose, covering reading, writing, editing, listing, searching, and metadata retrieval without unnecessary bloat.
Completeness2/5
Missing critical operations: there is no tool to delete files or directories, and no copy functionality. This creates significant gaps that will hinder agents from performing basic file management tasks.
Maintenance
ActivityActive
ResponsivenessSyncing
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
MCP server for understanding Javascript internals from ECMAScript specification.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseAqualityDmaintenanceNode.js server implementing Model Context Protocol (MCP) for filesystem operations with comprehensive permission controls, allowing secure file and directory manipulation with granular access restrictions.211,299,946 npm3MIT
- -licenseNot gradedqualityNot gradedmaintenanceNode.js server implementing Model Context Protocol (MCP) for filesystem operations, allowing AI systems to read, write, edit files and manage directories within specified allowed paths.1,299,946 npm-
- -licenseAqualityNot gradedmaintenanceA comprehensive Node.js server implementing Model Context Protocol (MCP) that enables filesystem operations, process management, and terminal session handling with an enterprise-grade security approach.141,299,946 npm-