Skip to main content
Glama
Sign In
deenesjakoruzh
agent-tool

agent-tool

by knewstimek
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

agent-tool

한국어

MCP (Model Context Protocol) tool server for AI coding agents.

Why?

Built-in tools in AI coding agents (Claude Code, Cursor, Codex, etc.) have known limitations:

  • Tab indentation breaks: LLMs output spaces, but your project uses tabs. The built-in Edit tool writes spaces as-is, corrupting your indentation style.

  • Encoding corruption: Editing EUC-KR, Shift-JIS, or GB18030 files silently converts them to UTF-8, breaking legacy projects.

  • Too many separate tools: Making the agent find, install, and configure Redis CLI, MySQL client, SSH client, etc. is tedious and error-prone. agent-tool bundles 40 tools into one binary and exposes them on demand through compact profiles.

  • No reverse engineering support: Built-in tools can't disassemble binaries, inspect PE/ELF headers, find function boundaries, or search cross-references. agent-tool includes static binary analysis (disassembly, decompilation to C with PDB/DWARF types, xref, function detection), a DAP debugger, and CheatEngine-style memory tools -- giving your agent full reverse engineering capabilities.

  • Network censorship: In some countries, government-level web filtering breaks plain curl/wget requests. agent-tool uses ECH (Encrypted Client Hello) and DoH (DNS over HTTPS) by default to work around these restrictions.

agent-tool solves these with agent-oriented tools that preserve project conventions while keeping model context bounded.

Related MCP server: DevToolkit MCP Server

Supported Agents

Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, and any MCP-compatible agent.

LLM-efficient by default

The default core profile exposes only 11 schemas (including toolbox) instead of all 40. In a protocol-level measurement this reduced the serialized tool list from about 74 KB (full) to 15 KB. For the smallest steady-state context, start with --profile core-lite; its five schemas are about 6.4 KB and expose only read, write, edit, grep, and toolbox. Use toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute") to load only one operation's fields and required list, then invoke it through toolbox(operation="call", tool="ssh", arguments={...}). The gateway does not depend on dynamic tool-list refresh, so it works with fixed-binding clients such as Codex. Describe returns a tool/version-bound schema_handle; sending it on a later describe returns a short unchanged acknowledgement when the schema is still current. Common compact operations include SSH execution, MySQL queries, file copy, Windows screenshots/clipboard images, and static-analysis operations. You can also start with --profile core-lite|coding|remote|analysis|full.

Potentially large text responses default to 32K characters with a 128K hard ceiling. Truncation is always visible and pageable tools return next_offset or next_cursor. Local relative paths resolve against an explicit workspace, then the MCP client root.

Features

Tool

Description

Status

Edit

String replacement with smart indentation and encoding preservation (supports dry_run)

✅

Read

Encoding-aware, line-numbered reading. Defaults to 400 lines/32K chars, reports truncation and exact next_offset, safely handles very long lines, optional SHA-256. Flexible offset and MCP ImageContent support

✅

Write

Encoding-aware file creation/overwrite

✅

Grep

Encoding-aware regex search with 32K output budget, compact file-grouped output, relative paths, .gitignore/.ignore/generated-directory filtering, binary detection, output modes/context, and deterministic next_cursor paging without repeated matches

✅

Glob

Sorted, bounded file matching with **, relative paths, .gitignore/.ignore/generated-directory filtering, explicit has_more, and deterministic cursor paging

✅

ListDir

Bounded/pageable directory listing. max_entries + continuation cursor, directory/file filters, entry-name glob filters, counts-only mode, flat/tree output

✅

Diff

Compare two files with unified diff output (encoding-aware). Files differing only in line endings or a trailing newline say so instead of returning an empty diff

✅

Patch

Apply unified diff patch to a file (supports dry_run). Each line keeps its own ending, so a mixed CRLF/LF file is not rewritten

✅

Checksum

Compute file hash (md5, sha1, sha256)

✅

FileInfo

File metadata (size, encoding, mixed line-ending counts, indentation, line count)

✅

ConvertEncoding

Convert file encoding (EUC-KR ↔ UTF-8, add/remove BOM, etc.)

✅

Delete

Safe file/directory deletion, including compact batches of up to 100 file_paths. Directories require recursive=true; protected roots, symlink blocking, bounded errors, and dry_run preview

✅

Rename

Atomic file/directory rename or move (dry_run)

✅

ProcList

List running processes — PID, name, command line, memory. Sensitive args auto-masked. Filter by name or port

✅

ProcKill

Kill, suspend, or resume processes by PID or port. Tree kill, signal selection (kill/term/hup/int/stop/cont), zombie handling (Linux), dry_run

✅

ProcExec

Execute commands as new processes. Foreground/background/suspended start, timeout/env vars, and safe repeated-diagnostic compaction with expiring raw-output retrieval

✅

SSH

SSH execution with 32K head+tail capture, original byte counts, proper non-zero-exit errors, and background jobs (start/status/tail/cancel). Auth-aware pooling, host-key verification, ProxyJump, IPv6

✅

SSHKey

Convert local private keys between PuTTY PPK v3, traditional PEM, modern OpenSSH, and PKCS#8. Auto-detects input, supports encrypted PPK/OpenSSH output, writes mode 0600, and never returns key material

✅

SFTP

Transfer files and manage remote filesystems over SSH. Upload, download, ls, stat, mkdir, rm, chmod, rename. Reuses SSH session pool. Max 2 GB per transfer

✅

Bash

Persistent shell sessions with working directory/environment retention, safe repeated-diagnostic compaction, and expiring raw-output retrieval. Session pooling (max 5, idle timeout 30 min). Unix: bash/sh, Windows: PowerShell/git-bash/cmd

✅

Download

Download files from URLs to disk. ECH + DoH by default. SSRF protection. HTTP/SOCKS5 proxy. Atomic write. Max 2 GB

✅

HTTPReq

Execute HTTP requests with any method (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS). API testing with custom headers, body, proxy. SSRF protection

✅

Query

Read one value from a JSON, YAML or TOML file by dot-notation path (e.g. dependencies.react, services.web.ports[0], users[*].email); format from the extension or format. Saves tokens on large configs

✅

Copy

Copy files/directories with atomic write and permission preservation. Recursive directory copy. Windows locked-file fallback (renames running exe/DLL aside). dry_run preview

✅

Mkdir

Create directories with optional permission mode (octal, e.g. 0755). Recursive by default (mkdir -p). dry_run preview

✅

MultiRead

Read up to 50 files with a call-wide 32K budget, 200-line per-file default, long-line safety, and per-file/overall continuation metadata. Hashes are opt-in

✅

RegexReplace

Regex find-and-replace across files/directories. Encoding and line-ending preserving, capture groups ($1, $2). Skips binary files. dry_run preview

✅

NetCheck

Network diagnostics: external_ip (public IPv4/IPv6 with provider fallback), dns (A/AAAA/MX/CNAME/TXT/NS/SOA over DoH or the system resolver), tls (certificate subject, issuer, expiry, SANs, TLS version, cipher), port (TCP OPEN/CLOSED with response time)

✅

MySQL

Execute SQL queries on MySQL/MariaDB. Table-formatted SELECT results with configurable row/column/cell/total-output limits; affected rows for DML. Use SQL LIMIT/OFFSET for paging

✅

Redis

Execute Redis commands with formatted output by type. TLS support. Dangerous commands (FLUSHALL, SHUTDOWN, etc.) blocked

✅

SLOC

Count source lines of code per language. 70+ language detection, per-file/language breakdown, blank line stats, max_depth control

✅

Debug

Interactive debugger via DAP (Debug Adapter Protocol). Full DAP coverage with bounded values/output and paging for variables, completions, modules, and loaded sources. Tested with dlv (Go), debugpy (Python), codelldb (C/C++/Rust). Works with any DAP-compatible adapter. Stdio and TCP modes. Note: vsdbg (Microsoft) requires VS Code licensing and is not usable standalone — use codelldb or netcoredbg as open-source alternatives

✅

Analyze

Static binary analysis and reverse engineering. Decompilation of x86/x64 PE/ELF functions to C (Gosleigh, a Go port of Ghidra's decompiler core, run in an isolated worker process with time/memory limits); a matching PE PDB (built-in reader, no DIA SDK; pdb_force loads one whose GUID differs) or embedded DWARF is read automatically for function names, prototypes, struct/enum types, global data, bitfields and local variables (names and types) in decompilation (the structs/enums a function names are printed after it with member offsets and enum values; type_info prints any other by name), and for names and exact function bounds in disassemble, call_graph and function_at; MSVC decorated names are demangled; Go binaries use the Go ABI; non-returning functions are detected as in Ghidra; undecodable bytes end only their path (halt_baddata()); a runaway flow (junk-byte obfuscation, where Ghidra times out) is decompiled inside the function's x64 .pdata extent with each exit marked (halt_missing()), and assume_branches fixes conditional jumps a runtime trace resolved; agent-tool decompile-all dumps a whole binary to a JSONL corpus; x86/x64/ARM/ARM64 disassembly; semantic x86/x64 instruction search (mnemonic, register, immediate, memory displacement) with exhaustive executable-offset recovery, CFG confidence, function names, target/result filters, and parallel fixpoint register/stack/read-only constant tracing into ABI-aware calls and tail calls (stdcall argument cleanup modeled, read from the imported DLLs for x86 imports); PE/ELF/Mach-O parsing with bounded, pageable PE import output; xref to an address, the strings containing a text, or a struct field (Class::member, confirmed by decompiling), covering code, immediates and data pointers (vtable slots), each reference named by its containing function; function discovery/call graphs (function bounds without a PDB matched PDB bounds for 100% of addresses on a large x64 image, 99.5% on x86; callers through thunks and tail jumps, vtable references), pointer/RTTI/vtable/struct analysis, imphash, Rich header, DWARF, strings, hexdump, pattern search, entropy, overlay detection, and binary diff. No global file size limit

✅

Memtool

CheatEngine-style process memory tool — search/filter/read/write memory values, read_chain (resolve base+offset pointer chains, batched in one call), live disassembly (x86/x64/ARM/ARM64), undo, struct pattern search, pointer scan, memory diff. Disk-backed snapshots for large scans. Session management with idle timeout. Windows (ReadProcessMemory) and Linux (/proc/pid/mem). Windows auto-enables SeDebugPrivilege when elevated; opt-in force_dacl bypasses a same-user process's self-hardened DACL (original restored after)

✅

Wintool

Windows GUI automation — find/enumerate windows and child controls, capture screenshots (ImageContent PNG via PrintWindow), read clipboard images, read/set text, click, type, send raw messages, show/hide/minimize/maximize, move/resize, close, focus. screenshot/clipboard return ImageContent by default (save_path option for file output). Enables AI agents to "see" and interact with GUI applications. Windows only

✅

CodeGraph

Fully embedded semantic code graph: Go standard-library AST plus lazy compressed tree-sitter WASM for C/C++, Python, C#, Rust, and Java. Adds declaration/definition identity, return-chain and generic/alias propagation, transitive includes, calibrated overload evidence, virtual/interface dispatch, macro/callback edges, build-condition provenance, and multi-root workspaces. No compiler, language server, external binary, LLM call, or token cost

✅

SetConfig

Change runtime settings (encoding, file size limit, symlinks, workspace, etc.)

✅

Help

Built-in usage guide for agents (encoding, indentation, troubleshooting)

✅

Persistent analysis annotations

The existing analyze tool can save user comments and labels in SQLite with annotation_set, search/read them with annotation_list, and remove them with annotation_delete. Disassembly and decompilation load saved notes automatically. These are user assessments, visibly separate from automatic symbols and debug types; labels and subjects do not rename engine symbols or override inferred types.

{"operation":"annotation_set","file_path":"sample.exe","rva":"0x1234","subject":"rax","comment":"User pointer returned here","annotation_status":"hypothesis","annotations_path":"project.annotations.sqlite"}
{"operation":"disassemble","file_path":"sample.exe","va":"0x140001234","annotations_path":"project.annotations.sqlite"}
{"operation":"annotation_list","file_path":"sample.exe","query":"User","annotations_path":"project.annotations.sqlite"}

Call through toolbox (operation="call", tool="analyze", arguments={...}); use toolbox describe or help topic analyze for the full schema and examples.

  • annotations_path manually selects the SQLite file for saving and loading; relative paths use the workspace/MCP root. The default is <user config dir>/agent-tool/analysis-annotations.sqlite (Windows: under %APPDATA%). Reads do not create databases; the first annotation_set does. This is separate from the rebuildable codegraph DB and disposable analysis cache.

  • Notes are scoped by the full binary SHA-256 and static address. Identical copies keep their notes; changed binaries do not inherit them. There is no automatic migration between builds. Use a static va (hex or file/debug symbol) or PE rva (module-relative offset), not a live ASLR address or file offset.

  • annotation_kind is instruction (default), function (entry address), or decompile. Optional subject identifies a register, operand, or variable at that location. annotation_status is hypothesis (default), confirmed, or rejected; this records the user's assessment.

  • For a C-line comment, first run decompile with line_numbers=true. Pass the returned code_hash, the C-body line (L number), the function entry va, and annotation_kind="decompile" to annotation_set. Notes render before the corresponding line. A changed C snapshot keeps the note at the function header as needs_review instead of attaching it to another line. Headers, annotations, and trailing type definitions do not count toward L numbers.

  • Function notes appear above the C body. Instruction notes appear inline in disassembly. Decompile also gathers instruction notes inside exact PDB/.pdata or sized ELF-symbol ranges, showing each original VA above the C body. Unknown ranges fall back to entry notes with a notice; at most 16 ranges per function are used. These notes are not guessed onto individual C lines.

  • Set without an ID creates a new anchor; it rejects an occupied anchor instead of overwriting another editor's work. Update by annotation_id requires the exact expected_revision string from set/list. Omitted fields are preserved; nonempty top-level fields update only those values. Use annotation_patch for explicit empty strings or line=0; its supplied fields override top-level values. The merged record must still have a label or comment and a valid anchor. Delete requires both ID and expected revision. Stale edits/deletes fail without changing the record; read it again before retrying. Revisions remain strings, including in rendered notes and abbreviated receipts.

  • List supports address, kind, subject, status, ID and literal query filters (ASCII case folding). max_results defaults to 50 (max 200); result_offset is a row index and next_result_offset continues the JSON list. Output limits can shorten a page; raise max_output_chars when a single listed note cannot fit. Writes require at least 256 output characters, checked before any change. If full write details cannot fit, success still returns a short JSON receipt with saved, annotation_id, revision (or deleted) and details_omitted=true. Disassembly/decompile page by character instead. Rendered views cap notes at 500; list retrieves the rest.

  • Annotation DB load failures produce a visible warning alongside the original disassembly/decompilation; annotation CRUD still reports DB errors normally. Legacy v1/v2 DBs remain readable without modification. Their first write atomically migrates to v3, adding missing revision/evidence/provenance/anchor fields. Existing revisions are preserved (v1 starts at "1"). Older builds that only understand v1/v2 cannot open a v3 DB.

Partial edit example (use the ID and revision returned by your last read):

{"operation":"annotation_set","file_path":"sample.exe","annotation_id":"<id>","expected_revision":"1","annotation_patch":{"comment":"Confirmed user pointer","annotation_status":"confirmed","label":""},"annotations_path":"project.annotations.sqlite"}

Batch and evidence example:

{"operation":"annotation_batch","file_path":"sample.exe","annotations_path":"project.annotations.sqlite","batch":[{"operation":"set","rva":"0x1234","subject":"rax","comment":"User pointer","provenance":"manual analysis","evidence":[{"kind":"static","va":"0x140001230","source":"lookup_user call","detail":"Return value is used as a context pointer"}]},{"operation":"set","annotation_id":"<id>","expected_revision":"1","annotation_patch":{"annotation_status":"confirmed"}}]}

  • A batch contains 1..32 set/delete items sharing one binary and DB. It opens and hashes once; each item commits independently and returns an indexed receipt, including conflicts. Successful items remain committed when another fails. Required max_output_chars is at least 768 * item_count + 256, checked before any changes. The default budget supports 32 items. A DB-open error fails the envelope; cancellation leaves completed items committed and marks remaining items failed.

  • Optional evidence stores up to 16 user-supplied observations with kind (static, runtime, user), optional exact-string va, source, and required detail. provenance records the origin of the judgment. Neither sources nor observations are fetched or automatically verified. Both appear in saved/rendered notes and are searchable; sparse edits preserve them. annotation_patch with evidence:[] or provenance:"" explicitly clears them.

  • When saving a C-line note, include the exact raw line in anchor_text. annotation_suggest with its annotation_id decompiles that function and returns the current code_hash, revision and up to three candidate lines. Unchanged snapshots use the original line; otherwise stored text or token overlap proposes candidates. Equal top scores are marked ambiguous. Generic/missing anchors may produce no candidates. Old notes without text need manual selection after a snapshot change. Suggestions never write the DB. After review, call annotation_set with ID, expected_revision and annotation_patch:{"line":N,"code_hash":"<current hash>","anchor_text":"<raw line>"}. The revision guard still applies. Source/detail/provenance limits are 512/1024/512 UTF-8 bytes; anchor_text is one C line, max 2048 bytes.

{"operation":"annotation_suggest","file_path":"sample.exe","annotation_id":"<id>","annotations_path":"project.annotations.sqlite"}

Keep private annotation databases out of public Git history. This repository ignores *.annotations.sqlite* and the default DB filename. Custom filenames need their own ignore rule. Keep a backup of durable notes; clearing analysis caches does not remove them.

Key Improvements

Smart Indentation

LLMs typically output spaces, but many projects use tabs. AgentTool auto-converts indentation to match the file's existing style.

  • Inherits indent_style, indent_size, and tab_width per property from parent .editorconfig files, respecting root = true, unset, indent_size=tab, and common ** path patterns

  • Falls back to a content sample of up to 8 MiB, without a fixed line-count cap. Long lines and LF, CRLF, or CR endings are supported. Lexical block-opening evidence takes priority over raw indent/dedent frequencies, reducing confusion with continuation alignment; inconclusive evidence retains the deterministic frequency fallback

  • When recovering unique anchors, new space-indented levels use the nearest block-width evidence within 32 lines and 16 KiB. Lexical state is scanned from the file start within the 8 MiB sample; anchors beyond it retain the previous fallback. Common comments, quoted/raw/triple-quoted literals, and parenthesized/bracketed continuations are excluded from structural evidence. This is a heuristic, not a language parser or semantic formatter

  • Preserves the detected space width when existing space indentation conflicts with a tab setting

  • Converts tabs/spaces and space widths such as 2 ↔ 4; converted matches stay at line boundaries, and tab-depth correction preserves relative nesting

  • Unique line and multiline block anchors use actual local indentation and prefix mappings, preserving minority styles, alignment, and indented blank lines. Block nesting must agree

  • C++/header and Python file edits lazily reuse the embedded Tree-sitter WASM engine to infer new space-indented levels from direct statements in the actual enclosing block, rather than nearby sibling blocks or argument alignment. No external compiler, Python installation, CGO, or index is required

  • For successfully parsed replacement snippets, continuation lines aligned to an actual inline token column follow the opener's indentation shift; hanging indentation retains level rescaling even when the first argument is inline, and multiline literal/comment interiors retain their supplied content. Exact matches and explicit style overrides keep their existing behavior

  • Syntax assistance falls back to the existing heuristic on unsupported files, inconclusive/error-bearing enclosing blocks, analysis failures/timeouts, or sources over 8 MiB. Each parse has a 2-second budget; replacement-snippet assistance is limited to 64 KiB/512 lines. Syntax recovery is not a guarantee of semantic equivalence

  • Rejects equally plausible tab-depth candidates instead of choosing one arbitrarily

  • Detection is heuristic, not a language formatter; use dry_run=true to review an automatic edit

Encoding Preservation

Edits preserve the original file encoding instead of forcing UTF-8.

  • Detection priority: BOM → per-call encoding override → inherited .editorconfig charset → BOM-less UTF-16 → valid UTF-8 → chardet auto-detection → fallback encoding

  • Supported: UTF-8, UTF-8 BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16 (LE/BE, with or without BOM), and more

  • Inherited settings: charset inherits independently of indentation settings; new files honor charset = utf-8-bom by writing a UTF-8 BOM

  • Decode failures: malformed UTF-8/UTF-16, detected lossy decoding, and unsupported encodings return errors. write refuses to overwrite an existing file whose encoding cannot be read

  • Retry without project changes: read, multiread, edit, multiedit, write, patch, and file_info accept encoding="EUC-KR", encoding="CP949", or another supported charset, overriding .editorconfig. An existing BOM still takes priority; use convert_encoding for intentional conversion

  • Detection limits: automatic detection remains heuristic; its 64 KiB sample starts after the ASCII preamble so long headers do not hide legacy text. Specify encoding or charset when the result is ambiguous

  • No false warnings on ASCII: valid UTF-8 is verified directly, so plain ASCII files never raise a low-confidence warning

  • Line endings: Detects LF, CRLF, CR, and mixed files. edit matches a multi-line old_string whether the file uses CRLF or LF, including files that mix both, and text inserted by edit/regexreplace follows the newline style of the region it lands in, so the rest of the file is left byte-identical

Consistent reads and edit batches

  • read, multiread, file_info, grep, and patch agree on LF, CRLF, and CR line boundaries. A final terminator adds no phantom line; reading past EOF returns no lines.

  • Read hashes come from the same raw bytes as the text. edit, multiedit, write, patch, regexreplace, and convert_encoding check their captured source hash before saving. expected_hash is available on edit, multiedit, and patch.

  • multiedit supports the same encoding and indent_style options as edit; each replacement sees the previous result, and a failed replacement leaves the whole file unchanged.

  • multiread accepts global or per-file encoding. Resume the original input list with start_file_index=next_file_index and resume_offset=next_offset (omit the offset when zero); the current file keeps its original window end, and later files keep their original ranges.

  • Read output budgets are 256–131072 characters. An oversized first line is visibly shortened so paging can advance; raise max_output_chars or max_line_chars to inspect it in full.

Conversion and bulk-operation results

  • Directory regexreplace reports files_scanned, error_count, limit_reached, and truncated. The matching-file cap is explicit. Successful files stay changed if another file fails; inspect the partial result and retry only failed files.

  • diff accepts encoding_a/encoding_b and context_lines=0. It distinguishes identical decoded text from identical bytes, reports CR/LF placement changes, and separates a missing final newline from other ending changes.

  • convert_encoding accepts from_encoding for source hints. GBK and GB18030 remain distinct targets; GB2312 is a GBK compatibility alias. Characters unsupported by the chosen target leave the original unchanged.

  • File writes stage a replacement beside the target. If staging or replacement fails, they return an error and do not fall back to truncating the original in place. Close programs locking the target or correct directory permissions before retrying.

Token-safe directory listings

listdir defaults to 500 entries per page and returns next_cursor when more entries are available. Narrow results with directories_only, files_only, name_pattern (for example A*), or multiple OR patterns in include. Use counts_only=true when only matching file/directory counts are needed.

Idle memory release

After 30 minutes with no tool call, the server returns its heap to the OS. A stdio MCP server cannot tell an abandoned client from a quiet one -- the process that spawned it may be alive, finished with it, and still holding the pipe open, so no EOF ever arrives -- and exiting on that guess would break a session that merely paused. Releasing the memory is the safe half of that trade: an instance that once read a 50MB file settles back to its ~20MB baseline instead of holding 200MB for the rest of the machine's uptime. Open shell and ssh sessions survive, and nothing the client can observe changes.

Quick Start

  1. Download the binary for your OS from Releases

  2. Run agent-tool install (or agent-tool install claude for a specific agent)

  3. Restart your IDE / agent

  4. Done — the compact core tools are available immediately; toolbox describes and calls every other tool on demand

Or just ask your AI agent to do it for you:

"Download agent-tool from https://github.com/knewstimek/agent-tool/releases/latest and run agent-tool install"

Any capable AI coding agent (Claude Code, Codex, etc.) can handle the full download → install → restart flow automatically.

Recommended: Tell your agent to prefer agent-tool

After installing, agents will have access to agent-tool but may still default to built-in tools (Read, Edit, etc.). To ensure agents prefer agent-tool's encoding-aware, indentation-smart tools, add one of the instructions below.

Code navigation tip: For large projects, add this to your CLAUDE.md / AGENTS.md to enable AST-based code navigation:

At the start of a session, run codegraph(op="index", path="<project_root>") to build a code index.
For several repositories sharing one graph, use codegraph(op="index", path="<db_root>", roots=["<source_root_1>", "<source_root_2>"]). Source-root provenance prevents unrelated projects with the same symbol names from contaminating candidates while explicit/transitive includes can still cross roots.
Then use codegraph for structural queries (find, callers, callees, methods, inherits) instead of grep.

Pick Strict or Soft:

Mode

When to use

Instruction

Strict

Projects with non-UTF-8 files or mixed indentation

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools. agent-tool preserves file encoding and respects .editorconfig indentation settings.

Soft

General projects

Prefer agent-tool MCP tools (mcp__agent-tool__*) over built-in file tools when available.

Where to put it:

Per-project — add to your project's CLAUDE.md:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

Global (all projects) — add to ~/.claude/CLAUDE.md:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

Hard enforcement — deny built-in file tools at the permission level via ~/.claude/settings.json:

{
  "permissions": {
    "deny": ["Read", "Edit", "MultiEdit", "Write", "Glob", "Grep"]
  }
}

This makes Claude Code's built-in file tools unavailable, so the agent is forced to use agent-tool. Recommended when you want strict enforcement without relying on prompt instructions.

  1. Add to ~/.codex/config.toml (top-level, not inside [mcp_servers.*]):

model_instructions_file = "~/.codex/model_instructions.md"

  1. Create ~/.codex/model_instructions.md:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

  1. Restart Codex.

Per-project — add to your project's AGENTS.md instead.

Add to your project's .cursorrules, .windsurfrules, or AGENTS.md:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

Installation

Auto-install (recommended)

# Register with all detected agents (full auto-approve — all tools)
agent-tool install

# Safe mode — only auto-approve local file tools (no SSH, HTTP, DB, shell)
agent-tool install --safe-approve

# No auto-approve — manual approval required for every tool call
agent-tool install --no-auto-approve

# Register with a specific agent
agent-tool install claude
agent-tool install claude --safe-approve

# Uninstall (removes agent-tool entry only, preserves other settings)
agent-tool uninstall          # from all agents
agent-tool uninstall claude   # from specific agent

Install permission levels:

Level

Flag

Auto-approved tools

Full (default)

(none)

All tools (mcp__agent-tool__* wildcard)

Safe

--safe-approve

29 local-only tools (read, edit, write, grep, glob, etc.) — no SSH, HTTP, DB, bash, process control

None

--no-auto-approve

No tools — every call requires manual approval

Approval level is independent of schema profile: installation may approve the full namespace while the server still starts with the token-efficient core profile. toolbox is intentionally not auto-approved by --safe-approve, because its operation=call gateway can invoke network, shell, database, and process-control tools. Safe-mode users should review each toolbox approval and avoid granting it a permanent allow rule unless they intend to trust the full AgentTool namespace.

Manual setup

Claude Code / Cursor / Cline (settings.json or mcp.json):

{
  "mcpServers": {
    "agent-tool": {
      "command": "/path/to/agent-tool"
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.agent-tool]
command = "/path/to/agent-tool"

Options

# Select the initial schema profile (default: core)
agent-tool --profile core-lite

# Keep the core and eagerly expose only selected additional tools
agent-tool --profile core+copy+delete+ssh+wintool

# Set fallback encoding for projects with non-UTF-8 files
agent-tool --fallback-encoding EUC-KR

Profiles are presets: core-lite (read/write/edit/grep/toolbox), core (11 schemas), coding (core plus broader file/build/shell tools), remote, analysis, and full. Append +tool names to a preset for a custom initial inventory; for example, core+copy+delete+ssh+wintool exposes 15 tools while leaving analysis and other remote tools behind the gateway. The same syntax works in AGENT_TOOL_PROFILE and toolbox operation=profile. Unknown tools or empty components reject the whole selection before any tools are registered. At runtime, prefer the client-independent toolbox gateway: operation=describe returns one tool's schema (compact=true plus tool_operation limits it to one operation), and operation=call invokes it through the stable toolbox binding. Re-send a returned schema_handle to avoid receiving an unchanged schema again. When command diagnostics are compacted, operation=output retrieves the bounded raw output by its reported ID for 30 minutes and reports next_offset when paging is needed. enable, disable, and profile remain available for clients that honor tools/list_changed; fixed-binding clients can always keep using the gateway.

Environment Variable

Set AGENT_TOOL_FALLBACK_ENCODING and/or AGENT_TOOL_PROFILE to avoid repeating CLI flags:

# Windows (no admin required)
setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR
setx AGENT_TOOL_PROFILE coding

# Linux / macOS (add to ~/.bashrc or ~/.zshrc)
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR
export AGENT_TOOL_PROFILE=coding

Priority: CLI flag > environment variable > default (UTF-8).

Local SSH/SFTP connection profiles

SSH and SFTP accept either connection_profile or a session-local connection_id, so host, user, key, and jump-host fields do not need to be repeated. Profiles are read from the OS user config directory at agent-tool/connections.json; override the location with AGENT_TOOL_CONNECTION_PROFILE_FILE. Keep this file local and explicitly ignored if it is placed inside a workspace.

{
  "connections": {
    "dev": {
      "host": "192.0.2.10",
      "user": "builder",
      "key_file": "/local/path/to/id_ed25519",
      "host_key_check": "strict",
      "trusted": true
    }
  }
}

An initial call returns an opaque connection_id that remains reusable by both tools for 30 minutes. Local profiles default to trusted:true; set trusted:false to show the private-address warning on every call instead of once per pooled connection. This affects only display; SSRF blocking and cloud metadata protection are unchanged. SSH also supports quiet, echo_command, and result_only; the last returns compact JSON centered on stdout, stderr, and exit_code. SFTP supports quiet, result_only, and upload_many (up to 100 files).

For Windows PowerShell, pass script text in powershell_script instead of command. SSH uploads a unique UTF-8 temporary .ps1 through a short PowerShell command's standard input, executes its contents with a short PowerShell launcher, and deletes it after success or failure. Standalone powershell[.exe] / pwsh[.exe] commands using -EncodedCommand (or -enc, -ec, -e) are staged automatically at 8,000 UTF-16 code units. Safe profile, interactive, apartment, and execution-policy options are preserved; unsupported options or shell suffixes require explicit powershell_script input. Scripts are limited to 4 MiB. SFTP is not required, including on legacy Windows SSH servers.

{"operation":"execute","connection_profile":"dev","powershell_script":"Write-Output 'hello'","result_only":true}

Preparation and foreground execution share timeout_sec. Background scripts use the same upload and cleanup path, then expose job_id for status/tail/cancel. The remote launcher attempts cleanup in finally; confirmed completion also triggers bounded SSH cleanup. Cancellation or connection loss does not prove remote termination, so the tool leaves deletion to the remote launcher and reports cleanup_warning if completion or cleanup could not be confirmed. This warning is separate from the script's exit code and captured output.

Local SSH private-key conversion

ssh_key converts a private-key file without sending its contents over the network or returning key material in the response. Input is auto-detected as PPK, PEM, PKCS#8, or OpenSSH. The output format is one of ppk, pem, pkcs8, or openssh.

{
  "operation": "convert",
  "input_path": "server.pem",
  "output_path": "server.ppk",
  "output_format": "ppk",
  "input_passphrase": "",
  "output_passphrase": "",
  "overwrite": false
}

PPK output uses version 3. Passphrase-protected PPK output uses Argon2id, AES-256-CBC, and HMAC-SHA-256; protected OpenSSH output uses OpenSSH's modern encrypted format. Traditional PEM and PKCS#8 output are deliberately unencrypted; use openssh or ppk when output encryption is required. New files are mode 0600, and existing files are not replaced unless overwrite=true.

Runtime Configuration

Agents can change settings at runtime via set_config without restarting:

Parameter

Description

Default

fallback_encoding

Fallback encoding when auto-detection fails

UTF-8

encoding_warnings

Show encoding detection warnings

true

max_file_size_mb

Max file size for read/edit/grep (MB)

100

allow_symlinks

Allow symlink extraction from tar archives

false

workspace

Explicit local workspace root. Otherwise the first MCP client root is used, then cwd

(MCP root/cwd)

allow_http_private

Allow webfetch/download/httpreq to access private IPs

false

allow_mysql_private

Allow mysql tool to access private IPs

true

allow_redis_private

Allow redis tool to access private IPs

true

allow_ssh_private

Allow ssh/sftp tools to access private IPs

true

enable_doh

Enable DNS over HTTPS globally (webfetch/download/httpreq/dnslookup)

true

enable_ech

Enable Encrypted Client Hello globally (webfetch/download/httpreq)

true

Build

go build -trimpath -ldflags="-s -w" -o agent-tool .

Cross-compile:

GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool.exe .

Release

The guarded GitHub workflow runs tests, builds all declared assets, creates the MCPB and checksums, and verifies uploaded bytes. From a clean, pushed master branch, dispatch a build-only dry run:

.\scripts\release.ps1

After the dry run succeeds, publish the version declared in main.go:

.\scripts\release.ps1 -Publish

The workflow requires tracked notes at docs/releases/vVERSION.md. Publication creates an annotated tag and GitHub Release, then updates server.json with the released MCPB hash. When RepoPlane uses this repository as its workspace, the same dry-run, publish, and status operations are discoverable through the repository-local catalog/ manifests.

Troubleshooting

Garbled text (encoding issues)

If Korean, Japanese, or other non-ASCII text appears as garbage characters:

Option 1: Add charset to your .editorconfig:

[*]
charset = euc-kr

Option 2: Set environment variable (persistent):

setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR   # Windows
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR  # Linux

Option 3: CLI flag (per-session):

agent-tool --fallback-encoding EUC-KR

Built-in help for agents

agent-tool includes a agent_tool_help tool that agents can call for usage guidance. When an agent encounters encoding warnings or garbled text, it can call:

{ "tool": "agent_tool_help", "arguments": { "topic": "encoding" } }

Available topics: overview, encoding, indentation, tools, troubleshooting

Security

agent-tool provides powerful system access (SSH, MySQL, Redis, file operations, HTTP requests). When used with AI coding agents, be aware of prompt injection risks:

  • SSRF Protection: Cloud metadata IPs (169.254.x.x, fe80::/10) are always blocked regardless of settings. Private IP access is configurable per protocol via set_config (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)

  • DLP (Data Loss Prevention): All outbound HTTP request bodies are scanned for sensitive data patterns (PEM private keys, AWS access keys, GitHub/GitLab tokens, Slack tokens, .env file dumps) and blocked before transmission

  • Prompt Injection Warnings: Allowed private IP connections show a compact warning; trusted local SSH/SFTP profiles show it once per pooled connection

  • Zip Slip protection: Archive entries with ../ path traversal are blocked (both zip and tar)

  • Zip Bomb protection: Single file limit (1GB), total extraction limit (5GB)

  • Symlinks: Skipped by default. Enable via set_config allow_symlinks=true (tar only; zip symlinks always skipped). Even when enabled, symlinks targeting outside the output directory are blocked

  • File size limit: Configurable max file size (default 100MB) prevents OOM on large files. Adjustable via set_config max_file_size_mb=N

  • Encoding safety: chardet uses a 64 KiB sample after the ASCII preamble; malformed input is reported before an edit can persist lossy text

For maximum security, review the AI agent's tool calls before approving, especially for SSH commands, HTTP requests to external URLs, and database queries.

Tech Stack

  • Language: Go

  • MCP SDK: github.com/modelcontextprotocol/go-sdk

  • Encoding: saintfish/chardet + golang.org/x/text

  • Distribution: Single binary (cross-compiled)

  • Decompiler: Gosleigh with embedded Ghidra x86/x64 language specs

  • PDB: gopdb (PDB 7.0 reader and MSVC demangler)

License

MIT

The decompiler (Gosleigh) and the Ghidra language specs it embeds are licensed under the Apache License 2.0; Gosleigh is a reimplementation of the Ghidra decompiler, developed by the National Security Agency (https://github.com/NationalSecurityAgency/ghidra).

Available Tools

11 tools
agent_tool_helpA

Returns usage guide for agent-tool. Call this when you encounter encoding warnings, garbled text, or need to understand agent-tool features. Topics: overview, encoding, indentation, tools, debug, analyze, troubleshooting.

NameRequiredDescriptionDefault
topicNoHelp topic. Available: overview, encoding, indentation, tools, debug, analyze, memtool, wintool, codegraph, troubleshooting. Empty = overview

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that it returns a usage guide and lists topics, but does not explicitly state that it is read-only or has no side effects. For a help tool this is low risk, but the description could be more transparent about the operation's safety.

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 three short, front-loaded lines: purpose, when to call, and topics. The topics list is somewhat redundant with the schema, but overall there is little waste and the structure is easy to scan.

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

Completeness4/5

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

For a simple help tool with one optional parameter and no output schema, the description covers purpose, triggers, and topics. It does not describe the return format, but since the output is free-form help text, that omission is minor. The definition is sufficient for correct invocation.

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 100%, so the schema already documents the single 'topic' parameter thoroughly. The description lists a subset of topics but adds no syntax, format, or default behavior beyond what the schema provides. Baseline 3 is appropriate.

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

Purpose4/5

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

The description states a specific verb and resource: 'Returns usage guide for agent-tool.' It clearly distinguishes from siblings (edit, write, read, etc.) since it is the only help-oriented tool. However, 'agent-tool' is slightly ambiguous as it could refer to the tool itself or the broader server.

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

Usage Guidelines5/5

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

It explicitly states when to call: 'Call this when you encounter encoding warnings, garbled text, or need to understand agent-tool features.' No alternatives exist among siblings, so no exclusions are needed. The triggers are clear and actionable.

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

editA

Replace exact text in a file. Preserves encoding and local line endings, adapts indentation using the file and .editorconfig, and supports dry-run plus hash-guarded edits.

NameRequiredDescriptionDefault
pathNoAlias for file_path
dry_runNoPreview only; default false
encodingNoCharset override, e.g. EUC-KR or Shift_JIS; overrides .editorconfig, BOM takes priority
file_pathNoFile path; relative to workspace/MCP root
new_stringNoReplacement text; must differ from old_string
old_stringNoExact text to find in the file
new_contentNoAlias for new_string
old_contentNoAlias for old_string
replace_allNoReplace every match; default false
indent_styleNotabs or spaces-N; default auto-detect
expected_hashNoExpected SHA-256; mismatch rejects edit

TDQS

A3.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does real work: it discloses encoding preservation, local line-ending preservation, .editorconfig-driven indentation adaptation, a dry-run mode, and hash-guarded edits that reject on mismatch. It still omits failure behavior for missing or ambiguous old_string and whether the file must already exist.

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?

A single front-loaded sentence states the core operation first, then enumerates the behavioral guarantees. No filler, no restatement of the tool name, and every clause maps to a distinct behavior an agent would otherwise have to guess.

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?

For an 11-parameter mutation tool with no annotations and no output schema, the description covers the important behavioral traits but leaves error semantics, uniqueness requirements, and return information unstated. It is adequate but not complete for the complexity involved.

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 100%, so the schema already documents all 11 parameters including the aliases and the SHA-256 guard, which sets the baseline at 3. The description adds modest color on expected_hash, encoding precedence, and dry-run, but does not explain the alias pairs or replace_all semantics beyond what the schema states.

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

Purpose4/5

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

The description gives a specific verb and mechanism: "Replace exact text in a file," which is meaningfully narrower than write or patch. It does not name any sibling (multiedit, patch, write) to differentiate itself, so an agent must infer the boundary from "exact text" alone.

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?

There is no explicit when-to-use or when-not guidance, and no alternative tool is named despite multiedit, patch, and write being obvious overlapping siblings. At best an agent can infer that exact-match replacement applies to an existing file, which is implied rather than stated.

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

globA

Finds files matching a glob pattern. Supports ** recursive matching and sorts results by modification time (newest first). Defaults to 200 workspace-relative paths and 32768 characters per page. Skips hidden paths and paths excluded by root .gitignore/.ignore or the common generated/vendor policy unless explicitly included. Returns total/has_more/truncated metadata and an opaque next_cursor.

NameRequiredDescriptionDefault
pathNoDirectory to search. Defaults to configured workspace, MCP client root, or current directory
limitNoMaximum paths returned per page. Default: 200, Max: 5000
cursorNoOpaque continuation cursor returned by a previous glob call
patternYesGlob pattern to match files (e.g. **/*.go or src/**/*.ts)
include_hiddenNoTraverse hidden directories. Explicit hidden roots are always searched. Default: false
relative_pathsNoReturn paths relative to the search directory. Default: true
include_ignoredNoInclude paths excluded by .gitignore/.ignore or the common generated/vendor policy. Default: false
max_output_charsNoMaximum returned text characters. Default: 32768, Max: 131072

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description carries full behavioral burden, and it excels: it discloses sorting by modification time, default limits (200 paths, 32768 chars), skip rules for hidden and ignored paths, and pagination via next_cursor and metadata (total/has_more/truncated). This is thorough and actionable, covering the major behavioral traits an agent needs to anticipate.

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 compact and front-loaded with the core purpose, followed by key behaviors and return metadata. Every sentence adds distinct information (recursion, sorting, defaults, exclusions, pagination) with no filler. It is well-structured and easy to scan.

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 8 parameters, no annotations, and no output schema, the description covers the essential usage context: purpose, defaults, skip rules, sorting, and pagination metadata. It clearly states the return includes metadata and a cursor, which is sufficient for an agent to invoke and handle results. Minor gaps exist (e.g., exact shape of the path list) but these are not critical for correct invocation.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how parameters interact: e.g., include_hidden affects traversal, include_ignored overrides skip rules, and limit/cursor govern pagination. It also clarifies default behavior (workspace-relative, 200 limit). This enriches parameter understanding without contradicting 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 opens with a clear verb and resource: 'Finds files matching a glob pattern.' It immediately distinguishes from siblings like listdir (directory listing) and grep (content search) by specifying pattern matching and recursive support. This is a specific, unambiguous 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 implies usage when pattern-based file discovery is needed but does not explicitly state when to prefer this over listdir or grep, nor does it list exclusions (e.g., 'for directory contents, use listdir'). Context is provided via behavior (e.g., default limits, skip rules) but not as routing guidance. It is adequate but not explicit.

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

grepA

Regex-search encoding-aware files or directories. Supports context, glob filters, content/file/count modes, ignored-path controls, and bounded pageable output. Directory searches skip detected binaries; explicit files are searched.

NameRequiredDescriptionDefault
globNoDirectory file filter, e.g. *.go
pathNoFile or directory; defaults to workspace/MCP root/CWD
afterNoLines after; overrides context
beforeNoLines before; overrides context
cursorNoContinuation cursor; incompatible with context lines
contextNoLines before/after; max 1000
patternYesRegular expression
file_pathNoAlias for path
recursiveNoRecurse; default true
ignore_caseNoIgnore case
max_resultsNoMatches per page; default 100, max 100000
output_modeNocontent (default), files_with_matches, or count
output_formatNocompact (default) or classic path:line:text
include_hiddenNoInclude hidden directories
max_line_charsNoPer-line cap; default 4000, max 32768
relative_pathsNoPaths relative to root; directory default true
include_ignoredNoInclude ignored/generated/vendor paths
max_output_charsNoOutput cap; default 32768, max 131072

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does a strong job: it discloses encoding-awareness, binary skipping in directories, bounded pagination, ignored-path controls, and output modes. It does not mention rate limits or auth, but for a read-only search tool, this is comprehensive. No contradiction with annotations since none exist.

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

Conciseness5/5

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

Two sentences, front-loaded with the core purpose, and every clause adds value (modes, filters, output behavior, binary handling). No fluff, well-structured for quick parsing.

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?

Despite 18 parameters and no output schema, the description covers the major behavioral areas (search scope, filters, pagination, binary handling). It does not explicitly mention incompatibilities like cursor vs. context, but those are captured in the schema. The description is sufficient for an agent to understand the tool's role and invoke it 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 100%, so the schema already documents every parameter. The description adds high-level context (e.g., 'context, glob filters, content/file/count modes') that maps to parameters but does not explain each individually. It does not go beyond the schema, so a baseline 3 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?

The description clearly states a specific verb ('Regex-search') and resource ('encoding-aware files or directories'), and enumerates key features that distinguish it from siblings like glob (which finds filenames) and read (which reads content). It leaves no ambiguity about what the tool does.

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

Usage Guidelines3/5

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

The description implies usage via feature list but does not explicitly state when to use grep versus alternatives (e.g., 'use for content search, not filename matching'). It does clarify directory vs. explicit file behavior, but lacks direct routing guidance or exclusions, so the agent must infer from sibling names.

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

listdirA

Lists directory contents with bounded, pageable output. Default: flat listing, max_depth=3, max_entries=500. When has_more=true, pass next_cursor as cursor to fetch the next page. Filter by type with directories_only or files_only, and by entry-name glob with name_pattern (single) or include (multiple OR patterns, e.g. ["A*", "*.go"]). Use counts_only=true for counts without names, flat=false for a visual tree, and relative_paths=true to save tokens. Skips hidden entries and common build/vendor directories during recursion.

NameRequiredDescriptionDefault
flatNoFlat listing without tree connectors (one path per line). Default: true
pathNoDirectory to list. Relative paths use the configured workspace or MCP client root
cursorNoOpaque continuation cursor returned by a previous listdir call
includeNoAdditional entry-name glob patterns. An entry is included when any pattern matches
file_pathNoAlias for path
max_depthNoMaximum depth for traversal. Default: 3
files_onlyNoReturn files only: true or false. Default: false
counts_onlyNoReturn matching directory/file counts without listing names: true or false. Default: false
max_entriesNoMaximum entries to return per page. Default: 500, maximum: 10000
name_patternNoGlob matched against each entry name, for example A* or *.go
relative_pathsNoShow paths relative to the root. Saves tokens: true or false. Default: false
directories_onlyNoReturn directories only while still traversing them: true or false. Default: false

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does a good job: it discloses pagination mechanics, skip behavior for hidden/build/vendor entries, the flat/tree distinction, counting mode, and token-saving relative paths. It does not describe the exact response fields, but it mentions has_more and next_cursor sufficient to drive pagination.

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?

Each sentence carries a distinct responsibility: definition, defaults, pagination, filtering, output modes, skipped entries. There is no filler or repetition, and key information is front-loaded.

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

Completeness4/5

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

The description covers defaults, pagination, filtering, output modes, and behavioral exclusions, which is a solid level of context. Since there is no output schema, the only minor gap is omitted return record shape, but the provided behavior is enough for a capable agent.

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%, so the baseline is 3, but the description adds relationship semantics beyond the schema: pagination binds has_ more to the cursor parameter, name_pattern versus include as single/multi OR patterns, and counts_only relative_paths as output modifiers. These are not obvious 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?

The description clearly states the tool 'lists directory contents' and immediately adds the defining scope: bounded, pageable output. This is a specific verb plus resource and distinguishes the tool from siblings like read, write, and grep, even before opening the schema.

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 gives practical usage guidance: paginate with cursor when has_more=true, filter with directories_only/files_only, and use counts_only or relative_paths for optimization. It does not explicitly tell an agent when to prefer listdir over sibling tools like glob, but the tool's 'list directory contents' purpose implies the context.

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

multieditA

Applies multiple old_string -> new_string replacements to a single file in one call. Edits are applied sequentially in order; each edit sees the result of the previous one. Atomic: if any edit fails, the file is not modified at all. Encoding-aware: preserves original file encoding (UTF-8, EUC-KR, Shift-JIS, etc.). Line-ending aware: old_string matches whether the file uses CRLF or LF, and inserted newlines follow the region being edited (mixed-newline files stay intact). Accepts "path" as alias for "file_path". Use dry_run=true to preview all changes without modifying the file.

NameRequiredDescriptionDefault
pathNoAlias for file_path
editsYesOrdered list of replacements to apply sequentially
dry_runNoPreview changes without modifying the file: true or false. Default: false
encodingNoCharset override, e.g. EUC-KR or CP949; overrides .editorconfig, BOM takes priority
file_pathNoFile to edit. Relative paths use the configured workspace or MCP client root
indent_styleNotabs or spaces-N; default auto-detect, same as edit
expected_hashNoExpected raw-file SHA-256; mismatch rejects the whole batch

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description bears the full burden and does substantial work: sequential application where each edit sees the prior result, atomic rollback if any edit fails, encoding preservation, and CRLF/LF-aware matching. Gaps remain around permissions requirements and what happens if the file is missing or if the edits array is empty, but the core mutation semantics are unusually well disclosed.

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 core behavior is front-loaded in the first sentence, and each subsequent sentence isolates one behavioral trait (ordering, atomicity, encoding, line endings, alias, preview). No sentence is redundant with another and nothing is padded.

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

Completeness4/5

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the risky dimensions an agent most needs: ordering, atomicity, and encoding/line-ending fidelity. What is missing is modest but real, namely the return shape (no output schema exists, so a hint would help) and the interaction with expected_hash rejection beyond the schema's one line.

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 100%, so the baseline is 3 and the schema already documents path aliasing, dry_run, encoding, and expected_hash individually. The description reinforces the alias and preview semantics and adds the meaningful ordering guarantee for the edits list, but contributes no new interpretation for encoding, indent_style, or expected_hash beyond the schema text.

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

Purpose4/5

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

The description opens with a precise verb and resource: it applies multiple old_string -> new_string replacements to a single file in one call. The "multiple ... in one call" and "single file" wording implicitly separates it from the singular `edit` sibling, but it never names that sibling, so differentiation is inferred rather than stated.

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

Usage Guidelines3/5

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

There is one concrete usage hint, "Use dry_run=true to preview all changes without modifying the file," which is genuinely actionable. However, there is no guidance on when to choose multiedit over `edit`, `patch`, or `write`, and no stated prerequisites for use.

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

multireadA

Reads multiple files in a single call to reduce API round-trips. Encoding-aware: auto-detects each file, with optional global/per-file encoding overrides. Supports offset/limit for reading specific line ranges. Defaults to 200 lines per file and 32768 characters total across the call. Returns visible per-file and overall truncation metadata with continuation positions. Resume the same input list with start_file_index=next_file_index and resume_offset=next_offset (omit resume_offset when zero). Use file_paths or paths (string array) with global offset/limit, or files (object array) for per-file offset/limit. If a file fails, the error is included in output and remaining files continue. Maximum 50 files per request.

NameRequiredDescriptionDefault
allNoRemove the default per-file line limit. The total character budget still applies. Default: false
filesNoPer-file read ranges. Each entry has path, offset, limit. Takes priority over file_paths
limitNoMaximum lines per file. Default: 200. Set 0 or all=true to remove the line limit
pathsNoCompatibility alias for file_paths; prefer file_paths
offsetNoLine number to start from (1-based, negative = from end). Default: 1
encodingNoDefault charset override, e.g. EUC-KR or CP949; files entries may override it; BOM takes priority
file_pathsNoFile paths to read. All files use the global offset/limit. Use files for per-file ranges
include_hashNoInclude per-file SHA-256 hashes. Default: false
resume_offsetNoOverride offset only for start_file_index; other files retain their original ranges
max_line_charsNoMaximum characters returned from one line. Default: 4000, Max: 32768
max_output_charsNoMaximum total returned text characters across all files. Default: 32768, Min: 256, Max: 131072
start_file_indexNoResume at this 1-based index in the original file list; default 1

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses default budgets (200 lines/file, 32768 chars total), truncation metadata and continuation positions in the response, error isolation (a failed file reports its error while the rest continue), encoding precedence (BOM > per-file > global), and the 50-file cap. These are exactly the behavioral traits an agent needs before calling a bulk reader.

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?

Purpose is front-loaded in the first sentence and each subsequent line carries distinct information rather than restating the schema. The result is somewhat dense as a single block with several interacting concepts (resume, encoding, dual path parameters), which costs it the top score but there is no filler.

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 12-parameter, annotation-free bulk reader with no output schema, the description covers the response shape (truncation metadata, continuation offsets, per-file errors), all default budgets, and the resumption protocol. An agent can construct a correct call and correctly chain a follow-up call from the text alone.

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%, so the baseline is 3, but the description adds real meaning beyond it: the precedence of `files` over `file_paths`, and the non-obvious pairing of `start_file_index` with `resume_offset` (omit it when zero, other files keep original ranges). It does not explain `all`, `include_hash`, or `max_line_chars`, but those are already self-documenting in 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?

Opens with a specific verb+resource+scope: reads multiple files in a single call to reduce API round-trips, which cleanly separates it from the single-file `read` sibling. The follow-up lines enumerate the distinguishing capabilities (encoding detection, offset/limit, truncation metadata) that make the tool's identity unambiguous.

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

Usage Guidelines4/5

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

Gives clear operational context: when to pick `file_paths`/`paths` versus `files`, when to use `start_file_index`+`resume_offset` to continue a truncated read, and the 50-file ceiling. It never explicitly names the single-file `read` alternative or states when NOT to use this tool, so a 4 rather than a 5.

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

patchA

Applies a unified diff patch to a file. Parses @@ hunk headers, verifies context lines, and applies changes. Encoding-aware: preserves original file encoding. Line-ending aware: each line keeps its own ending (a mixed CRLF/LF file is not rewritten) and a file without a trailing newline does not gain one. Use dry_run=true to preview without modifying the file.

NameRequiredDescriptionDefault
pathNoAlias for file_path
patchYesUnified diff text (output of the diff tool)
dry_runNoPreview patch result without modifying the file: true or false. Default: false
encodingNoCharset override, e.g. CP949; overrides .editorconfig, BOM takes priority
file_pathNoFile to patch. Relative paths use the configured workspace or MCP client root
expected_hashNoExpected raw-file SHA-256; mismatch rejects the patch

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: it discloses that hunks are parsed and context lines verified, that encoding is preserved, and that per-line endings (mixed CRLF/LF) and absence of a trailing newline are left intact. What it omits is failure behavior — whether a failed context check aborts the whole patch or leaves a partially written file — which matters for a mutation tool.

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

Conciseness4/5

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

Front-loaded with purpose, then layered detail in descending order of importance: mechanics, encoding, line endings, preview. Every sentence conveys distinct information, though the line-ending sentence is the longest and could be tightened without losing meaning.

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?

For a 6-parameter mutation tool with no annotations and no output schema, the description covers the 'what' well but leaves the agent guessing about atomicity, error/rollback semantics, and what a successful call returns. The safety-relevant gaps are meaningful given nothing else supplies them.

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 100%, so all six parameters including the path/file_path alias, expected_hash, and encoding override are already documented in structured fields. The description only reinforces dry_run, which the schema already explains. Baseline 3 is appropriate since the schema does the heavy lifting.

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

Purpose4/5

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

The description opens with a specific verb and resource: 'Applies a unified diff patch to a file', and the following sentence narrows the mechanism to unified-diff semantics (hunk headers, context-line verification). That is enough to separate it from a plain 'write' or 'edit', but it never names the sibling tools (edit, multiedit, write) that an agent would otherwise have to weigh it against.

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 only explicit guidance is 'Use dry_run=true to preview without modifying the file', which is a per-parameter hint rather than tool-selection guidance. There is no statement of when to prefer this over edit/multiedit, or what precondition (e.g. having diff output) must hold. Usage is implied by the phrase 'output of the diff tool' in the schema, not by the description.

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

readA

Read text with line numbers or return raster images as ImageContent. Detects common encodings; SVG stays text. Text is bounded and reports truncation/next_offset. Use offset/limit to page; relative paths use the workspace or MCP root.

NameRequiredDescriptionDefault
allNoDisable line cap; character cap remains
pathNoAlias for file_path
limitNoLine limit; default 400. Use 0 or all=true for no line cap
offsetNoStart line: 1-based integer, negative from end, 'start-end', or [start,end]; default 1
encodingNoCharset override, e.g. EUC-KR or Shift_JIS; overrides .editorconfig, BOM takes priority
end_lineNoInclusive end with start_line
file_pathNoAbsolute or workspace/MCP-root-relative file path
start_lineNoAlias for offset
include_hashNoInclude SHA-256; default true
max_line_charsNoPer-line character cap; default 4000, max 32768
max_output_charsNoOutput character cap; default 32768, min 256, max 131072

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the burden and mostly succeeds: it discloses the dual text/image return mode, encoding auto-detection with an SVG exception, bounded output, and explicit truncation/next_offset reporting. It does not cover failure behavior (missing file, unreadable binary) or state the read-only/no-side-effect nature explicitly, so it stops short of full disclosure.

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

Conciseness5/5

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

Four short sentences, front-loaded with the primary behavior, and every clause carries information an agent cannot get elsewhere (image mode, SVG exception, truncation signal, path base). No filler or restatement of the name.

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

Completeness4/5

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

For an 11-parameter tool with full schema coverage and no output schema, the description covers the essential unknowns: what is returned (text with line numbers vs ImageContent), how large it may be, how truncation is signalled, and how to continue paging. Gaps are minor – error behavior and guidance on the aliased/overlapping parameters (path vs file_path, start_line vs offset) are left entirely to the schema.

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 100%, so every parameter is already documented, and the description mostly reinforces it (offset/limit paging, relative path resolution) rather than adding new meaning. The one genuine addition is the framing of offset/limit as the paging mechanism and the note that text is bounded and reports next_offset. Baseline 3 is appropriate.

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?

States a concrete verb and resource ('Read text with line numbers') plus a second output mode ('return raster images as ImageContent'), which lets an agent distinguish it from glob/grep/listdir. It never names the closest sibling (multiread) or explains the split, so the differentiation is implicit rather than explicit.

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

Usage Guidelines3/5

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

'Use offset/limit to page' gives real operational guidance for large files, and the path-resolution note clarifies relative paths. But there is no when-to-use vs when-not guidance relative to grep (search content), listdir (enumerate files), or multiread (several files at once), which are the decisions an agent actually has to make.

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

toolboxA

Discover and call tools without loading every schema. Use describe, preferably compact with tool_operation, then call with arguments. Reuse schema_handle. output retrieves preserved paged command output. list shows tools; enable/disable/profile manage direct bindings. Profiles: core-lite, core, coding, remote, analysis, full.

NameRequiredDescriptionDefault
toolNoTarget tool for describe/call
toolsNoTool names for enable/disable
groupsNoGroups for enable/disable: core, file, coding, system, remote, data, analysis, windows
compactNoReturn a reduced describe schema
profileNoProfile to add: core-lite, core, coding, remote, analysis, or full; append +tool names for extra tools
argumentsNoTarget arguments for call; describe first if unknown
operationNolist (default), describe, call, output, enable, disable, or profile
output_idNoRaw output ID for output
output_offsetNoOutput character offset; default 0
schema_handleNoPrior handle; short acknowledgement if unchanged
tool_operationNoOperation-specific compact schema, e.g. execute
output_max_charsNoOutput character limit; default 32768, max 130048

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the full burden; it discloses some real behavior such as preserved paged output with offsets/limits and a short acknowledgement when schema_handle is unchanged. However, the stateful operations are underspecified: it never says whether enable/disable/profile persist, whether they are reversible, or what happens to existing bindings. The meaning of 'manage direct bindings' is left unexplained.

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?

At roughly 55 words covering nine operations, there is almost no filler and the core purpose is front-loaded. The drawback is structural: operations are crushed into semicolon-joined fragments like 'enable/disable/profile manage direct bindings,' which forces re-reading to disambiguate.

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?

For a 12-parameter, nine-operation meta-tool with no annotations and no output schema, the description should do more. It never explains which parameters apply to which operation, how errors or invalid tool names surface, or what describe/call results look like beyond the paged-output note on one operation.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains all 12 parameters including profile values, output offsets and limits. The description reinforces the intended pairing of compact with tool_operation and reuse of schema_handle, but adds little parameter meaning the schema does not already supply, and it omits the schema's '+' suffix convention for extra tools in profiles.

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

Purpose4/5

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

The description opens with a specific framing: 'Discover and call tools without loading every schema,' which pins this as a meta/proxy tool rather than a domain tool. It then names each operation's role (describe, call, output, list, enable/disable/profile) so an agent can map intent to operation. It lacks an explicit statement that the tool is for cases where target schemas are not pre-loaded, leaving the routing versus the file-oriented siblings implicit.

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 prescribes a concrete workflow: describe first, preferably with compact and tool_operation, then call with arguments, and reuse schema_handle. That is actionable sequencing an agent can follow directly. It stops short of stating when NOT to use this tool (e.g., when the target tool is already loaded and can be called directly) and doesn't rank alternatives.

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

writeA

Create or overwrite a file. Preserves existing encoding, uses .editorconfig for new files, and creates parent directories.

NameRequiredDescriptionDefault
pathNoAlias for file_path
contentYesContent to write to the file
encodingNoCharset override, e.g. EUC-KR or Shift_JIS; overrides .editorconfig, existing BOM takes priority
file_pathNoFile path; relative to workspace/MCP root

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description carries the full disclosure burden, and it does add three useful traits: encoding preservation, .editorconfig usage for new files, and automatic parent directory creation. It omits what matters most for a mutation tool with no safety annotations — whether an existing file is truncated wholesale, whether the call is reversible, and what happens on permission or path errors.

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?

A single front-loaded sentence with the mutation stated first and the behavioral guarantees trailing. Every clause earns its place and nothing is padded.

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?

For a four-parameter write tool with no annotations and no output schema, the description covers encoding and directory side effects but leaves the overwrite/truncation semantics and error behavior unstated. Adequate but not sufficient to call the tool confidently in destructive scenarios.

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 100%, so the baseline is 3; every parameter is already documented, including the encoding precedence rules. The description does not address the file_path/path alias or the fact that file_path is not in the required list, which is the one piece of parameter meaning the schema leaves ambiguous.

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?

"Create or overwrite a file" gives a specific verb and resource, and the word "overwrite" implicitly separates it from the incremental siblings edit, multiedit and patch. It stops short of naming those siblings, so an agent must infer the boundary rather than being told it.

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 phrase "create or overwrite" implies full-file replacement, which hints at when this should be chosen over edit or patch, but the description never states the condition or names an alternative. No prerequisites or exclusions are given.

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

Tool Schema Changelog

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

  1. 7 tool updatesv1.0.5
    • Changededit1 field changed
      • addedInput schema / properties / encoding
        Added value: +{
+  "description": "Charset override, e.g. EUC-KR or Shift_JIS; overrides .editorconfig, BOM takes priority",
+  "type": "string"
+}
    • Changedmultiedit3 fields changed
      • addedInput schema / properties / encoding
        Added value: +{
+  "description": "Charset override, e.g. EUC-KR or CP949; overrides .editorconfig, BOM takes priority",
+  "type": "string"
+}
      • addedInput schema / properties / expected_hash
        Added value: +{
+  "description": "Expected raw-file SHA-256; mismatch rejects the whole batch",
+  "type": "string"
+}
      • addedInput schema / properties / indent_style
        Added value: +{
+  "description": "tabs or spaces-N; default auto-detect, same as edit",
+  "type": "string"
+}
    • Changedmultiread5 fields changed
      • addedInput schema / properties / encoding
        Added value: +{
+  "description": "Default charset override, e.g. EUC-KR or CP949; files entries may override it; BOM takes priority",
+  "type": "string"
+}
      • addedInput schema / properties / files / items / properties / encoding
        Added value: +{
+  "description": "Per-file charset override; otherwise inherits global encoding; BOM takes priority",
+  "type": "string"
+}
      • changedInput schema / properties / max_output_chars / description
        Previous value: -"Maximum total returned text characters across all files. Default: 32768, Max: 131072"New value: +"Maximum total returned text characters across all files. Default: 32768, Min: 256, Max: 131072"
      • addedInput schema / properties / resume_offset
        Added value: +{
+  "description": "Override offset only for start_file_index; other files retain their original ranges",
+  "type": [
+    "null",
+    "integer"
+  ]
+}
      • addedInput schema / properties / start_file_index
        Added value: +{
+  "description": "Resume at this 1-based index in the original file list; default 1",
+  "type": "integer"
+}
    • Changedpatch2 fields changed
      • addedInput schema / properties / encoding
        Added value: +{
+  "description": "Charset override, e.g. CP949; overrides .editorconfig, BOM takes priority",
+  "type": "string"
+}
      • addedInput schema / properties / expected_hash
        Added value: +{
+  "description": "Expected raw-file SHA-256; mismatch rejects the patch",
+  "type": "string"
+}
    • Changedread2 fields changed
      • addedInput schema / properties / encoding
        Added value: +{
+  "description": "Charset override, e.g. EUC-KR or Shift_JIS; overrides .editorconfig, BOM takes priority",
+  "type": "string"
+}
      • changedInput schema / properties / max_output_chars / description
        Previous value: -"Output character cap; default 32768, max 131072"New value: +"Output character cap; default 32768, min 256, max 131072"
    • Changedtoolbox1 field changed
      • changedInput schema / properties / profile / description
        Previous value: -"Profile to add; core-lite, core, coding, remote, analysis, or full. core-lite is smallest at startup"New value: +"Profile to add: core-lite, core, coding, remote, analysis, or full; append +tool names for extra tools"
    • Changedwrite1 field changed
      • addedInput schema / properties / encoding
        Added value: +{
+  "description": "Charset override, e.g. EUC-KR or Shift_JIS; overrides .editorconfig, existing BOM takes priority",
+  "type": "string"
+}
  2. 1 tool updatev1.0.2
    • Changedagent_tool_help1 field changed
      • changedInput schema / properties / topic / description
        Previous value: -"Help topic. Available: overview, encoding, indentation, tools, debug, analyze, memtool, wintool, codegraph, ipc, troubleshooting. Empty = overview"New value: +"Help topic. Available: overview, encoding, indentation, tools, debug, analyze, memtool, wintool, codegraph, troubleshooting. Empty = overview"
  3. 6 tool updatesv0.9.7
    • Changededit6 fields changed
      • changedInput schema / properties / dry_run / description
        Previous value: -"Preview changes without modifying the file: true or false. Default: false"New value: +"Preview only; default false"
      • changedInput schema / properties / expected_hash / description
        Previous value: -"Optional SHA-256 hash of the file. If provided and mismatched, edit is rejected (optimistic concurrency)."New value: +"Expected SHA-256; mismatch rejects edit"
      • changedInput schema / properties / file_path / description
        Previous value: -"File to edit. Relative paths use the configured workspace or MCP client root"New value: +"File path; relative to workspace/MCP root"
      • changedInput schema / properties / indent_style / description
        Previous value: -"Override indentation style. Values: tabs or spaces-N (e.g. spaces-4). Empty = auto-detect (default)"New value: +"tabs or spaces-N; default auto-detect"
      • changedInput schema / properties / new_string / description
        Previous value: -"Replacement text (must differ from old_string)"New value: +"Replacement text; must differ from old_string"
      • changedInput schema / properties / replace_all / description
        Previous value: -"Replace all occurrences instead of just the first: true or false. Default: false"New value: +"Replace every match; default false"
    • Changedglob1 field changed
      • changedInput schema / properties / include_ignored / description
        Previous value: -"Traverse generated/vendor directories such as node_modules, vendor, target, build, and dist. Default: false"New value: +"Include paths excluded by .gitignore/.ignore or the common generated/vendor policy. Default: false"
    • Changedgrep17 fields changed
      • changedInput schema / properties / after / description
        Previous value: -"Lines after each match. Overrides context. Default: 0, Max: 1000"New value: +"Lines after; overrides context"
      • changedInput schema / properties / before / description
        Previous value: -"Lines before each match. Overrides context. Default: 0, Max: 1000"New value: +"Lines before; overrides context"
      • changedInput schema / properties / context / description
        Previous value: -"Lines before and after each match (like grep -C). Default: 0, Max: 1000"New value: +"Lines before/after; max 1000"
      • changedInput schema / properties / cursor / description
        Previous value: -"Opaque continuation cursor returned by a previous grep call. Not supported with context lines"New value: +"Continuation cursor; incompatible with context lines"
      • changedInput schema / properties / glob / description
        Previous value: -"Glob pattern to filter files (e.g. *.go). Only used when path is a directory"New value: +"Directory file filter, e.g. *.go"
      • changedInput schema / properties / ignore_case / description
        Previous value: -"Case-insensitive search. Default: false"New value: +"Ignore case"
      • changedInput schema / properties / include_hidden / description
        Previous value: -"Search hidden directories. Explicitly provided hidden roots are always searched. Default: false"New value: +"Include hidden directories"
      • changedInput schema / properties / include_ignored / description
        Previous value: -"Search common generated/vendor directories instead of skipping them. Default: false"New value: +"Include ignored/generated/vendor paths"
      • changedInput schema / properties / max_line_chars / description
        Previous value: -"Maximum characters per matching/context line. Default: 4000, Max: 32768"New value: +"Per-line cap; default 4000, max 32768"
      • changedInput schema / properties / max_output_chars / description
        Previous value: -"Maximum total result characters. Default: 32768, Max: 131072"New value: +"Output cap; default 32768, max 131072"
      • changedInput schema / properties / max_results / description
        Previous value: -"Maximum matching lines/files per page. Default: 100, Max: 100000"New value: +"Matches per page; default 100, max 100000"
      • changedInput schema / properties / output_format / description
        Previous value: -"Content layout: compact (group matches by file, default) or classic (path:line:text on every line)"New value: +"compact (default) or classic path:line:text"
      • changedInput schema / properties / output_mode / description
        Previous value: -"Output mode: content (default), files_with_matches, or count"New value: +"content (default), files_with_matches, or count"
      • changedInput schema / properties / path / description
        Previous value: -"File or directory to search. Defaults to configured workspace, MCP client root, or current directory"New value: +"File or directory; defaults to workspace/MCP root/CWD"
      • changedInput schema / properties / pattern / description
        Previous value: -"Regular expression pattern to search for"New value: +"Regular expression"
      • changedInput schema / properties / recursive / description
        Previous value: -"Recurse into subdirectories. Default: true"New value: +"Recurse; default true"
      • changedInput schema / properties / relative_paths / description
        Previous value: -"Return paths relative to the search root. Default: true for directory searches"New value: +"Paths relative to root; directory default true"
    • Changedread11 fields changed
      • changedInput schema / properties / all / description
        Previous value: -"Remove the default line limit. The max_output_chars safety budget still applies. Default: false"New value: +"Disable line cap; character cap remains"
      • changedInput schema / properties / end_line / description
        Previous value: -"Inclusive end line used with start_line"New value: +"Inclusive end with start_line"
      • changedInput schema / properties / file_path / description
        Previous value: -"Absolute or workspace-relative path to the file to read"New value: +"Absolute or workspace/MCP-root-relative file path"
      • changedInput schema / properties / include_hash / description
        Previous value: -"Include SHA-256 for optimistic edit concurrency. Default: true"New value: +"Include SHA-256; default true"
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum lines to return. Default: 400. Set 0 or all=true to remove the line limit; the character budget still applies"New value: +"Line limit; default 400. Use 0 or all=true for no line cap"
      • changedInput schema / properties / max_line_chars / description
        Previous value: -"Maximum characters returned from one line. Default: 4000, Max: 32768"New value: +"Per-line character cap; default 4000, max 32768"
      • changedInput schema / properties / max_output_chars / description
        Previous value: -"Maximum returned text characters. Default: 32768, Max: 131072"New value: +"Output character cap; default 32768, max 131072"
      • changedInput schema / properties / offset / description
        Previous value: -"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 1"New value: +"Start line: 1-based integer, negative from end, 'start-end', or [start,end]; default 1"
      • addedInput schema / properties / offset / type
        Added value: +"integer"
      • changedInput schema / properties / path / description
        Previous value: -"Compatibility alias for file_path; prefer file_path"New value: +"Alias for file_path"
      • changedInput schema / properties / start_line / description
        Previous value: -"Compatibility alias for offset; prefer offset"New value: +"Alias for offset"
    • Changedtoolbox12 fields changed
      • changedInput schema / properties / arguments / description
        Previous value: -"Target tool arguments for operation=call. Use operation=describe first when the schema is unknown"New value: +"Target arguments for call; describe first if unknown"
      • changedInput schema / properties / compact / description
        Previous value: -"Return a reduced input schema: true or false. Pair with tool_operation for operation-specific fields"New value: +"Return a reduced describe schema"
      • changedInput schema / properties / groups / description
        Previous value: -"Tool groups to enable or disable: core, file, coding, system, remote, data, analysis, windows"New value: +"Groups for enable/disable: core, file, coding, system, remote, data, analysis, windows"
      • changedInput schema / properties / operation / description
        Previous value: -"Operation: list (default), describe, call, output, enable, disable, profile. Prefer describe/call because they work even when the MCP client ignores dynamic tool-list changes"New value: +"list (default), describe, call, output, enable, disable, or profile"
      • changedInput schema / properties / output_id / description
        Previous value: -"Preserved raw command output ID for operation=output"New value: +"Raw output ID for output"
      • changedInput schema / properties / output_max_chars / description
        Previous value: -"Maximum raw-output characters returned by operation=output. Default: 32768, Max: 130048"New value: +"Output character limit; default 32768, max 130048"
      • changedInput schema / properties / output_offset / description
        Previous value: -"Character offset for operation=output paging. Default: 0"New value: +"Output character offset; default 0"
      • changedInput schema / properties / profile / description
        Previous value: -"Profile for operation=profile: core, coding, remote, analysis, full"New value: +"Profile to add; core-lite, core, coding, remote, analysis, or full. core-lite is smallest at startup"
      • changedInput schema / properties / schema_handle / description
        Previous value: -"Handle returned by an earlier describe; matching handles return only an unchanged acknowledgement"New value: +"Prior handle; short acknowledgement if unchanged"
      • changedInput schema / properties / tool / description
        Previous value: -"Single tool name for operation=describe or call"New value: +"Target tool for describe/call"
      • changedInput schema / properties / tool_operation / description
        Previous value: -"Target tool operation for compact describe, for example execute or upload"New value: +"Operation-specific compact schema, e.g. execute"
      • changedInput schema / properties / tools / description
        Previous value: -"Individual tool names to enable or disable"New value: +"Tool names for enable/disable"
    • Changedwrite1 field changed
      • changedInput schema / properties / file_path / description
        Previous value: -"File to write. Relative paths use the configured workspace or MCP client root"New value: +"File path; relative to workspace/MCP root"
  4. 1 tool updatev0.9.6
    • Changedtoolbox3 fields changed
      • addedInput schema / properties / compact
        Added value: +{
+  "description": "Return a reduced input schema: true or false. Pair with tool_operation for operation-specific fields",
+  "type": "boolean"
+}
      • addedInput schema / properties / schema_handle
        Added value: +{
+  "description": "Handle returned by an earlier describe; matching handles return only an unchanged acknowledgement",
+  "type": "string"
+}
      • addedInput schema / properties / tool_operation
        Added value: +{
+  "description": "Target tool operation for compact describe, for example execute or upload",
+  "type": "string"
+}
  5. 53 tool updatesv0.9.5
    • Removedanalyze
    • Removedbackup
    • Removedbash
    • Removedchecksum
    • Removedcodegraph
    • Removedcompress
    • Removedconvert_encoding
    • Removedcopy
    • Removeddebug
    • Removeddecompress
    • Removeddelete
    • Removeddiff
    • Removeddnslookup
    • Removeddownload
    • Changededit3 fields changed
      • addedInput schema / properties / dry_run / type
        Added value: +"boolean"
      • changedInput schema / properties / file_path / description
        Previous value: -"Absolute path to the file to edit"New value: +"File to edit. Relative paths use the configured workspace or MCP client root"
      • addedInput schema / properties / replace_all / type
        Added value: +"boolean"
    • Removedenvvar
    • Removedexternalip
    • Removedfile_info
    • Removedfind_tools
    • Removedfirewall
    • Changedglob8 fields changed
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Opaque continuation cursor returned by a previous glob call",
+  "type": "string"
+}
      • addedInput schema / properties / include_hidden
        Added value: +{
+  "description": "Traverse hidden directories. Explicit hidden roots are always searched. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / include_ignored
        Added value: +{
+  "description": "Traverse generated/vendor directories such as node_modules, vendor, target, build, and dist. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / limit
        Added value: +{
+  "description": "Maximum paths returned per page. Default: 200, Max: 5000",
+  "type": "integer"
+}
      • addedInput schema / properties / max_output_chars
        Added value: +{
+  "description": "Maximum returned text characters. Default: 32768, Max: 131072",
+  "type": "integer"
+}
      • changedInput schema / properties / path / description
        Previous value: -"Directory to search in (absolute path). Defaults to current directory if empty"New value: +"Directory to search. Defaults to configured workspace, MCP client root, or current directory"
      • changedInput schema / properties / relative_paths / description
        Previous value: -"Return paths relative to the search directory instead of absolute paths. Saves tokens in output: true or false. Default: false"New value: +"Return paths relative to the search directory. Default: true"
      • addedInput schema / properties / relative_paths / type
        Added value: +[
+  "null",
+  "boolean"
+]
    • Changedgrep21 fields changed
      • changedInput schema / properties / after / description
        Previous value: -"Lines of context after each match (like grep -A). Overrides context. Default: 0"New value: +"Lines after each match. Overrides context. Default: 0, Max: 1000"
      • addedInput schema / properties / after / type
        Added value: +"integer"
      • changedInput schema / properties / before / description
        Previous value: -"Lines of context before each match (like grep -B). Overrides context. Default: 0"New value: +"Lines before each match. Overrides context. Default: 0, Max: 1000"
      • addedInput schema / properties / before / type
        Added value: +"integer"
      • changedInput schema / properties / context / description
        Previous value: -"Lines of context before and after each match (like grep -C). Default: 0"New value: +"Lines before and after each match (like grep -C). Default: 0, Max: 1000"
      • addedInput schema / properties / context / type
        Added value: +"integer"
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Opaque continuation cursor returned by a previous grep call. Not supported with context lines",
+  "type": "string"
+}
      • changedInput schema / properties / ignore_case / description
        Previous value: -"Case insensitive search: true or false. Default: false"New value: +"Case-insensitive search. Default: false"
      • addedInput schema / properties / ignore_case / type
        Added value: +"boolean"
      • addedInput schema / properties / include_hidden
        Added value: +{
+  "description": "Search hidden directories. Explicitly provided hidden roots are always searched. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / include_ignored
        Added value: +{
+  "description": "Search common generated/vendor directories instead of skipping them. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / max_line_chars
        Added value: +{
+  "description": "Maximum characters per matching/context line. Default: 4000, Max: 32768",
+  "type": "integer"
+}
      • addedInput schema / properties / max_output_chars
        Added value: +{
+  "description": "Maximum total result characters. Default: 32768, Max: 131072",
+  "type": "integer"
+}
      • changedInput schema / properties / max_results / description
        Previous value: -"Maximum number of matching lines/files to return. Default: 100"New value: +"Maximum matching lines/files per page. Default: 100, Max: 100000"
      • addedInput schema / properties / max_results / type
        Added value: +"integer"
      • addedInput schema / properties / output_format
        Added value: +{
+  "description": "Content layout: compact (group matches by file, default) or classic (path:line:text on every line)",
+  "type": "string"
+}
      • changedInput schema / properties / output_mode / description
        Previous value: -"Output mode: 'content' (matching lines with path:line:text, default), 'files_with_matches' (file paths only), 'count' (match count per file)"New value: +"Output mode: content (default), files_with_matches, or count"
      • changedInput schema / properties / path / description
        Previous value: -"File or directory to search in (absolute path). Defaults to current directory"New value: +"File or directory to search. Defaults to configured workspace, MCP client root, or current directory"
      • changedInput schema / properties / recursive / description
        Previous value: -"Recurse into subdirectories: true or false. Default: true"New value: +"Recurse into subdirectories. Default: true"
      • addedInput schema / properties / recursive / type
        Added value: +[
+  "null",
+  "boolean"
+]
      • addedInput schema / properties / relative_paths
        Added value: +{
+  "description": "Return paths relative to the search root. Default: true for directory searches",
+  "type": [
+    "null",
+    "boolean"
+  ]
+}
    • Removedhttpreq
    • Removedipc
    • Removedjsonquery
    • Changedlistdir12 fields changed
      • addedInput schema / properties / counts_only
        Added value: +{
+  "description": "Return matching directory/file counts without listing names: true or false. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Opaque continuation cursor returned by a previous listdir call",
+  "type": "string"
+}
      • addedInput schema / properties / directories_only
        Added value: +{
+  "description": "Return directories only while still traversing them: true or false. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / files_only
        Added value: +{
+  "description": "Return files only: true or false. Default: false",
+  "type": "boolean"
+}
      • addedInput schema / properties / include
        Added value: +{
+  "description": "Additional entry-name glob patterns. An entry is included when any pattern matches",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}
      • changedInput schema / properties / max_depth / description
        Previous value: -"Maximum depth for tree traversal. Default: 3"New value: +"Maximum depth for traversal. Default: 3"
      • addedInput schema / properties / max_depth / type
        Added value: +"integer"
      • addedInput schema / properties / max_entries
        Added value: +{
+  "description": "Maximum entries to return per page. Default: 500, maximum: 10000",
+  "type": "integer"
+}
      • addedInput schema / properties / name_pattern
        Added value: +{
+  "description": "Glob matched against each entry name, for example A* or *.go",
+  "type": "string"
+}
      • changedInput schema / properties / path / description
        Previous value: -"Absolute path to the directory to list"New value: +"Directory to list. Relative paths use the configured workspace or MCP client root"
      • changedInput schema / properties / relative_paths / description
        Previous value: -"Show the root as '.' instead of the full absolute path. Saves tokens in output: true or false. Default: false"New value: +"Show paths relative to the root. Saves tokens: true or false. Default: false"
      • addedInput schema / properties / relative_paths / type
        Added value: +"boolean"
    • Removedmemtool
    • Removedmkdir
    • Changedmultiedit2 fields changed
      • addedInput schema / properties / dry_run / type
        Added value: +"boolean"
      • changedInput schema / properties / file_path / description
        Previous value: -"Absolute path to the file to edit"New value: +"File to edit. Relative paths use the configured workspace or MCP client root"
    • Changedmultiread14 fields changed
      • addedInput schema / properties / all
        Added value: +{
+  "description": "Remove the default per-file line limit. The total character budget still applies. Default: false",
+  "type": "boolean"
+}
      • changedInput schema / properties / file_paths / description
        Previous value: -"List of absolute file paths to read. All files use the global offset/limit. Use 'files' instead for per-file ranges"New value: +"File paths to read. All files use the global offset/limit. Use files for per-file ranges"
      • changedInput schema / properties / files / items / properties / limit / description
        Previous value: -"Max lines to read. Default: 0 (all)"New value: +"Max lines to read. Default: 200. Set 0 to remove the line limit"
      • addedInput schema / properties / files / items / properties / limit / type
        Added value: +[
+  "null",
+  "integer"
+]
      • addedInput schema / properties / files / items / properties / offset / type
        Added value: +[
+  "null",
+  "integer"
+]
      • changedInput schema / properties / files / items / properties / path / description
        Previous value: -"Absolute file path"New value: +"Absolute or workspace-relative file path"
      • addedInput schema / properties / include_hash
        Added value: +{
+  "description": "Include per-file SHA-256 hashes. Default: false",
+  "type": "boolean"
+}
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum number of lines to read per file. Default: 0 (all)"New value: +"Maximum lines per file. Default: 200. Set 0 or all=true to remove the line limit"
      • addedInput schema / properties / limit / type
        Added value: +[
+  "null",
+  "integer"
+]
      • addedInput schema / properties / max_line_chars
        Added value: +{
+  "description": "Maximum characters returned from one line. Default: 4000, Max: 32768",
+  "type": "integer"
+}
      • addedInput schema / properties / max_output_chars
        Added value: +{
+  "description": "Maximum total returned text characters across all files. Default: 32768, Max: 131072",
+  "type": "integer"
+}
      • changedInput schema / properties / offset / description
        Previous value: -"Line number to start reading from (1-based). Negative = from end (e.g. -5 = last 5 lines). Default: 1"New value: +"Line number to start from (1-based, negative = from end). Default: 1"
      • addedInput schema / properties / offset / type
        Added value: +[
+  "null",
+  "integer"
+]
      • changedInput schema / properties / paths / description
        Previous value: -"Alias for file_paths"New value: +"Compatibility alias for file_paths; prefer file_paths"
    • Removedmysql
    • Changedpatch2 fields changed
      • addedInput schema / properties / dry_run / type
        Added value: +"boolean"
      • changedInput schema / properties / file_path / description
        Previous value: -"Absolute path to the file to patch"New value: +"File to patch. Relative paths use the configured workspace or MCP client root"
    • Removedportcheck
    • Removedprocexec
    • Removedprockill
    • Removedproclist
    • Changedread13 fields changed
      • addedInput schema / properties / all
        Added value: +{
+  "description": "Remove the default line limit. The max_output_chars safety budget still applies. Default: false",
+  "type": "boolean"
+}
      • changedInput schema / properties / end_line / description
        Previous value: -"End line number (1-based, inclusive). Sets limit = end_line - start_line + 1 when used with start_line"New value: +"Inclusive end line used with start_line"
      • addedInput schema / properties / end_line / type
        Added value: +[
+  "null",
+  "integer"
+]
      • changedInput schema / properties / file_path / description
        Previous value: -"Absolute or relative path to the file to read"New value: +"Absolute or workspace-relative path to the file to read"
      • addedInput schema / properties / include_hash
        Added value: +{
+  "description": "Include SHA-256 for optimistic edit concurrency. Default: true",
+  "type": [
+    "null",
+    "boolean"
+  ]
+}
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum number of lines to read. Default: 0 (all)"New value: +"Maximum lines to return. Default: 400. Set 0 or all=true to remove the line limit; the character budget still applies"
      • addedInput schema / properties / limit / type
        Added value: +[
+  "null",
+  "integer"
+]
      • addedInput schema / properties / max_line_chars
        Added value: +{
+  "description": "Maximum characters returned from one line. Default: 4000, Max: 32768",
+  "type": "integer"
+}
      • addedInput schema / properties / max_output_chars
        Added value: +{
+  "description": "Maximum returned text characters. Default: 32768, Max: 131072",
+  "type": "integer"
+}
      • changedInput schema / properties / offset / description
        Previous value: -"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 0 (all)"New value: +"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 1"
      • changedInput schema / properties / path / description
        Previous value: -"Alias for file_path"New value: +"Compatibility alias for file_path; prefer file_path"
      • changedInput schema / properties / start_line / description
        Previous value: -"Alias for offset (1-based line number to start reading from)"New value: +"Compatibility alias for offset; prefer offset"
      • addedInput schema / properties / start_line / type
        Added value: +[
+  "null",
+  "integer"
+]
    • Removedredis
    • Removedregexreplace
    • Removedrename
    • Removedset_config
    • Removedsftp
    • Removedsloc
    • Removedssh
    • Removedsysinfo
    • Removedtlscheck
    • Removedtomlquery
    • Addedtoolbox
    • Removedwebfetch
    • Removedwebsearch
    • Removedwintool
    • Changedwrite1 field changed
      • changedInput schema / properties / file_path / description
        Previous value: -"Absolute path to the file to write"New value: +"File to write. Relative paths use the configured workspace or MCP client root"
    • Removedyamlquery
  6. 53 tool updatesv0.8.7
    • Addedagent_tool_help
    • Addedanalyze
    • Addedbackup
    • Addedbash
    • Addedchecksum
    • Addedcodegraph
    • Addedcompress
    • Addedconvert_encoding
    • Addedcopy
    • Addeddebug
    • Addeddecompress
    • Addeddelete
    • Addeddiff
    • Addeddnslookup
    • Addeddownload
    • Addededit
    • Addedenvvar
    • Addedexternalip
    • Addedfile_info
    • Addedfind_tools
    • Addedfirewall
    • Addedglob
    • Addedgrep
    • Addedhttpreq
    • Addedipc
    • Addedjsonquery
    • Addedlistdir
    • Addedmemtool
    • Addedmkdir
    • Addedmultiedit
    • Addedmultiread
    • Addedmysql
    • Addedpatch
    • Addedportcheck
    • Addedprocexec
    • Addedprockill
    • Addedproclist
    • Addedread
    • Addedredis
    • Addedregexreplace
    • Addedrename
    • Addedset_config
    • Addedsftp
    • Addedsloc
    • Addedssh
    • Addedsysinfo
    • Addedtlscheck
    • Addedtomlquery
    • Addedwebfetch
    • Addedwebsearch
    • Addedwintool
    • Addedwrite
    • Addedyamlquery
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.8/5.0

Scored across 11 tools

Disambiguation4/5

Most tools have clear, distinct purposes: read vs multiread and edit vs multiedit vs patch are well differentiated by their descriptions (single vs multi vs diff-based). The only mild overlaps are read/multiread and the meta-tools toolbox vs agent_tool_help, but descriptions clarify the boundaries. glob, grep, and listdir target distinct operations (pattern-find, content-search, listing).

Naming Consistency3/5

Conventions are mixed: bare verbs (read, write, edit, grep), nouns (glob, patch, toolbox), and one snake_case name (agent_tool_help) sit side by side. The multiedit/multiread prefix shows some internal logic, but there is no single predictable verb_noun pattern across the set. It remains readable but not uniform.

Tool Count5/5

11 tools is squarely within the ideal 3-15 range and each tool earns its place covering reading, writing, editing, patching, searching, listing, and discovery. No redundant or filler tools are present for the scope of a file/code agent toolkit.

Completeness4/5

The core file lifecycle is well covered (read, write, edit, multiedit, patch, glob, grep, listdir, toolbox, help). However, there is no delete/remove and no move/rename operation, which are genuine lifecycle gaps an agent may need. These are minor and often workable around, so coverage is strong but not complete.

Maintenance

ActivityActive
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • ABSD DevOps MCP Server

    anthonybir
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables secure local filesystem operations and interactive terminal sessions for AI assistants. Provides 12 tools for file management, directory operations, code searching, and running interactive REPLs with security protections.
    12 npm
    MIT

  • @rog0x/mcp-file-tools

    rog0x
    A
    license
    A
    quality
    D
    maintenance
    Enables AI agents to explore, analyze, and search file systems, with tools for directory trees, file statistics, duplicate detection, code counting, and multi-criteria file search.
    5
    45 npm
    MIT

Appeared in Searches