Supports external authentication via reverse proxy headers, allowing integration with Authelia for authentication.
Supports external authentication via reverse proxy headers, allowing integration with Authentik for authentication.
Provides a read-only S3-compatible API that can be accessed by MinIO client for file browsing and downloads.
Exposes Prometheus metrics at the /metrics endpoint for monitoring server operations.
Provides a read-only S3-compatible API that can be used by rclone for file access and synchronization.
A stateless, read-only web file browser for homelab and NAS power users. No database, no background workers, no disk writes - just point it at a mounted path and go.
Browse files in a clean web UI with search, previews, and archive inspection. Download individual files or entire folders as ZIP. Access the same data through a RESTful JSON API, an S3-compatible endpoint for tools like rclone, a read-only WebDAV mount for native OS file managers, or an MCP server for AI assistants. Everything runs in a single stateless container with no external dependencies.
Prerequisite: Docker or Podman (images are published for amd64 and arm64).
docker run -d \
--name dirforge \
-p 8091:8080 \
-e RootPath=/data \
-v /srv/share:/data:ro \
ghcr.io/dissimilis/dirforge:latestcp .env.example .env
# edit HOST_PATH, BasicAuthUser, and BasicAuthPass in .env
docker compose up -dWarning: The default compose file falls back to
admin/dirforgecredentials if you don't setBasicAuthUserandBasicAuthPassin your.env. Change these before exposing the service on your network.
The same commands work with Podman. Replace docker with podman:
podman run -d \
--name dirforge \
-p 8091:8080 \
-e RootPath=/data \
-v /srv/share:/data:ro \
ghcr.io/dissimilis/dirforge:latestFor Compose, use podman compose (Podman 4.1+):
cp .env.example .env
# edit HOST_PATH in .env
podman compose up -dNotes for Podman users:
podman composeis a built-in subcommand in Podman 4.1+, not the older third-partypodman-composePython package.DirForge uses ports above 1024, so rootless Podman works without extra configuration.
On SELinux systems (Fedora, RHEL), add
:zto volume mounts:-v /srv/share:/data:ro,z.
Download dirforge-win-x64.zip from the latest release
Extract to a folder (e.g. C:\DirForge)
Edit appsettings.json — set RootPath to the directory you want to share
Console mode: Double-click DirForge.exe to run interactively
Windows Service: Right-click install-service.bat → Run as administrator. DirForge will start on boot automatically. Use uninstall-service.bat to remove the service.
Download dirforge-linux-x64.tar.gz (or linux-arm64) from the latest release
Extract: tar -xzf dirforge-linux-x64.tar.gz -C /opt/dirforge
Edit appsettings.json — set RootPath to the directory you want to share
Run directly: ./DirForge
Install as systemd service:
sudo useradd -r -s /usr/sbin/nologin dirforge
sudo cp dirforge.service /etc/systemd/system/
# Edit /etc/systemd/system/dirforge.service to adjust paths if needed
sudo systemctl daemon-reload
sudo systemctl enable --now dirforgeThe tarball includes an example dirforge.service file with systemd hardening options.
Open http://localhost:8091.
With the default config profile in this repository, sharing, dashboard, and metrics are enabled.
Related MCP server: mcp-file-lens
List and grid view layouts
Sortable columns (name, size, date)
Light and dark themes (toggle or set default via DefaultTheme)
File preview modal for text, images, video, audio, and PDF
Inline archive browser for .zip, .tar, .tar.gz, .tgz, and .gz
Image lightbox with navigation
Recursive search with configurable depth and time budget
Age badges on files and folders
Custom site title via SiteTitle
Direct file downloads
Folder download as ZIP archive (with configurable max size)
Signed share links with expiry
One-time share links
QR code generation for share links
File hash calculation (CRC32, MD5, SHA-1, SHA-256, SHA-512)
Sidecar checksum verification (.md5, .sha1, .sha256, .sha512, .sfv)
Read-only WebDAV endpoint at /webdav/ (DAV Class 1)
Supports OPTIONS, PROPFIND, GET, and HEAD methods
Compatible with Windows Explorer, macOS Finder, and other WebDAV clients
Same security policies as the web UI (hidden paths, denied extensions, auth)
Read-only S3 endpoint at /s3/ for scripted and programmatic access
Compatible with aws cli, rclone, MinIO client, and other S3-compatible tools
AWS Signature V4 authentication (access key + secret key)
Supports ListBuckets, GetBucketLocation, ListObjectsV2, GetObject, HeadObject
HTTP Range requests for partial downloads
Hidden paths, denied extensions, and auth enforced
HTTP Basic Auth (username + password)
Bearer token auth via configurable header (for MCP clients, API consumers, automation)
External auth via reverse proxy headers (e.g. Authelia, Authentik)
Hide files by dotfile flag or glob patterns
Deny downloads by file extension
Fixed-window rate limiting (per-IP and global)
Health endpoints (/health, /healthz, /readyz)
In-memory dashboard at /dashboard with optional dedicated credentials
Prometheus metrics at /metrics
RESTful JSON API at /api/ (browse, search, share, archive)
MCP server at /mcp/ (JSON-RPC 2.0, Streamable HTTP transport)
Integration stats JSON at /dashboard/stats
Distroless chiseled container image
Defaults are defined in src/DirForge/appsettings.json. Override any value with an environment variable of the same name. Boolean values must be true or false. For the full list of options, see .env.example.
Variable | Default | Description |
|
| Root directory to browse. |
|
| HTTP listen port. |
|
| IP address the app binds to. |
| unset | Basic Auth username. |
| unset | Basic Auth password. |
| unset | Bearer token for token-based auth (MCP clients, API consumers, automation). |
|
| Header to read the bearer token from. |
|
| Enable HMAC-signed share links. |
| empty | Secret for signing share links. Set a long random value in production; if empty an in-memory secret is generated at startup. |
|
| Hide entries starting with |
|
| Extensions blocked in direct and ZIP downloads. |
|
| UI theme ( |
|
| Custom page title/header label. |
|
| Read-only WebDAV at |
|
| Read-only S3 API at |
|
| RESTful JSON API at |
|
| MCP server at |
|
| Auto-calculate subdirectory sizes on page load (slow on large trees). |
|
| Cache TTL for computed directory sizes in seconds (0–2592000; 0 disables). |
|
| Directory listing cache TTL in seconds (1–2592000). |
Hardened example profile - copy into your .env and adjust:
BasicAuthUser=admin
BasicAuthPass=change-this
BearerToken=replace-with-long-random-token
ShareSecret=replace-with-long-random-value
ForwardedHeadersKnownProxies=10.0.0.2
DashboardAuthUser=metrics
DashboardAuthPass=change-this-tooMount only directories you want to expose; prefer read-only mounts (:ro).
Baseline defaults are homelab-oriented, not internet-hardened.
Set BasicAuthUser / BasicAuthPass when exposed outside a trusted network.
Set BearerToken for token-based auth (useful for MCP clients, API consumers, and automation that poorly support Basic Auth). Both auth methods can be enabled simultaneously, either one grants access.
When BearerTokenHeaderName is Authorization (default), the middleware accepts Authorization: Bearer <token> and Authorization: <token>. Set a custom header name (e.g. X-API-Key) to read the raw token from that header instead.
Set ShareSecret to a long random value in production. If empty, DirForge uses an in-memory secret and share links reset on restart.
For reverse proxy auth, set ExternalAuthEnabled=true and pin ForwardedHeadersKnownProxies. Bearer token auth is also bypassed when external auth is enabled.
Hidden paths and denied extensions are enforced for both direct downloads and ZIP output.
Dashboard and metrics data are in-memory only and reset on restart.
If DashboardAuthUser / DashboardAuthPass are set, /dashboard and /metrics accept only those credentials.
/dashboard/stats uses the same dashboard auth behavior: if dashboard credentials are configured, they are required.
Static UI assets are served from /dirforge-assets/* (plus /favicon.ico) and are intentionally public.
DirForge includes a read-only WebDAV endpoint at /webdav/ (DAV Class 1), enabled by default. It supports OPTIONS, PROPFIND, GET, and HEAD. All write methods return 405 Method Not Allowed.
Client | Connection |
macOS Finder | Finder → Go → Connect to Server → |
Windows Explorer | Map Network Drive → |
Linux (GVFS) |
|
cadaver / curl |
|
Windows Explorer's WebDAV client (Mini-Redirector) refuses Basic Auth over plain HTTP by default. You must either:
Use HTTPS (via reverse proxy, recommended)
Set the registry key HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel to 2 and restart the WebClient service
WebDAV requests follow the same auth and security pipeline as the web UI:
Basic Auth or bearer token credentials are required when configured
External auth headers are honored when ExternalAuthEnabled=true
Hidden paths (HideDotfiles, HidePathPatterns) and denied extensions (DenyDownloadExtensions) are enforced
Path traversal protection applies to all WebDAV paths
Set EnableWebDav=false to disable the endpoint entirely.
DirForge includes a read-only S3-compatible endpoint at /s3/, disabled by default. It implements the minimal subset of the S3 API needed for listing and downloading files with standard S3 tools.
Operation | Description |
|
|
|
|
|
|
|
|
|
|
All write operations (PUT, POST, DELETE) return 405 Method Not Allowed.
S3 requests use AWS Signature V4 - the same signing protocol as real AWS S3. Your secret key is never sent over the wire; clients sign each request with an HMAC-based signature that the server verifies.
By default, the S3 endpoint reuses your BasicAuthUser / BasicAuthPass as access key / secret key. Set S3AccessKeyId and S3SecretAccessKey for dedicated S3 credentials.
Credentials are required - the app will not start with EnableS3Endpoint=true and no credentials configured.
aws cli:
export AWS_ACCESS_KEY_ID=mykey
export AWS_SECRET_ACCESS_KEY=mysecret
aws --endpoint-url http://localhost:8091/s3 s3 ls
aws --endpoint-url http://localhost:8091/s3 s3 ls s3://dirforge/
aws --endpoint-url http://localhost:8091/s3 s3 ls s3://dirforge/subdir/
aws --endpoint-url http://localhost:8091/s3 s3 cp s3://dirforge/file.txt .rclone:
rclone config create myremote s3 \
provider=Other \
endpoint=http://localhost:8091/s3 \
access_key_id=mykey \
secret_access_key=mysecret \
region=us-east-1
rclone ls myremote:dirforge
rclone copy myremote:dirforge/file.txt .S3 requests bypass Basic Auth (they use SigV4 instead) but enforce all the same file-level policies:
Hidden paths (HideDotfiles, HidePathPatterns) are not visible
Denied extensions (DenyDownloadExtensions) return 403 Access Denied
Path traversal and symlink containment checks apply
Set EnableS3Endpoint=false (default) to disable the endpoint entirely.
DirForge exposes an MCP endpoint at /mcp that lets AI assistants browse directories, read files, search by name or content, check hashes, find duplicates, get disk usage reports, and more. Requires EnableMcpEndpoint=true (default) and a BearerToken set in your DirForge config. All hide/deny/auth policies apply.
Just ask your AI assistant:
"Add DirForge MCP server at http://localhost:8091/mcp with bearer token
changeme"
Then swap changeme for your actual BearerToken in a file config was added.
DirForge follows symlinks but enforces strict containment: every symlink target must resolve to a path under RootPath. Links that escape the root are silently blocked.
When a request path contains a symlink, DirForge resolves it segment-by-segment. At each level, if a path component is a reparse point (symlink or junction), the final target is resolved and checked against RootPath. If the resolved target is outside the root, the entire path is rejected.
This means you can use symlinks freely inside your shared directory tree — for example, to present files from multiple physical locations under a single virtual layout — as long as every target points somewhere within RootPath.
During recursive operations (search, ZIP download, S3 listing), it tracks visited canonical paths to prevent infinite loops caused by circular symlinks. A directory that has already been visited (after symlink resolution) is skipped.
Hardlinks are regular directory entries that share an inode with another file. They have no special metadata that distinguishes them from normal files, so DirForge treats them as ordinary files. Both names are listed and downloadable independently. There is no risk of escaping RootPath through hardlinks since they cannot point outside the filesystem they reside on, and they cannot reference directories.
Link Type | Followed | Root Containment | Cycle Protection |
Symlink | Yes | Enforced per-segment | Yes (visited set) |
Junction (Windows) | Yes | Enforced per-segment | Yes (visited set) |
Hardlink | N/A (treated as regular file) | N/A | N/A |
For homelab dashboards (Homarr, Homepage, etc.), DirForge exposes:
GET /dashboard/stats
The endpoint returns compact JSON with 11 basic fields:
generatedAtUtc, ready, uptimeSeconds, totalRequests, inFlightRequests, requestsPerMinute, averageLatencyMs, totalDownloadTrafficBytes, totalDownloadCount, fileCount, zipCount.
See CONTRIBUTING.md.
dotnet restore src/DirForge/DirForge.csproj
dotnet build src/DirForge/DirForge.csproj -c Release --no-restore
docker build -t dirforge:dev . # or: podman build -t dirforge:dev .Images are published to ghcr.io/dissimilis/dirforge.
Tag | When pushed | Use for |
| Every non-pre-release GitHub Release | Stable production use |
| Every GitHub Release | Pinned stable version |
| Every push to | Latest development build |
| Every push to | Pinned to a specific commit |
MIT. See LICENSE.
File icon vector set in src/DirForge/wwwroot/file-icon-vectors/ is attributed to dmhendricks.
Compare two directories side by side. Shows files only in the first, only in the second, files that differ, and identical files.
| Name | Required | Description | Default |
|---|---|---|---|
| path1 | Yes | Relative path to the first directory. | |
| path2 | Yes | Relative path to the second directory. | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.log, *.txt'). Only matching files are returned. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the output categories (files only in first/second, different, identical) but does not mention that traversal is recursive or that maxDepth controls depth. Since no annotations are provided, the description carries the full burden; missing recursion details lowers the score.
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 two sentences long, with the first sentence stating the primary action and the second elaborating on the output. No redundant or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (2 required) and no output schema, the description covers the basic behavior and output categories but could mention recursive traversal and the effect of filtering parameters. The schema covers parameter details, so the description is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with parameter descriptions. The tool description adds no additional parameter information beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two directories and outputs four categories of file differences. It distinguishes itself from siblings like diff_snapshots (compares snapshots) and list_directory (just lists contents).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparing directories but does not specify when to use this versus alternative tools like diff_snapshots or find_potential_duplicates. No explicit exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect filesystem changes in a directory. On first call (without a previousToken), returns a snapshot token. On subsequent calls, pass the previous token to get a structured diff of added, removed, and modified files. The token is self-contained — no server-side state is stored.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| previousToken | No | Snapshot token from a previous call. Omit for first snapshot. | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the stateless token mechanism, first-call token return, and subsequent diff output. However, it omits edge cases like invalid tokens or performance implications.
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, no wasted words, front-loaded with the main purpose. Highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain return values. It mentions 'snapshot token' and 'structured diff' but does not specify the diff format or token characteristics, which is a gap for full agent understanding.
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 100%, so baseline is 3. The description adds some context (e.g., omitting previousToken on first call), but overall adds minimal value beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects filesystem changes in a directory, distinguishing it from siblings like compare_directories (which compares two directories) and list_directory (which lists contents) by describing the token-based two-step process.
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 explains the usage pattern: first call without previousToken, subsequent calls with it. However, it does not explicitly state when not to use this tool or name alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize total size, file count, and directory count for a path. Shows top subdirectories by size. Optionally filter by glob pattern to summarize only matching files.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.jpg, *.png'). Only matching files count toward totals. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it summarizes counts, sizes, and top subdirectories, and supports filtering. However, it does not mention aspects like symlink handling or performance characteristics, which would be helpful for a file system tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences effectively convey the core purpose and key features. No wasted words; the most important information is front-loaded.
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 4 parameters, no output schema, and no annotations, the description covers the main functionality and filtering. It mentions maxDepth implicitly via the schema, but could be more explicit. Overall, it provides sufficient context for a summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds contextual meaning by stating that include/exclude are glob patterns for filtering, reinforcing the tool's behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Summarize total size, file count, and directory count,' which is a specific verb and resource. It also mentions showing top subdirectories and optional glob filtering, distinguishing it from siblings like compare_directories or find_largest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for summarization but does not explicitly state when to use this tool versus alternatives like get_directory_tree or find_largest_directories. With many sibling tools, some guidance would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the largest files under a directory, sorted by size descending.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| maxResults | No | Maximum results to return (default: 20, max: 100). | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.log, *.txt'). Only matching files are returned. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It describes the operation as finding and sorting files, which is adequate for a read tool, but lacks details on edge cases or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words, efficiently conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacking an output schema, the description does not explain return format, pagination default, or behavior when no results are found, leaving significant gaps for a tool with 5 parameters.
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 100%, so baseline is 3. The description does not add significant meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds the largest files under a directory, sorted by size descending. It distinguishes from siblings like find_largest_directories and disk_usage_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding large files but provides no explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the largest directories by total recursive size, sorted by size descending.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| maxResults | No | Maximum results to return (default: 20, max: 100). | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should disclose behavioral traits. It only mentions sorting order. Missing details like whether it follows symlinks, excludes hidden directories, performance impact, or if results are real-time or cached.
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?
Single sentence with clear, front-loaded purpose. No unnecessary words. Could slightly expand on behavioral details without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 parameters and no output schema or annotations. Description covers core purpose but omits default values for maxResults, maxDepth constraints, and exclude glob syntax. Schema fills some gaps, but overall adequate but not fully complete.
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 covers 100% of parameters with descriptions. Description adds no additional meaning beyond schema. Baseline score of 3 is appropriate.
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?
Description clearly states verb 'Find', resource 'largest directories', scope 'by total recursive size', and ordering 'sorted by size descending'. Distinguishes from sibling tools like 'find_largest' (likely files) and 'disk_usage_summary' (summary vs listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'find_largest' or 'get_directory_tree'. No mention of prerequisites, context, or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find potential duplicate files by grouping files with identical sizes then hashing candidates. Uses XXH3-128 with 5 × 2 MiB probabilistic chunk sampling (first, last, and 3 pseudo-random interior chunks per file) — results are potential duplicates, not guaranteed exact matches.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| minSize | No | Minimum file size in bytes to consider (default: 1). | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| maxResults | No | Maximum number of duplicate groups to return (default: 20, max: 100). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.log, *.txt'). Only matching files are returned. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the hashing algorithm (XXH3-128) and sampling method (5×2 MiB chunks), and clearly states results are potential duplicates, not exact. Good transparency, though it does not mention side effects or resource usage.
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?
Two sentences: first states the high-level function, second provides technical detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not explain return format (e.g., structure of duplicate groups). Could also mention performance considerations. Adequate but not fully complete.
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 covers all 6 parameters with descriptions; description adds no extra meaning beyond the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it finds potential duplicate files using size grouping and hashing. Distinct from sibling tools which do not perform duplicate detection.
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?
Implies usage for finding potential duplicates but provides no explicit guidance on when to use or avoid this tool. Given many sibling tools, differentiation is implicit only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the most recently modified files under a directory, sorted by date descending.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| maxResults | No | Maximum results to return (default: 20, max: 100). | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.log, *.txt'). Only matching files are returned. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description should disclose behavioral traits beyond the basic purpose. It only mentions sorting by date but does not reveal that it recursively traverses directories, respects include/exclude patterns, or that it is a read-only operation. Important details like depth limits and result caps are left to the schema, which the agent may not infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words that immediately conveys the core action and ordering. Every word adds value, and no extraneous information is present. It is appropriately sized and front-loaded for an AI agent to quickly understand the tool's main function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description is too minimal to provide a complete understanding. It does not explain the behavior of the depth traversal, filtering via include/exclude, or the format of the returned results. The agent would need to rely entirely on the schema for details, which may not be sufficient for effective usage.
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 baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter. It does not elaborate on how to use the parameters together or what the output includes, but the schema descriptions are adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find', the resource 'most recently modified files under a directory', and the sorting behavior 'sorted by date descending'. This is specific and distinguishes it from siblings like 'list_directory' (lists all files) or 'search_by_date' (likely searches by date range).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus its siblings. It lacks explicit context such as 'Use this to find recently modified files; for other search criteria, use find_largest or search_by_date instead.' The usage context is only implied by the tool's name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a visual tree representation of a directory structure, similar to the 'tree' command.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| maxDepth | No | Maximum depth to traverse (default: 3, max: 10). | |
| includeSizes | No | Include file/directory sizes in output (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies output is textual/tree-like but doesn't specify format or constraints. No annotations exist to supplement. It's adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose without extraneous details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and many siblings, the description doesn't clarify return format or provide enough context for usage decisions. It's functional but barely adequate for the complexity.
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 100%, so the schema already documents all parameters. The description adds no extra meaning beyond the schema, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: getting a visual tree representation of a directory, analogous to the 'tree' command. It uses a specific verb and resource, and the analogy effectively distinguishes it from siblings like 'list_directory'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools for directory analysis, missing context for selection is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute CRC32, MD5, SHA1, SHA256, and SHA512 hashes of a file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description lists the hash algorithms but does not disclose additional behavioral traits such as file access requirements, read-only nature, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose and lists all hash types without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers the hash types computed. Minor gaps include missing error scenarios or read-only guarantees, but it is complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a full description of the 'path' parameter (100% coverage). The tool description adds no extra meaning beyond what is already 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?
The description clearly states the action (compute) and the resource (hashes of a file), listing specific hash types. It distinguishes from sibling tools like get_file_info and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., get_file_info for metadata, search for content). It only states what it does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed metadata about a file including size, modification date, and MIME type.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does not disclose whether the tool is read-only, whether it works on directories or only files, if there are any restrictions (e.g., file size limits), or what happens if the path doesn't exist. The description is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the key action. However, it could include additional useful details (e.g., output format) without being verbose, so it is slightly under-informative for maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should fully explain what the tool returns. It mentions three metadata fields but does not specify output format, all possible fields, or error behavior. For a simple tool with one parameter, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the 'path' parameter with 100% coverage. The description does not add meaning beyond what the schema provides, but it hints at the kind of metadata returned, which indirectly adds context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('detailed metadata about a file'), and provides specific examples ('size, modification date, and MIME type'). This distinguishes it from sibling tools like 'read_file' which returns content, and 'list_directory' which lists entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't clarify that it should be used over 'read_file' when only metadata is needed, or that it can be used on directories. Sibling tools like 'get_directory_tree' exist but no comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize all files under a directory grouped by modification date buckets (Today, Yesterday, This week, This month, This year, Older).
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the grouping into date buckets but does not disclose whether the summary includes counts, sizes, or if it is recursive. The output format is not described, leaving behavior partly ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the key action and resource, making it highly 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?
Given no output schema and no annotations, the description is moderately complete. It covers the main action but lacks details about output format, recursion, and performance considerations. For a simple tool, it is acceptable but could be improved.
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 100%, so baseline is 3. The description mentions 'a directory' but adds no extra meaning beyond the schema's 'Relative path within the file server root'. The optional nature of the parameter is not clarified in the 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 clearly states the verb 'Summarize' and the resource 'all files under a directory grouped by modification date buckets'. It distinguishes itself from sibling tools like group_tree_by_type and search_by_date by specifying the grouping criterion (date buckets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is useful for getting a high-level view of file modification ages, but it does not explicitly state when to use this tool over alternatives like find_recent or search_by_date. No when-not or exclusion guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize all files under a directory grouped by file extension, with counts and total sizes.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| maxDepth | No | Maximum depth to traverse (default: 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behaviors. It mentions grouping by extension but doesn't specify handling of hidden files, directories, or errors. Behavior with maxDepth (traversal depth) is implied but not explicitly described. Missing details on what is returned for empty directories or non-existent paths.
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?
Single sentence of 18 words, front-loaded with the tool's primary function. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description partially explains return values (counts and total sizes) but not the structure (flat or nested). Lacks details on error cases or large directory handling. Adequate for simple use but not fully complete.
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 descriptions cover both parameters (path and maxDepth) at 100%. The description adds context by saying 'under a directory' (relating to path) and 'grouped by file extension' (explaining output logic), but does not mention maxDepth. Baseline 3 due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes files under a directory grouped by file extension with counts and sizes. It uses specific verb 'summarize' and specific resource 'files under a directory', and distinctly separates from sibling tool 'group_tree_by_date' which groups by date.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives like 'group_tree_by_date' or 'disk_usage_summary'. No when-to-use or when-not-to-use conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and directories inside an archive (ZIP, TAR, TAR.GZ). Supports browsing into subdirectories within the archive.
| Name | Required | Description | Default |
|---|---|---|---|
| archivePath | Yes | Relative path to the archive file. | |
| path | No | Directory path within the archive. Empty string for root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description partially covers behavior: supports multiple archive formats and subdirectory browsing. However, it lacks details on performance considerations, error cases (password-protected archives), or return format. Moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Purpose is front-loaded. Efficient and to the point.
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 is provided, and the description does not explain the return format (e.g., list of names with metadata). Given the tool's simplicity, this is a notable gap. Lacks completeness for effective agent decision-making.
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 100% with clear parameter descriptions. The description adds context for the 'path' parameter ('supports browsing into subdirectories'), but overall value beyond schema is marginal. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists files and directories inside archives (ZIP, TAR, TAR.GZ) and supports browsing subdirectories. It distinguishes from sibling tools like list_directory (filesystem) and read_archive_entry (reading content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not specify when to use this tool versus alternatives like read_archive_entry or list_directory. No explicit guidance on prerequisites, limitations, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contents of a directory. Returns file and folder names with sizes and modification dates.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full behavioral burden. It discloses output elements (names, sizes, dates) but omits whether listing is flat or recursive, error handling (e.g., missing directory), or performance characteristics. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-formed sentence conveying core functionality. Very concise, but could be slightly more structured (e.g., separating purpose from returns).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple but description does not mention default behavior when path is omitted (though required is false, implied root). No output schema, so return structure details are minimal. Adequate for basic use but leaves some ambiguity.
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?
Input schema has 100% coverage with a description for the 'path' parameter. The tool description adds no additional semantic value beyond what the schema already provides. Baseline 3 is appropriate.
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?
Description clearly states the action 'List contents of a directory' and specifies the return values (names, sizes, modification dates). This effectively distinguishes it from sibling tools like get_directory_tree (likely recursive) or disk_usage_summary (aggregated usage).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With 21 siblings like compare_directories or find_largest, explicit when-to-use or when-not-to-use context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the text contents of a file entry inside an archive (ZIP, TAR, TAR.GZ).
| Name | Required | Description | Default |
|---|---|---|---|
| archivePath | Yes | Relative path to the archive file. | |
| entryPath | Yes | Path of the entry within the archive. | |
| maxBytes | No | Maximum bytes to read from the entry (default: server limit). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Indicates it's a read operation (non-destructive) but lacks details on encoding, handling of binary content, error cases, or any side effects. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no superfluous words, front-loaded with the core action and resource. Every word 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?
Given no output schema, the description is adequate for a simple read operation but omits details like return format (e.g., plain text, assumed UTF-8), behavior for non-text entries, and error conditions (missing archive/entry). Could be more complete.
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 100%, so baseline is 3. The description does not add extra meaning beyond the schema; it merely states the tool's purpose. No enhancement or degradation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Read' and resource 'text contents of a file entry inside an archive', specifying supported formats (ZIP, TAR, TAR.GZ). Distinguishes well from sibling tools like list_archive_entries (lists entries) and read_file (reads plain files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes what the tool does but provides no guidance on when to use it vs alternatives, no prerequisites, and no exclusions. Agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the text contents of a file. Only works for text files within the size limit. Binary files (images, videos, executables, etc.) will be rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file. | |
| maxBytes | No | Maximum bytes to read (default: server limit). | |
| startLine | No | If provided, returns only lines starting from this 1-based line number. | |
| endLine | No | If provided, returns only lines up to and including this 1-based line number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool reads text, rejects binaries, and hints at size limits, but does not mention error handling for missing files or default behavior for parameters like line ranges. The description adds some context beyond the schema but not enough for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no wasted words. The purpose is front-loaded in the first sentence. Every sentence adds value, making it efficient for an AI agent to process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is largely complete. It covers the key behavioral constraints (text only, size limit, rejection of binaries). It does not explain the line range feature in detail, but the schema already covers that. Without an output schema, the description could hint at return format, but it's not essential for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description adds no new meaning to the parameters beyond what the schema provides. For example, it mentions 'size limit' but the schema already describes maxBytes. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read the text contents of a file.' It specifies it only works for text files within a size limit, distinguishing it from potential sibling tools that might handle binary files. The verb 'Read' and resource 'file' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage conditions: 'Only works for text files within the size limit. Binary files ... will be rejected.' This tells the agent when to use the tool (text files) and when not to (binary files), though it does not explicitly suggest alternatives for binary files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for files and folders by name pattern.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (filename pattern). | |
| path | No | Directory to search within. Empty for root. | |
| maxResults | No | Maximum results to return (default: 200). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read-only operation but does not specify behavioral traits like case sensitivity, recursion depth, or pagination.
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?
Single sentence, perfectly concise and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large number of sibling tools and no output schema, the description is too minimal. It does not specify that it only searches by name or provide context on when to use it over other search tools.
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 100%, so baseline is 3. Description adds no extra meaning beyond the schema; it just restates 'name pattern' already in the query parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for files and folders by name pattern, but does not distinguish from sibling tools like search_by_date or search_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It does not mention that other search tools exist for different criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files modified within a date range. Supports before, after, or between. Results sorted by date descending.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| after | No | ISO date string (e.g. '2025-01-01'). Only include files modified after this date. | |
| before | No | ISO date string (e.g. '2025-02-01'). Only include files modified before this date. | |
| maxResults | No | Maximum results to return (default: 20, max: 100). | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.log, *.txt'). Only matching files are returned. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. | |
| includeDirectories | No | Include directories in results (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses sorting by date descending and support for before/after/between, but lacks details on permissions, side effects, or behavior when parameters are omitted.
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 with no redundancy. Efficiently conveys core functionality and key features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description is adequate but not comprehensive. It omits guidance on parameter interplay or default behaviors, though required parameters are none.
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 100%, so the description adds minimal additional meaning. It mentions 'before, after, or between' which aligns with schema but does not enrich parameter understanding beyond already documented fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds files modified within a date range, with clear verb and resource. It distinguishes itself from sibling tools like search_by_size and search_content by focusing on date filtering and mentioning sorting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for date-based file retrieval but does not explicitly state when not to use or compare with siblings like find_recent. No alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files within a size range. Supports min, max, or both. At least one of minSize or maxSize is required. Results sorted by size descending.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path within the file server root. Empty string for root. | |
| minSize | No | Minimum file size in bytes (inclusive). | |
| maxSize | No | Maximum file size in bytes (inclusive). | |
| maxResults | No | Maximum results to return (default: 20, max: 100). | |
| maxDepth | No | Maximum depth to traverse (default: 10, max: 10). | |
| include | No | Comma-separated glob patterns to include (e.g. '*.log, *.txt'). Only matching files are returned. Supports * and ? wildcards. Empty means all files. | |
| exclude | No | Comma-separated glob patterns to exclude (e.g. 'node_modules, *.tmp'). Matching files and directories are skipped. Supports * and ? wildcards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states it finds files and sorts results. It gives no insight into read-only behavior, permission needs, or side effects. It is minimally informative for a presumably safe read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence delivers the purpose, and the second adds two critical constraints. Every word 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?
Despite good schema coverage, the description omits important context: there is no output schema, yet it doesn't hint at return format, pagination (maxResults default 20), directory traversal (maxDepth), or how include/exclude patterns interact with size filtering. For a tool with 7 parameters, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already described. The description adds value by specifying 'At least one of minSize or maxSize is required' (a constraint not in schema) and 'Results sorted by size descending' (behavioral detail). This goes beyond the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find files within a size range', immediately identifying the tool's purpose. This distinguishes it from siblings like search_by_date or find_largest, which target other criteria.
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 mentions support for min, max, or both and requires at least one size parameter, but does not specify when to use this tool instead of alternatives like find_largest (for top files) or search (for name-based queries). No explicit exclusions or context for directory traversal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for text inside files (grep-like). Returns matching lines with line numbers. Only searches text files.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Case-insensitive text to search for inside files. | |
| path | No | Directory to search within. Empty for root. | |
| maxResults | No | Maximum matching lines to return (default: 50, max: 200). | |
| maxFileSize | No | Skip files larger than this many bytes (default: 2 MB, max: 10 MB). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that it only searches text files and returns line numbers, but does not mention that it is read-only, concurrency limits, or other behavioral aspects. It provides some transparency but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the purpose and key constraints. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with full schema coverage and no output schema, the description is fairly complete for a simple search tool. It could mention the output format explicitly, but the combination of schema and description suffices.
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 descriptions cover all 4 parameters (100% coverage). The description adds 'grep-like' context but does not enhance understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for text inside files (grep-like), returns matching lines with line numbers, and only searches text files. This distinguishes it from sibling tools like search_by_date or search_by_size which filter by metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for content searching via 'grep-like', but does not explicitly state when to use this tool versus alternatives, nor provides exclusions or context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a file's integrity against a sidecar checksum file. Looks for a sidecar file in the same directory as the target file by appending a hash extension (e.g. for 'movie.mkv' it checks 'movie.mkv.sha256', 'movie.mkv.md5', 'movie.mkv.sfv', etc.). Supported sidecar formats: .sha512, .sha256, .sha1, .md5 (and their *sum variants), and .sfv (CRC32). Returns the algorithm used, the expected hash from the sidecar, the freshly computed hash, and whether they match.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file to verify (the data file, not the sidecar). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains sidecar discovery by appending extensions and lists supported formats, but omits behavior for missing sidecars, multiple matching sidecars, or error handling for invalid files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: three sentences covering purpose, sidecar discovery mechanism, and return values. No redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the four return values (algorithm, expected hash, computed hash, match), which covers key outputs. However, it lacks details on error scenarios (e.g., sidecar not found, hash mismatch) and exact return structure. Given the simplicity of the tool, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'path' parameter as the data file, not sidecar. The description adds minimal extra meaning beyond clarifying that the path is relative. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: verifying a file's integrity against a sidecar checksum file. It specifies the resource (file) and action (verify), and differentiates from siblings like get_file_hashes by focusing on sidecar verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a sidecar file exists, but does not explicitly state when to use this tool vs alternatives, nor does it provide conditions for avoidance or prerequisite checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: compare directories, diff snapshots, disk usage summary, various find operations, tree visualization, file hashing, grouping, archive handling, searching, and integrity verification. No two tools overlap in functionality.
Tool names follow a consistent snake_case convention and mostly use verb_noun (e.g., compare_directories, find_largest). A minor deviation is 'disk_usage_summary' which is a noun phrase rather than a verb phrase, but overall the pattern is clear and predictable.
21 tools cover a comprehensive set of file system operations including listing, searching, comparing, archiving, hashing, and grouping. The count is well-scoped for a utility server without being overwhelming or sparse.
The tool set thoroughly covers analysis and inspection of directories and files (searching, comparing, archiving, hashing, grouping). However, it lacks write operations (create, delete, move, copy), which may be intentional for a read-only utility but leaves a notable gap for full file management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Publish HTML, Markdown, and multi-file sites as shareable URLs instantly via MCP.
Browse and manage files in your Moxt AI workspace from any MCP client.
A MCP server built for developers enabling Git based project management with project and personal…
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Dissimilis/DirForge'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
