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., "@bounded-filesystem-mcp read the first 10,000 characters of error.log"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A fork of the Filesystem MCP server where every tool result has a size limit. Large files are read in windows instead of being returned in one piece.
Vendored from modelcontextprotocol/servers, tag 2026.1.14 (commit 3e805376da81c063c2798410906b5fd134334a43), directory src/filesystem. This repository's history starts from that snapshot. Upstream is MIT licensed, copyright Anthropic, PBC; see LICENSE.
lib.ts, path-validation.ts, path-utils.ts, roots-utils.ts and their tests are unchanged from upstream (only __tests__/structured-content.test.ts is adapted, see below), so they can be synced by copying the files. The changes live in index.ts (tool registration) and the new bounded.ts.
Related MCP server: LocalFS MCP Server
Result cap. A text result longer than the cap (default 50,000 characters) keeps its first 50,000 characters, never splitting a surrogate pair. A notice is added on its own line:
[Result truncated: showing characters 1-50,000 of 1,234,567. Call again with offset=50000 to continue.]Tools that cannot page say how to narrow the request instead, for example:
[Result truncated: showing characters 1-50,000 of 812,345. To see the rest, narrow the request: pass a deeper path, or add excludePatterns.]Paged reads. read_text_file and read_file take offset and limit, both counted in characters. Follow the offset in each notice to walk the whole file; the last window has no notice. The file is streamed and only the window is kept in memory. head and tail work as before, but cannot be combined with offset or limit.
Capped listings. read_multiple_files, directory_tree, search_files, list_directory, list_directory_with_sizes and edit_file's diff all use the cap. read_multiple_files caps the combined text, and its notice says how many of the requested files were included in full. It reads the files one after another rather than in parallel.
Media size limit. read_media_file refuses files over 5 MB (5,242,880 bytes) with an error naming the file size and the limit. It checks the size before reading any bytes.
Plain text results. Tools have no outputSchema and return no structuredContent, only content blocks. Hosts that prefer structuredContent would otherwise see the text JSON-escaped and the payload doubled, so a capped result would not be the size the cap promises.
The server reports itself as bounded-filesystem in initialize. Tool names and existing parameters are unchanged.
"Characters" here means UTF-16 code units, the same as a JavaScript string's length.
Flag | Environment variable | Default | Meaning |
|
|
| Largest text result, in characters, before the truncation notice |
|
|
| Largest file |
A flag wins over its environment variable. Both flags also accept the --flag=<n> form. Everything else on the command line is an allowed directory:
bunx bounded-filesystem-mcp@0.1.0 --max-result-chars 40000 /path/to/dir1 /path/to/dir2Read/write files
Create/list/delete directories
Move files/directories
Search files
Get file metadata
Dynamic directory access control via Roots
The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via Roots.
Specify Allowed directories when starting the server:
bounded-filesystem-mcp /path/to/dir1 /path/to/dir2MCP clients that support Roots can dynamically update the Allowed directories.
Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
Important: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.
This is the recommended method, as this enables runtime directory updates via roots/list_changed notifications without server restart, providing a more flexible and modern integration experience.
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 & Initialization
Client connects and sends initialize request with capabilities
Server checks if client supports roots protocol (capabilities.roots)
Roots Protocol Handling (if client supports roots)
On initialization: Server requests roots from client via roots/list
Client responds with its configured roots
Server replaces ALL allowed directories with client's roots
On runtime updates: Client can send notifications/roots/list_changed
Server requests updated roots and replaces allowed directories again
Fallback Behavior (if client doesn't support roots)
Server continues using command-line directories only
No dynamic updates possible
Access Control
All filesystem operations are restricted to allowed directories
Use list_allowed_directories tool to see current directories
Server requires at least ONE allowed directory to operate
Note: The server will only allow operations within directories specified either via args or via Roots.
read_text_file
Read complete contents of a file as text, or a window of it
Inputs:
path (string)
head (number, optional): First N lines
tail (number, optional): Last N lines
offset (integer, optional): Character position to start from (default 0)
limit (integer, optional): Number of characters to return, clamped to the result cap
Always treats the file as UTF-8 text regardless of extension
Cannot specify both head and tail simultaneously, or combine either with offset/limit
Results over the cap end with a notice giving the offset to continue from
read_file is the deprecated alias and behaves the same
read_media_file
Read an image or audio file
Inputs:
path (string)
Streams the file and returns base64 data with the corresponding MIME type
Files over --max-media-bytes (default 5 MB) return an error without being read
read_multiple_files
Read multiple files simultaneously
Input: paths (string[])
Failed reads won't stop the entire operation
The combined text is capped; the notice says how many files were included in full
write_file
Create new file or overwrite existing (exercise caution with this)
Inputs:
path (string): File location
content (string): File content
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
Git-style diff output with context
Preview changes with dry run mode
Inputs:
path (string): File to edit
edits (array): List of edit operations
oldText (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
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 list
sortBy (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
move_file
Move or rename files and directories
Inputs:
source (string)
destination (string)
Fails if destination exists
search_files
Recursively search for files/directories that match or do not match patterns
Inputs:
path (string): Starting directory
pattern (string): Search pattern
excludePatterns (string[]): Exclude any patterns.
Glob-style pattern matching
Returns full paths to matches
directory_tree
Get recursive JSON tree structure of directory contents
Inputs:
path (string): Starting directory
excludePatterns (string[]): Exclude any patterns. Glob formats are supported.
Returns:
JSON array where each entry contains:
name (string): File/directory name
type ('file'|'directory'): Entry type
children (array): Present only for directories
Empty array for empty directories
Omitted for files
Output is formatted with 2-space indentation for readability
get_file_info
Get detailed file/directory metadata
Input: path (string)
Returns:
Size
Creation time
Modified time
Access time
Type (file/directory)
Permissions
list_allowed_directories
List all directories the server is allowed to access
No input required
Returns:
Directories that this server can read/write from
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).
The mapping for filesystem tools is:
Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
|
| – | – | 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 |
|
|
|
| Re‑applying edits can fail or double‑apply |
|
|
|
| Move/rename only; repeat usually errors |
Note:
idempotentHintanddestructiveHintare meaningful only whenreadOnlyHintisfalse, as defined by the MCP spec.
MCP clients start the server over stdio:
{
"mcpServers": {
"filesystem": {
"command": "bunx",
"args": [
"bounded-filesystem-mcp@0.1.0",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}npx -y bounded-filesystem-mcp@0.1.0 <dirs...> works the same way.
npm install
npm run build
npm testMIT. The upstream code is copyright Anthropic, PBC; the changes in this fork are copyright Shivam Singh. See LICENSE.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation idempotentHint=true is echoed by 'will succeed silently', but the description adds genuinely new behavioral facts: nested directories are created in one call, and the operation is confined to allowed directories. The sandbox constraint is real context beyond the annotations, though error behavior outside allowed dirs is not spelled out.
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 critical behavior (create-or-ensure, nested, silent success) is front-loaded in the first three sentences. The 'Perfect for...' sentence leans promotional but does carry a use case, so it mostly earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and annotations covering the safety profile, the description covers idempotency, nesting, and the allowed-directory constraint. Only the path format and failure behavior are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single 'path' parameter is undocumented. The description implies the path must live within allowed directories but never specifies format (absolute vs relative), so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Create a new directory') and adds a distinguishing behavior ('ensure a directory exists'), which separates it from a plain create. It does not, however, differentiate itself from siblings like list_directory or directory_tree, so a 4 rather than a 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?
It offers use-case hints ('setting up directory structures for projects or ensuring required paths exist'), which imply when the tool is appropriate. It gives no explicit exclusions or named alternatives, so usage remains inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
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 |
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 |
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 | |||
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 |
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declaring the safety profile, the description adds value beyond annotations by disclosing the output format ([FILE]/[DIR] prefixes to distinguish entries) and an access constraint ('Only works within allowed directories'). It does not discuss pagination or entry-count limits, but it earns credit for the output-shape and permission-scope 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?
Three compact sentences, front-loaded with the core action and output format, followed by use case and the access constraint. The 'This tool is useful for...' sentence is slightly filler-ish, but nothing is redundant or bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on responsibility for return shape and does so via the [FILE]/[DIR] prefix convention, plus it flags the allowed-directory restriction. An agent has enough to call it correctly; only the sortBy behavior and result limits are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: sortBy carries its own enum description, but path is undocumented in the schema. The description mentions 'a specified path' without format or constraint details and never mentions sortBy at all, so it does not compensate for the gap. It neither adds nor detracts much beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get a detailed listing of all files and directories in a specified path') and adds the distinguishing scope 'including sizes', which implicitly separates it from the sibling list_directory that lacks size information. It is clear and specific, though it never names the sibling it differs from, so an agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers context ('useful for understanding directory structure and finding specific files within a directory') but gives no when-not guidance and never names alternatives such as list_directory or directory_tree, which are the obvious competing tools in this family. Usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavior beyond that: the operation fails if the destination already exists and both paths must remain within allowed directories. It does not discuss atomicity, rollback, or detailed error cases, but it covers the most important invocation constraints.
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 front-loaded with the core action and appropriately sized for a simple file operation. There is some redundancy between saying it can move/rename in one operation and later saying it works across directories for simple renaming, but the structure remains clear and efficient.
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 two-parameter mutation tool with annotations and no output schema, the description is largely complete: it covers purpose, failure behavior, directory-scope constraints, and common use cases. Minor gaps remain around source existence and error handling, but nothing critical for basic invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It references both parameters by name and clarifies that they must be within allowed directories, and the destination must not already exist. However, it does not define path formats, source existence requirements, or individual parameter roles in depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Move or rename files and directories.' It also distinguishes moving between directories from simple renaming within the same directory, which clarifies the tool's scope without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives usage context such as 'works across different directories' and 'can be used for simple renaming within the same directory,' plus the constraint that the destination must not exist. However, it does not explicitly name alternatives or say when to use this instead of siblings like write_file or edit_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead. Use the 'offset' and 'limit' parameters to read a window of characters. Results longer than 50,000 characters are cut short, ending with a notice that says how to get the rest.
| 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 | |
| limit | No | Maximum number of characters to return, clamped to the result cap | |
| offset | No | Character position to start reading from (default 0). Use the offset given in a truncation notice to continue |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, so the description earns credit for adding the truncation contract: results over 50,000 characters are cut short and end with a notice explaining how to fetch the rest. That continuation behavior is real operational context not present in annotations. It omits error behavior (missing file, permission, binary content), keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all load-bearing: purpose, deprecation routing, then windowing and truncation behavior. The deprecation warning is prominently placed early so an agent cannot miss it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so by describing text output plus the truncation notice. For a read-only file tool with 80% schema coverage, the main remaining gaps are encoding assumptions and failure modes, which are minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so the baseline is 3, but the description adds the non-obvious workflow of feeding the offset from a truncation notice back into a follow-up call, which the schema alone does not convey. It says nothing about head/tail, which are documented only in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read the complete contents of a file as text') and explicitly names the sibling that replaces it ('Use read_text_file instead'). An agent can distinguish it from read_text_file, read_media_file, and read_multiple_files without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The deprecation notice routes the agent to read_text_file, which is a clear alternative, and the description tells the agent to use offset/limit for windowed reads. It does not explain when this deprecated tool should still be preferred over the replacement, nor how head/tail relate to offset/limit, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an image or audio file. Returns the base64 encoded data and MIME type. Files larger than 5,242,880 bytes are refused with an error. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing a precise failure threshold (files over 5,242,880 bytes are refused with an error), the returned encoding format, and the directory-scope limitation — three behavioral facts not present in structured fields.
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?
Four short sentences with the core purpose front-loaded, then return value, then hard limits, then scope. Every sentence carries distinct information and none is redundant with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly fills the gap by describing the return payload (base64 + MIME type) and the failure mode, plus the directory constraint. It is nearly complete for a one-parameter read tool; only path-format semantics are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single `path` parameter, so the description carries the burden but only partially compensates: 'Only works within allowed directories' hints at path resolution scope, yet nothing explains absolute vs relative paths, extensions, or how unsupported file types are handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read an image or audio file') and immediately says what it returns (base64 data plus MIME type). The media-versus-text distinction lets an agent infer its place among read_file/read_text_file, but it never names a sibling explicitly, so differentiation is implicit rather than stated.
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?
Usage is implied by the resource type and by two preconditions: a 5,242,880-byte size ceiling and the allowed-directories restriction. There is no explicit 'when to use this instead of read_text_file' routing guidance, so the agent must infer that non-media files belong to the other readers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Results longer than 50,000 characters are cut short, ending with a notice that says how to get the rest. 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint, it discloses failure isolation (one failed read won't abort the batch), a concrete truncation threshold (50,000 characters) with a recovery notice, the return shape (content paired with its path), and a directory restriction. These are exactly the operational traits an agent needs and would otherwise have to discover by trial.
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?
Five compact sentences, each earning its place: purpose first, then efficiency rationale, then return shape, failure behavior, truncation, and scope constraint. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description covers return format, per-file failure semantics, truncation behavior with recovery guidance, and path scope. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the paths parameter is already documented as an array of valid file paths. The description adds only the allowed-directory constraint, which the schema itself also states, so it does not meaningfully exceed the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and resource (contents of multiple files), and its batch scope distinguishes it from the single-file siblings read_file/read_text_file. An agent can select it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the use case ("when you need to analyze or compare multiple files") and positions it against the implicit alternative of reading files one by one. No hard when-not exclusions are given, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Use the 'offset' and 'limit' parameters to read a window of characters, for example to continue after a truncated result; they cannot be combined with 'head' or 'tail'. Results longer than 50,000 characters are cut short, ending with a notice that says how to get the rest. 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 | |
| limit | No | Maximum number of characters to return, clamped to the result cap | |
| offset | No | Character position to start reading from (default 0). Use the offset given in a truncation notice to continue |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true annotation, the description discloses several behavioral traits: a 50,000-character truncation cap with a notice explaining how to continue, detailed error messages, automatic text decoding across encodings, and the 'only works within allowed directories' constraint. This is rich, non-obvious operational detail that an agent could not infer from the annotation or schema.
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?
Purpose is front-loaded in the first sentence, followed by usage, parameter modes, truncation behavior, and the directory constraint. Six sentences that each carry distinct information with no redundancy, though it is on the longer side for a read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and 80% schema coverage, the description adequately covers encoding handling, error reporting, truncation, and windowing modes. It leaves minor gaps such as the format of the truncation notice and permission requirements, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so the schema already documents head, tail, limit, and offset. The description adds a genuinely important constraint the schema omits — that offset/limit cannot be combined with head/tail — plus a concrete use case ('continue after a truncated result'). It adds value beyond the schema, though the bare 'path' parameter still carries 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?
The description states a specific verb and resource ('Read the complete contents of a file from the file system as text') and clarifies scope with 'Operates on the file as text regardless of extension.' It implies a contrast with read_media_file/read_file but never names a sibling, so differentiation is only implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context ('Use this tool when you need to examine the contents of a single file') and thoroughly explains which parameter mode to use for line-limited vs. windowed reading. It does not explicitly name read_multiple_files or read_file as the alternatives to prefer for multi-file or single-file reads, so routing guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, and the description adds real context beyond it: the search is confined to allowed directories and results are full paths. It does not disclose ordering or result-size/truncation behavior, which is a minor gap for a read tool with annotation coverage.
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?
Five short sentences, front-loaded with the core action and pattern syntax before examples and return info. Slightly repetitive with two pattern examples, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly states what is returned (full paths), and scope plus pattern syntax are covered. The undocumented 'excludePatterns' parameter leaves the definition incomplete for a tool whose schema provides no parameter descriptions at all.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It handles 'pattern' well ('*.ext' vs '**/*.ext', relative to working directory) and implies 'path', but says nothing about 'excludePatterns', leaving one of three parameters entirely undocumented in both schema and 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?
States a specific verb+resource ('recursively search for files and directories matching a pattern') and names the matching mechanism (glob patterns), which clearly separates it from list_directory and directory_tree. It stops short of explicitly naming or contrasting those siblings, so it lands at 4 rather than 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?
The sentence 'Great for finding files when you don't know their exact location' implies when to reach for it, but no explicit when-not guidance or named alternatives (e.g., use list_directory for a single non-recursive listing) are given. Usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive=true and idempotent=true, and the description reinforces this with 'overwrite existing files without warning'. It adds context beyond the annotations: the sandboxing constraint ('only works within allowed directories') and the limitation to text content with proper encoding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and the destructiveness warning second. 'Handles text content with proper encoding' is slightly vague but still earns its place as a limitation statement.
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 two-parameter write tool with no output schema, the description covers the destructive behavior, the sandboxing constraint, and the text-only scope. It lacks error/failure behavior disclosure, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden for both parameters. It partially compensates by hinting that path is constrained to allowed directories and that content is text with encoding handling, but it gives no path format guidance (absolute vs relative) or content-size/encoding specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a new file or completely overwrite an existing file') and pins down the scope of what it writes. It does not name the obvious alternative (edit_file) for partial modifications, but the phrase 'completely overwrite' implicitly separates it from incremental editing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It warns 'Use with caution as it will overwrite existing files without warning' and constrains operation to allowed directories, which is useful contextual guidance. However it never says when to prefer this over edit_file or other siblings, leaving the agent to infer that from the word 'overwrite'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_directorydirectory_treeedit_fileget_file_infolist_allowed_directorieslist_directorylist_directory_with_sizesmove_fileread_fileread_media_fileread_multiple_filesread_text_filesearch_fileswrite_fileSafe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.
User-owned files and explicit AI Memories for authorized assistants with scoped access.