What can you do with this server?

The mcp-audit server is a security and observability proxy wrapping an upstream filesystem MCP server. It provides two layers of functionality: Filesystem Operations (via proxied server) * Read files: read_text_file (full or first/last N lines), read_media_file (images/audio as base64), read_multiple_files (batch), read_file (deprecated) * Write/Edit: write_file to create or overwrite; edit_file for line-based edits with diff output and dry-run support * Directory operations: create_directory, list_directory, list_directory_with_sizes (sortable), directory_tree (recursive JSON tree), list_allowed_directories * File management: move_file to move or rename; search_files with glob patterns; get_file_info for size, timestamps, and permissions Security & Observability (mcp-audit proxy layer) * Audit trails: All tool calls, resource reads, and JSON-RPC methods are logged as signed JSONL or SQLite entries * Data redaction: Sensitive fields are automatically redacted before storage * Policy enforcement: Synchronous allow/deny policies can block specific tools (e.g., destructive operations), with per-tool rate limiting * Monitoring: A local read-only dashboard shows recent audit entries, top tools, and error rates; Prometheus metrics are exposed for external monitoring

mcp-audit

by P4ST4S

Overview Schema Source Related Servers Score Discussions Admin

Hybrid

mcp-audit

codecov mcp-audit MCP server License Status GitHub Discussions

A drop-in security and observability proxy for MCP servers. mcp-audit sits between an MCP client and any upstream MCP server to produce signed audit trails, redact sensitive payloads, enforce allow/deny policies and per-tool rate limits, and expose a local read-only dashboard.

For a contributor-oriented map of the runtime, package boundaries, concurrency model, and design invariants, see ARCHITECTURE.md.

Why mcp-audit?

The MCP 2026 roadmap calls out enterprise needs around audit trails, gateway patterns, and operational visibility. mcp-audit fills that gap as a deployable sidecar or local wrapper: it sits between any MCP client and server, preserves protocol traffic, and records signed audit entries for tool calls, resource reads, prompt requests, and all other JSON-RPC methods.

+-------------+    JSON-RPC / MCP     +-----------+      JSON-RPC / MCP     +-------------+
| MCP client  | <-------------------> | mcp-audit | <---------------------> | MCP server  |
+-------------+                       +-----------+                         +-------------+
                                            |
                                            v
                                JSONL or SQLite audit log
                                            |
                                            v
                                   Read-only dashboard

Related MCP server: GitHub MCP Server Plus

What This Is / Is Not

mcp-audit is not a domain-specific MCP server. It is a transparent security and observability proxy that wraps any MCP server and audits the JSON-RPC traffic passing through it.

Directories may show the tools exposed by the upstream server, not tools implemented by mcp-audit itself.

Supported Transports

stdio for local MCP clients such as Claude Desktop
http for MCP servers exposed over HTTP

HTTP upstreams can use custom CA bundles, TLS server name overrides, and optional mTLS client certificates. Upstream retries are disabled by default and only apply to conservative, idempotent JSON-RPC methods when enabled; tools/call is not retried.

Use Cases

Audit tool calls made by AI agents in regulated environments
Detect unexpected or dangerous MCP tool usage
Keep signed JSONL or SQLite logs for incident review
Redact sensitive fields before storing requests and responses
Block disallowed tools and apply per-tool rate limits without modifying the upstream MCP server

Demo

mcp-audit demo

Install

For detailed platform-specific instructions and troubleshooting, see INSTALL.md.

Download the latest prebuilt binary and run:

# Linux/macOS: resolve latest, download, verify it starts
version=$(curl -fsSL https://api.github.com/repos/P4ST4S/mcp-audit/releases/latest \
  | grep '"tag_name"' | head -n1 | cut -d'"' -f4 | sed 's/^v//')
os=$(uname | tr '[:upper:]' '[:lower:]')
arch=$(uname -m); [ "$arch" = "x86_64" ] && arch=amd64 || arch=arm64
base="https://github.com/P4ST4S/mcp-audit/releases/download/v${version}"
archive="mcp-audit_${version}_${os}_${arch}.tar.gz"
curl -L -o "${archive}" "${base}/${archive}"
tar -xzf "${archive}"
./mcp-audit --version

Run with Docker:

docker run --rm ghcr.io/p4st4s/mcp-audit:latest --version

Install from source with Go:

go install github.com/P4ST4S/mcp-audit/cmd/mcp-audit@latest

To pin a specific release for reproducible installs, see INSTALL.md.

Quick Start

Run in stdio mode:

AUDIT_SECRET="$(openssl rand -hex 32)" \
mcp-audit --transport stdio --upstream "npx @modelcontextprotocol/server-filesystem /tmp"

On Windows PowerShell, generate the secret and set it as an environment variable:

$env:AUDIT_SECRET = -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
.\mcp-audit.exe --transport stdio --upstream "npx @modelcontextprotocol/server-filesystem C:\Temp"

Run in HTTP mode:

mcp-audit --transport http --upstream http://localhost:8080 --port 4422

Run with Docker Compose:

docker compose up --build

The dashboard is available at http://127.0.0.1:9090 by default. Prometheus metrics are available at http://localhost:9091/metrics by default.

Examples

Configuration

mcp-audit loads config.yaml from the current directory by default. CLI flags override config values, and AUDIT_SECRET overrides audit.secret.

Key	Default	Description
`proxy.transport`	`stdio`	Proxy transport: `stdio` or `http`.
`proxy.upstream`	required	Stdio command or HTTP upstream URL.
`proxy.port`	`4422`	HTTP listen port.
`proxy.upstream_timeout_ms`	`30000`	HTTP upstream request timeout in milliseconds.
`proxy.forward_headers`	empty	Request headers allowed to bypass the default upstream strip list. Use `["Authorization"]` only when the upstream MCP HTTP server requires bearer-token auth.
`proxy.tls.ca_file`	empty	Optional CA bundle used to verify an HTTPS upstream MCP server.
`proxy.tls.server_name`	empty	Optional TLS server name override for the upstream MCP server.
`proxy.tls.insecure_skip_verify`	`false`	Skip upstream TLS certificate verification. Intended only for local testing.
`proxy.tls.client_cert_file`	empty	Optional client certificate for upstream mTLS. Must be configured with `proxy.tls.client_key_file`.
`proxy.tls.client_key_file`	empty	Optional client key for upstream mTLS. Must be configured with `proxy.tls.client_cert_file`.
`proxy.retry.max_retries`	`0`	Maximum conservative retry attempts for safe HTTP upstream requests. Off by default.
`proxy.retry.initial_interval_ms`	`200`	Initial upstream retry backoff.
`proxy.retry.max_interval_ms`	`2000`	Maximum upstream retry backoff.
`proxy.client_id`	`claude-desktop`	Client identifier written to audit entries.
`proxy.server_id`	`filesystem`	Server identifier written to audit entries.
`audit.storage`	`jsonl`	Storage backend: `jsonl` or `sqlite`.
`audit.path`	`./audit.jsonl`	JSONL audit log path.
`audit.sqlite_path`	`./audit.db`	SQLite database path.
`audit.sign`	`true`	Enable HMAC-SHA256 signatures when a secret is set.
`audit.secret`	empty	HMAC secret. Prefer `AUDIT_SECRET`.
`audit.async.enabled`	`false`	Enable asynchronous batched audit writes through a bounded ring buffer.
`audit.async.queue_size`	`4096`	Maximum queued audit entries before backpressure blocks writers.
`audit.async.batch_size`	`128`	Maximum entries written per storage batch.
`audit.async.flush_interval_ms`	`1000`	Maximum time before a partial batch is flushed.
`audit.rotation.max_size_bytes`	`0`	Maximum active JSONL file size before archive rotation. `0` disables built-in rotation.
`audit.rotation.max_files`	`0`	Maximum number of rotated JSONL archives to keep. `0` disables retention.
`audit.rotation.interval`	empty	Optional time-based JSONL rotation interval: `hourly` or `daily`. Empty disables time-based rotation.
`audit.rotation.max_age_days`	`0`	Delete JSONL archives whose filename rotation timestamp is older than this many days. `0` disables age retention.
`middleware.rate_limit.enabled`	`true`	Enable per-client, per-tool token buckets.
`middleware.rate_limit.requests_per_minute`	`60`	Allowed requests per minute per `(client_id, tool_name)`.
`middleware.redact.enabled`	`true`	Enable JSON key-based PII redaction.
`middleware.redact.patterns`	sensitive keys	Case-insensitive key fragments to redact.
`policy.enabled`	`false`	Enable synchronous allow/deny policy checks for `tools/call`.
`policy.default_action`	`allow`	Fallback action when no policy rule matches: `allow` or `deny`.
`policy.rules`	empty	Ordered first-match allow/deny rules for tool calls.
`dashboard.enabled`	`true`	Serve the dashboard.
`dashboard.bind_address`	`127.0.0.1`	Dashboard listen address. Set explicitly, for example to `0.0.0.0`, only when the dashboard is protected by network controls or auth.
`dashboard.port`	`9090`	Dashboard listen port.
`dashboard.auth.token`	empty	Optional bearer token required as `Authorization: Bearer <token>` for dashboard HTML and API requests.
`metrics.enabled`	`true`	Serve Prometheus metrics on a separate HTTP endpoint.
`metrics.port`	`9091`	Metrics listen port.
`metrics.path`	`/metrics`	Metrics HTTP path.
`metrics.include_go_metrics`	`true`	Include Go runtime metrics.
`metrics.include_process_metrics`	`true`	Include process metrics.
`metrics.tool_labels`	`true`	Include `tool_name` and `client_id` labels for tool-level metrics. Disable to minimize label cardinality.
`otel.enabled`	`false`	Export `tools/call` audit entries as OTLP/HTTP JSON spans.
`otel.endpoint`	`http://localhost:4318`	OTLP HTTP endpoint base URL. `/v1/traces` is appended automatically.
`otel.service_name`	`mcp-audit`	OpenTelemetry `service.name` resource attribute.
`otel.headers`	empty	Additional OTLP HTTP headers, for example `Authorization` or API key headers.
`otel.tls.ca_file`	empty	Optional CA bundle used to verify the OTLP endpoint.
`otel.tls.server_name`	empty	Optional TLS server name override.
`otel.tls.insecure_skip_verify`	`false`	Skip OTLP TLS certificate verification. Intended only for local testing.
`otel.retry.max_retries`	`3`	Maximum OTLP retry attempts after a failed export request.
`otel.retry.initial_interval_ms`	`200`	Initial OTLP retry backoff.
`otel.retry.max_interval_ms`	`2000`	Maximum OTLP retry backoff.
`otel.queue_size`	`1024`	Maximum queued audit entries before trace exports are dropped.
`otel.batch_size`	`64`	Maximum spans per OTLP export request.
`otel.flush_interval_ms`	`1000`	Maximum time before a partial OTLP batch is exported.
`otel.timeout_ms`	`5000`	OTLP HTTP request timeout.

By default, mcp-audit strips hop-by-hop request headers and Authorization before forwarding HTTP requests to the upstream. To pass a bearer token to a trusted authenticated upstream, opt in explicitly:

proxy:
  forward_headers:
    - Authorization

Security note: forwarded headers, including secrets like bearer tokens, are transmitted verbatim to the upstream server. Only enable this if you control or trust the upstream MCP server. Authorization is the only sensitive header that can be opt-in forwarded because some MCP HTTP servers require it for upstream authentication. Cookie, Set-Cookie, and Proxy-Authorization are always rejected: they represent state destined for other components such as browser sessions or proxy chains and have no legitimate use in MCP request forwarding. If an existing deployment relied on implicit Authorization forwarding, add the config above.

JSONL rotation is disabled by default and supports size-based and UTC time-based triggers. Rotated archives use UTC timestamps such as audit.jsonl.20260610T214605Z; if multiple rotations happen in the same second, numeric suffixes are added. The archive timestamp reflects the wall-clock time of the rotation event, not the cutoff that was crossed. Time-based rotation is append-driven: mcp-audit does not start a background timer, so if no writes occur for several days, the active file is not rotated until the next append after the cutoff. Missed cutoffs are not caught up; the next append creates at most one archive.

audit:
  storage: jsonl
  rotation:
    max_size_bytes: 104857600
    interval: daily
    max_files: 10
    max_age_days: 30

max_age_days uses the rotation timestamp encoded in the archive filename. This means age since rotation, not the age of the oldest entry inside the archive. Age retention runs before max_files retention. Compression and SQLite archival are not part of this release.

CLI flags:

--transport    stdio | http
--upstream     upstream server command or URL
--port         proxy port for http mode
--upstream-timeout upstream HTTP request timeout in milliseconds
--config       path to config.yaml
--storage      jsonl | sqlite
--no-dashboard disable the web dashboard
--no-metrics   disable Prometheus metrics
--version      print version and exit
--log-level    debug | info | warn | error

Claude Desktop

Configure Claude Desktop to spawn mcp-audit instead of the upstream MCP server:

{
  "mcpServers": {
    "filesystem-audited": {
      "command": "mcp-audit",
      "args": [
        "--transport",
        "stdio",
        "--upstream",
        "npx @modelcontextprotocol/server-filesystem /tmp"
      ],
      "env": {
        "AUDIT_SECRET": "replace-with-a-long-random-secret"
      }
    }
  }
}

Dashboard

The dashboard shows recent entries, filters, expandable request/result JSON, top tools, calls today, and error rate. It refreshes every five seconds.

By default the dashboard listens only on 127.0.0.1:9090. To expose it on another interface, configure dashboard.bind_address explicitly and enable authentication or place it behind a trusted access proxy.

dashboard:
  enabled: true
  bind_address: 127.0.0.1
  port: 9090
  auth:
    token: "replace-with-a-long-random-token"

When dashboard.auth.token is configured, requests to /, /api/entries, and /api/stats must include:

Authorization: Bearer replace-with-a-long-random-token

Missing or invalid credentials return 401 Unauthorized with WWW-Authenticate: Bearer realm="mcp-audit-dashboard". Repeated failed authentication attempts from the same remote address are throttled with 429 Too Many Requests.

Dashboard JSON API responses include Cache-Control: no-store so intermediaries and browsers do not retain audit payloads.

Prometheus Metrics

mcp-audit exposes Prometheus metrics on a separate endpoint so platform teams can scrape operational data without exposing the dashboard.

scrape_configs:
  - job_name: mcp-audit
    static_configs:
      - targets: ["localhost:9091"]

Application metrics use the mcp_audit_ prefix and avoid unbounded labels. Tool-level labels can be disabled with metrics.tool_labels: false for stricter cardinality control. Policy decisions are exposed as mcp_audit_policy_decisions_total{action="allow|deny"}.

For a ready-made Prometheus + Grafana stack, see examples/docker-compose-observability.

Policy Engine

mcp-audit can enforce synchronous allow/deny rules before a tools/call reaches the upstream MCP server. Denied calls return a JSON-RPC error and are still written to the audit log.

policy:
  enabled: true
  default_action: allow
  rules:
    - action: deny
      client_id: claude-desktop
      server_id: filesystem
      tool_name: delete_file
      reason: "Destructive filesystem operations are blocked"

Rules are evaluated in order. Empty fields and * match any value, so default_action: deny can be used with explicit allow rules for stricter deployments.

OpenTelemetry

mcp-audit can export tools/call audit entries as OTLP/HTTP JSON spans to Jaeger, Tempo, Honeycomb, or any OTLP-compatible collector.

otel:
  enabled: true
  endpoint: "http://localhost:4318"
  service_name: "mcp-audit"
  headers:
    Authorization: "Bearer your-token"
  timeout_ms: 5000
  retry:
    max_retries: 3
    initial_interval_ms: 200
    max_interval_ms: 2000

The exporter uses current OpenTelemetry MCP and GenAI semantic conventions where possible, including mcp.method.name, jsonrpc.request.id, gen_ai.operation.name, gen_ai.tool.name, network.transport, network.protocol.name, rpc.response.status_code, and error.type. Project-specific attributes are kept link-oriented, such as mcp_audit.entry_id, mcp_audit.direction, mcp_audit.client_id, mcp_audit.server_id, mcp_audit.storage, and mcp_audit.signature.present.

Request params and tool results are not exported to spans by default. The signed JSONL or SQLite audit row remains the evidence artifact; OTLP provides correlation, latency, and operational visibility.

Exporter health is visible through Prometheus metrics under the mcp_audit_otel_ prefix, including export requests, span outcomes, dropped spans, queue depth, and queue capacity. Temporary OTLP failures are retried with bounded exponential backoff; Retry-After is honored for retryable responses up to otel.retry.max_interval_ms.

Audit Entries

Each stored entry includes a ULID, timestamp, direction, transport, JSON-RPC method, tool name when present, redacted params/result, JSON-RPC error when present, duration, client/server identifiers, and an optional HMAC-SHA256 signature.

Example JSONL entry:

{
  "id": "01HY8G6Y8S6W9K6ZD7VJ4Q8X4R",
  "timestamp": "2026-05-25T12:34:56Z",
  "direction": "client_to_server",
  "transport": "stdio",
  "method": "tools/call",
  "tool_name": "read_file",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/tmp/example.txt",
      "token": "[REDACTED]"
    }
  },
  "duration_ms": 18,
  "client_id": "claude-desktop",
  "server_id": "filesystem",
  "signature": "hmac-sha256:..."
}

The signature covers:

id + timestamp + method + tool_name + raw_params

Roadmap

SIEM-friendly exports
OTLP compression and trace context propagation

Contributing

Keep changes small, run go build ./... and go vet ./..., and prefer standard library behavior over new dependencies. Stability guarantees are documented in STABILITY.md.

See CONTRIBUTING.md for setup, PR expectations, and project principles. See CHANGELOG.md for release history.

Community

Discussions: questions, ideas, and design conversations
Issues: bug reports and concrete feature requests
Security: see SECURITY.md for the private vulnerability reporting process

License

Apache-2.0. See LICENSE.

Available Tools

14 tools

create_directoryCreate DirectoryA

Idempotent

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.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant behavioral details beyond annotations: nested directory creation, silent success on existing directory, and workspace restrictions. Annotations only say idempotent and not read-only, so description enriches understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: 5 sentences, front-loaded with action, no redundant words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, idempotent, non-destructive), the description covers all necessary aspects: purpose, behavior, usage example, and constraints. Output schema exists, so return value details are not needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to the 'path' parameter by implying support for nested paths and scoping to allowed directories. With 0% schema coverage, this is helpful, though more specifics on path format would be ideal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates new directories or ensures they exist, using specific verbs and resource. It distinguishes from sibling tools focused on files by explicitly mentioning directory creation and structure setup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for use ('setting up directory structures', 'ensuring required paths exist') and includes a constraint ('only works within allowed directories'). However, it does not explicitly name alternatives or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

directory_treeDirectory TreeA

Read-only

Get a recursive tree view of files and directories as a JSON structure. Each entry includes 'name', 'type' (file/directory), and 'children' for directories. Files have no children array, while directories always have a children array (which may be empty). The output is formatted with 2-space indentation for readability. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`excludePatterns`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral details beyond the 'readOnlyHint' annotation, including the recursive nature, entry structure (name, type, children), formatting (2-space indentation), and the constraint of working only within allowed directories. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with the main purpose, and every sentence adds value. No unnecessary words or repetition, making it concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema covering return values, the description is mostly complete, explaining output structure and formatting. However, it misses details about the 'excludePatterns' parameter, which is a minor gap. No discussion of depth limits or performance, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for parameters. The tool description does not explain the 'excludePatterns' parameter, leaving its purpose and usage unclear. While 'path' is inferred, the lack of compensation for low schema coverage results in poor parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool gets a recursive tree view of files and directories as a JSON structure, specifying the verb, resource, and output format. It distinguishes itself from siblings like 'list_directory' (flat list) and 'search_files' (search), providing a specific and helpful purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives like 'list_directory' for flat listing or 'search_files' for search. It mentions 'Only works within allowed directories' but provides no explicit when-not or alternative guidance, leaving usage context clear but incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_fileEdit FileA

Destructive

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.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`edits`	Yes
`dryRun`	No	Preview changes using git-style diff format

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already set destructiveHint=true, so the editing nature is known. Description adds that edits replace exact line sequences (preserving unmatched lines), returns a git-style diff, and works only in allowed directories. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each serving a distinct purpose: what it does (line-based edits), how output is returned (diff), and constraints (allowed directories). No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given annotations (destructiveHint=true) and output schema (present), the description provides enough context for an agent to understand functionality, output, and constraints. Could mention return type or more about the edit array structure, but adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (33%), with only dryRun having a description. Description explains that 'oldText' must match exactly (implying substring replacement) and that dryRun previews changes as a git-style diff, but does not detail parameter formats or constraints beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'edit', resource 'text file', and mechanism 'line-based replacements of exact line sequences with new content'. Distinguishes from siblings like write_file (whole file overwrite) by emphasizing line-based edits and returning a git-style diff.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States 'Only works within allowed directories' but does not explicitly guide when to use edit_file versus alternatives like write_file or read_file. No exclusion criteria or context for 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.

get_file_infoGet File InfoA

Read-only

Retrieve detailed metadata about a file or directory. Returns comprehensive information including size, creation time, last modified time, permissions, and type. This tool is perfect for understanding file characteristics without reading the actual content. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, indicating no destructive side effects. The description adds context about what metadata is returned (size, times, permissions, type) and the allowed directories constraint, going beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, no extraneous information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description explains return fields and restrictions. With an output schema present (indicated), the description does not need to detail return structure. However, it could hint at required nature of path.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not add meaning to the sole 'path' parameter. With a simple string parameter, more guidance on format or constraints would be helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Retrieve' and the resource 'detailed metadata about a file or directory', distinguishing it from sibling tools like read_file which read content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'perfect for understanding file characteristics without reading actual content' and notes restrictions ('Only works within allowed directories'). It does not explicitly mention when not to use or specific alternatives, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_allowed_directoriesList Allowed DirectoriesA

Read-only

Returns the list of directories that this server is allowed to access. Subdirectories within these allowed directories are also accessible. Use this to understand which directories and their nested paths are available before trying to access files.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description aligns with the readOnlyHint annotation and adds context about subdirectory accessibility. It does not contradict annotations and provides useful behavioral context beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words. The first sentence immediately states the primary purpose, making it easy for an agent to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with zero parameters and an output schema, the description fully covers what the tool does, what it returns, and when to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description does not need to add parameter details; baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it returns the list of directories the server is allowed to access, with subdirectories. This verb+resource combination distinguishes it from siblings like 'list_directory' which lists contents of a specific directory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using this tool before trying to access files to understand available directories. It implies a prerequisite role, though it does not mention when not to use it or alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directoryList DirectoryA

Read-only

Get a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is essential for understanding directory structure and finding specific files within a directory. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, and the description adds concrete behavioral traits: results are prefixed with [FILE] and [DIR], and it only works within allowed directories. This goes beyond the annotation to inform the agent about output format and scope. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each adding value: the first states the core function, the second explains output format, the third gives use case and constraint. Efficient and front-loaded, though it could be slightly tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity (1 param, output schema exists, annotations present), the description covers the key aspects: purpose, output format, constraint, and use case. It is complete enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'specified path' but provides no additional detail on format, relative vs absolute, or constraints beyond 'allowed directories'. This is adequate but minimal—the agent would benefit from more specific parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get a detailed listing of all files and directories' with a specific verb and resource. It distinguishes from siblings by mentioning the [FILE] and [DIR] prefixes and calls itself 'essential for understanding directory structure', setting it apart from tools like directory_tree or search_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context by stating 'essential for understanding directory structure and finding specific files within a directory'. Also mentions constraint 'Only works within allowed directories'. However, it does not explicitly exclude alternatives or provide when-not guidance, missing a chance to differentiate from siblings like directory_tree or list_allowed_directories.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directory_with_sizesList Directory with SizesA

Read-only

Get a detailed listing of all files and directories in a specified path, including sizes. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is useful for understanding directory structure and finding specific files within a directory. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`sortBy`	No	Sort entries by name or size	name

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. The description adds behavioral details: results prefix [FILE] and [DIR], and the constraint 'Only works within allowed directories.' No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each adding distinct value: purpose, distinguishing feature, and usage scope. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, an output schema exists to document return values. The description covers purpose, constraint, and distinct formatting. Could mention error handling for invalid paths, but adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (path has no description). The description mentions 'specified path' but doesn't explain the sortBy parameter at all. It adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides a detailed listing of files and directories with sizes, and distinguishes results with [FILE] and [DIR] prefixes. This differentiates it from sibling tools like list_directory (no sizes) and get_file_info (single file).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says it is 'useful for understanding directory structure and finding specific files,' which implies usage but does not explicitly state when to use this tool over alternatives or when not to use it. Missing exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_fileMove FileA

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.

ParametersJSON Schema

Name	Required	Description	Default
`source`	Yes
`destination`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral detail beyond annotations (readOnlyHint=false, etc.), such as failure on existing destination and cross-directory capability. It does not contradict annotations and provides useful operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with the primary action, no redundant wording. Every sentence adds value about operation, constraints, or scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderately complex operation (move/rename with failure conditions), the description covers purpose, constraints, and scope. Output schema is present, so lack of return value detail is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining that source and destination are file paths within allowed directories, adding meaning about their roles and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it moves or renames files/directories, specifies it can do both in one operation, and distinguishes from sibling tools like copy or write by noting failure if destination exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use (move/rename) and conditions (destination must not exist, both paths in allowed directories). It lacks explicit comparison to alternatives but provides sufficient context for typical use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileRead File (Deprecated)A

Read-only

Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`tail`	No	If provided, returns only the last N lines of the file
`head`	No	If provided, returns only the first N lines of the file

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true. The description adds deprecation context but does not mention the head/tail parameters that modify behavior (partial reads). This gap leaves behavior partially undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: two sentences front-load purpose and deprecation. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has three parameters and an output schema, the description is adequate for basic understanding but lacks detail on how head/tail affect output. The deprecation is the main extra value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (path lacks description). The description adds no parameter-specific meaning; path remains undocumented, and head/tail descriptions from schema are not reinforced or elaborated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool reads file contents as text and explicitly notes deprecation with a sibling alternative. The verb 'read' and resource 'file as text' are specific, and the deprecation distinguishes it from read_text_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'DEPRECATED: Use read_text_file instead', providing clear guidance on when not to use this tool and directing to the preferred alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_media_fileRead Media FileC

Read-only

Read an image or audio file. Returns the base64 encoded data and MIME type. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, so the description's addition of returning base64 data and MIME type and directory restriction adds context beyond annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, front-loaded with the core purpose. Efficiently conveys essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple with one parameter and an output schema. Description covers allowed directories and return format but lacks details on error behavior, supported MIME types, or file size limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'path' parameter's format, constraints, or expected input, leaving the agent without semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'read' and resource 'image or audio file', and specifies return of base64 data and MIME type. However, it does not explicitly distinguish from sibling read_file, which may cause confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Only mentions an access constraint ('only works within allowed directories') but provides no guidance on when to use this tool versus similar siblings like read_file or read_text_file.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_multiple_filesRead Multiple FilesA

Read-only

Read the contents of multiple files simultaneously. This is more efficient than reading files one by one when you need to analyze or compare multiple files. Each file's content is returned with its path as a reference. Failed reads for individual files won't stop the entire operation. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`paths`	Yes	Array of file paths to read. Each path must be a string pointing to a valid file within allowed directories.

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, it reveals that individual file failures won't abort the operation, and the directory restriction. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy. First sentence states core purpose, second adds efficiency and behavioral details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity, annotations, and output schema presence, the description provides necessary behavioral and return context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description adds that return includes file path as reference and partial failure behavior, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads multiple files simultaneously, which distinguishes it from sibling 'read_file' that reads single files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It highlights efficiency for analyzing or comparing multiple files, implying when to use this over single-file reads. It mentions allowed directories constraint but lacks explicit exclusions or alternative naming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_text_fileRead Text FileA

Read-only

Read the complete contents of a file from the file system as text. Handles various text encodings and provides detailed error messages if the file cannot be read. Use this tool when you need to examine the contents of a single file. Use the 'head' parameter to read only the first N lines of a file, or the 'tail' parameter to read only the last N lines of a file. Operates on the file as text regardless of extension. Only works within allowed directories.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`tail`	No	If provided, returns only the last N lines of the file
`head`	No	If provided, returns only the first N lines of the file

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, and the description adds that it provides detailed error messages, handles various encodings, operates on text regardless of extension, and only works within allowed directories, exceeding what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the main purpose, and each sentence adds value: first on core function, second on error handling, third on usage. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with output schema, the description covers reading behavior, encodings, error messages, directory restrictions, and partial reading options. It's fully adequate for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (head/tail described; path missing). The description adds usage guidance for head/tail but doesn't significantly enhance parameter meaning beyond the schema. Path parameter lacks detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads a file's complete contents as text, distinguishing it from siblings like 'read_media_file' (media) and 'read_multiple_files' (multiple files). It specifies handling encodings and error messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use when examining a single file and explains partial reading via head/tail parameters. It lacks a 'when not to use' section but provides clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_filesSearch FilesA

Read-only

Recursively search for files and directories matching a pattern. The patterns should be glob-style patterns that match paths relative to the working directory. Use pattern like '.ext' to match files in current directory, and '**/.ext' to match files in all subdirectories. Returns full paths to all matching items. Great for finding files when you don't know their exact location. Only searches within allowed directories.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`pattern`	Yes
`excludePatterns`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, confirming no mutation. The description adds useful behavioral details: recursive search, returns full paths, and works with glob patterns relative to the working directory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with main purpose, and includes examples without excessive verbosity. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and annotations cover read-only behavior, the description adequately explains search behavior, pattern syntax, process, and scope ('allowed directories'). Slight gap on excludePatterns, but overall complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains pattern syntax and scope but does not explicitly describe the 'path' parameter (only implies working directory context) and does not mention 'excludePatterns'. Partial but not fully comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Recursively search for files and directories matching a pattern' with specific verb and resource. It includes examples of glob patterns, and the purpose is distinct from sibling tools like list_directory or read_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context for when to use ('Great for finding files when you don't know their exact location') and mentions scope ('Only searches within allowed directories'), but does not explicitly state when not to use or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_fileWrite FileA

DestructiveIdempotent

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.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`content`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`content`	Yes

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true), description adds that it overwrites without warning and handles text encoding, providing useful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, each adding essential information: purpose, caution, and encoding/directory constraint. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks details on error handling (e.g., missing directory, invalid path) and prerequisites. With no parameter descriptions, agent may struggle to construct correct invocations despite output schema existing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage for parameters. Description does not clarify expected format for 'path' or 'content' (e.g., relative vs absolute, size limits, encoding specifics), leaving the agent to infer from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Create a new file or completely overwrite an existing file' – a specific verb and resource. Distinguishes from siblings like edit_file (which modifies partially) and read_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes a caution about overwriting and a directory restriction, but does not explicitly contrast with siblings like edit_file for partial modifications. Lacks guidance on when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

14 tool updatesv0.1.0May 25, 2026
- First observedcreate_directory
- First observeddirectory_tree
- First observededit_file
- First observedget_file_info
- First observedlist_allowed_directories
- First observedlist_directory
- First observedlist_directory_with_sizes
- First observedmove_file
- First observedread_file
- First observedread_media_file
- First observedread_multiple_files
- First observedread_text_file
- First observedsearch_files
- First observedwrite_file

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Scored 2026-09-09 18:46 across 14 tools

Disambiguation2/5

read_file is a deprecated duplicate of read_text_file, and list_directory/list_directory_with_sizes/directory_tree all provide overlapping directory listings. Most other tools are distinct, but these boundary cases create real selection ambiguity for agents.

Naming Consistency4/5

Tool names overwhelmingly follow a snake_case verb_noun pattern like read_, write_, edit_, list_, move_, search_, and get_. Minor deviations are directory_tree lacking a verb and the deprecated read_file alongside read_text_file, but overall the naming is predictable.

Tool Count4/5

14 tools is within a reasonable scope for a filesystem server, but the set is slightly padded by the deprecated read_file and the near-duplicate list_directory_with_sizes. Removing or merging those would make the count feel tighter without losing functionality.

Completeness2/5

The server covers reading, writing, editing, moving, searching, and listing, but has no delete_file, delete_directory, or copy operation. Since write and edit are present, the lack of delete and copy leaves significant file-management dead ends for agents.

Maintenance

ActivityStale

ResponsivenessResponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

agent-audit-logger-mcp
io.github.CSOAI-ORG
Hash-chained HMAC-signed audit log MCP for A2A (agent-to-agent) calls. Every tool-call, agent-ha...
Security Observability
2
Occludra — MCP Gateway (AI Security Gateway)
ai.occludra
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Security Agent Orchestration
1
MANDATE Credential Broker B
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security
111
clianythingharness-mcp
com.clauxel.clianythingharness
A paid remote MCP for CLI tool MCP, built to return verdicts, receipts, usage logs, and audit-ready
Command Line Monitoring
21

Related MCP Servers

Filesystem MCP Serverofficial
File Systems Developer Tools
modelcontextprotocol
A
license
A
quality
A
maintenance
Node.js server implementing Model Context Protocol (MCP) for filesystem operations.
Updated 8 days ago (2026-09-03 01:42 UTC)
2
14
954,129
90,196
-
GitHub MCP Server Plus
Version Control Developer Tools
PhialsBasement
A
license
B
quality
D
maintenance
MCP Server for the GitHub API, providing features for file operations, repository management, and advanced search, with automatic branch creation and comprehensive error handling.
Updated a year ago (2025-05-05 10:31 UTC)
18
9
8
MIT
Postgres MCP
Databases Developer Tools Code Execution
crystaldba
A
license
A
quality
D
maintenance
Postgres Pro is an open source Model Context Protocol (MCP) server built to support you and your AI agents throughout the entire development process—from initial coding, through testing and deployment, and to production tuning and maintenance.
Updated 25 days ago (2026-08-17 05:06 UTC)
9
3,260
MIT
Brave Search MCP Serverofficial
Research & Data Search Text Summarization
brave
A
license
A
quality
A
maintenance
An MCP implementation that integrates the Brave Search API, providing comprehensive search capabilities including web, local business, image, video, news searches, and AI-powered summarization.
Updated 11 hours ago (2026-09-10 16:48 UTC)
8
7,679
1,434
MIT

mcp-audit

Why mcp-audit?

What This Is / Is Not

Supported Transports

Use Cases

Demo

Install

Quick Start

Examples

Configuration

Claude Desktop

Dashboard

Prometheus Metrics

Policy Engine

OpenTelemetry

Audit Entries

Roadmap

Contributing

Community

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Filesystem MCP Serverofficial

Brave Search MCP Serverofficial