de en es ja ko ru zh

Semantic Cache MCP

Name: Semantic Cache MCP
Author: CoderDayton

by CoderDayton

Overview Schema Related Servers Score Discussions

Python

Local

Cut your MCP client's token usage by 98% on cached reads. Respond in milliseconds.

Semantic Cache MCP is a Model Context Protocol server that replaces redundant full-file reads with marker hits, unified diffs, and semantic summaries. Thirteen tools (read, batch_read, write, edit, batch_edit, search, grep, glob, similar, diff, delete, clear, stats) route every file operation through one cache-aware layer, so an MCP-capable agent skips files it has already seen.

Why this exists

In order of impact:

1. Reads stop costing tokens. The first read seeds the cache. Re-reads of unchanged files return a 5-token marker (mtime match, no disk I/O). Modified files return a unified diff. Files larger than the budget collapse to a semantic skeleton that preserves structure rather than slicing at a byte offset.

2. Search and grep run on the cache, not the disk. Semantic search (hybrid BM25 + HNSW), similar-file lookup, glob, and grep all read from the same indexed corpus that read/batch_read populate. An in-session result LRU collapses repeated queries to sub-millisecond hits.

3. Mutations are bounded by default. write, edit, and batch_edit enforce size and match limits, support dry_run, can run formatters, and refresh the cache atomically. Local FastEmbed is the default embedding provider; OpenAI-compatible endpoints are opt-in.

Related MCP server: Ambiance MCP Server

Installation

Add to Claude Code settings (~/.claude.json):

Option 1 — uvx (always runs latest version):

{
  "mcpServers": {
    "semantic-cache": {
      "command": "uvx",
      "args": ["semantic-cache-mcp"]
    }
  }
}

Option 2 — uv tool install:

uv tool install semantic-cache-mcp

{
  "mcpServers": {
    "semantic-cache": {
      "command": "semantic-cache-mcp"
    }
  }
}

Restart Claude Code.

GPU Acceleration (Optional)

For NVIDIA GPU acceleration, install with the gpu extra:

uv tool install "semantic-cache-mcp[gpu]"
# or with uvx: uvx "semantic-cache-mcp[gpu]"

Then set EMBEDDING_DEVICE=gpu in your MCP config env block. Falls back to CPU automatically if CUDA is unavailable.

Custom Embedding Models

Any HuggingFace model with an ONNX export works — set EMBEDDING_MODEL in your env config:

"env": {
  "EMBEDDING_MODEL": "Snowflake/snowflake-arctic-embed-m-v2.0"
}

If the model isn't in fastembed's built-in list, it's automatically downloaded and registered from HuggingFace Hub on first startup (ONNX file integrity is verified via SHA256). See env_variables.md for model recommendations.

OpenAI-Compatible Embeddings

Local FastEmbed remains the default. To route embeddings through an OpenAI-compatible provider instead, enable it in the MCP env block. Defaults target Ollama:

"env": {
  "OPENAI_EMBEDDINGS_ENABLED": "true",
  "OPENAI_BASE_URL": "http://localhost:11434/v1",
  "OPENAI_API_KEY": "ollama",
  "OPENAI_EMBEDDING_MODEL": "nomic-embed-text"
}

Run ollama pull nomic-embed-text first if the model is not installed. For hosted OpenAI, set OPENAI_BASE_URL=https://api.openai.com/v1, use a real OPENAI_API_KEY, and choose an embedding model such as text-embedding-3-small. OPENAI_EMBEDDING_DIMENSIONS is optional; leave it unset to infer the returned vector size.

Block Native File Tools (Recommended)

Disable the client's built-in file tools so all file I/O routes through semantic-cache.

Claude Code — add to ~/.claude/settings.json:

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

OpenCode — add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "deny",
    "edit": "deny",
    "write": "deny"
  }
}

CLAUDE.md Configuration

Add to ~/.claude/CLAUDE.md to enforce semantic-cache globally:

## Tools

- MUST use `semantic-cache-mcp` instead of native I/O tools (98% token savings on cached reads)

Tools

Core

Tool	Description
`read`	Single-file cache-aware read. Returns full content on first read, unchanged markers on cache hits, diffs on modifications, and supports `offset`/`limit` for targeted recovery.
`delete`	Single-path delete for one file or symlink, with cache eviction and `dry_run=true`. Intentionally does not support globs, recursive delete, or real-directory delete.
`write`	Full-file create or replace with cache refresh. Returns creation status or an overwrite diff, supports `append=true`, and can run formatters.
`edit`	Single-file exact edit using cached content. Best for one localized change; supports scoped and line-range replacement plus `dry_run=true`.
`batch_edit`	Multiple exact edits in one file with partial success reporting. Best when several localized changes belong in the same file.

Discovery

Tool	Description
`search`	Cache-only semantic search for meaning or mixed keyword intent. Seed likely files first with `batch_read`; use `grep` for exact text.
`similar`	Cache-only nearest-neighbor lookup for one source file. Best after seeding a directory with `batch_read`.
`glob`	File discovery plus cache coverage. Use it to find candidates, then pass those paths into `batch_read`.
`batch_read`	Multi-file cache-aware read for seeding and retrieval. Handles globs, priorities, token budgets, unchanged suppression, and diff/full routing.
`grep`	Cache-only exact search with regex or literal matching, line numbers, and optional context. Best for symbols and exact strings.
`diff`	Explicit side-by-side file comparison with unified diff and semantic similarity. Use `read` instead for “what changed since last read?”.

Management

Tool	Description
`stats`	Cache metrics, session usage (tokens saved, tool calls), and lifetime aggregates.
`clear`	Reset all cache entries.

Tool Reference

The table above is the authoritative tool map. This section only shows the common call shapes.

read path="/src/app.py"                        # automatic: full, unchanged, or diff
read path="/src/app.py" offset=120 limit=80    # lines 120–199 only

Automatic three states:

State	Response	Token cost
First read	Full content + cached	Normal
Unchanged	`"File unchanged (1,234 tokens cached)"`	~5 tokens
Modified	Unified diff only	5–20% of original

write path="/src/new.py" content="..."
write path="/src/new.py" content="..." auto_format=true
write path="/src/large.py" content="...chunk1..." append=false   # first chunk
write path="/src/large.py" content="...chunk2..." append=true    # subsequent chunks

# Mode A — find/replace: searches entire file
edit path="/src/app.py" old_string="def foo():" new_string="def foo(x: int):"
edit path="/src/app.py" old_string="..." new_string="..." replace_all=true auto_format=true

# Mode B — scoped find/replace: search only within line range (shorter old_string suffices)
edit path="/src/app.py" old_string="pass" new_string="return x" start_line=42 end_line=42

# Mode C — line replace: replace entire range, no old_string needed (maximum token savings)
edit path="/src/app.py" new_string="    return result\n" start_line=80 end_line=83

Mode selection:

Mode	Parameters	Best for
Find/replace	`old_string` + `new_string`	Unique strings, no line numbers known
Scoped	`old_string` + `new_string` + `start_line`/`end_line`	Shorter context when `read` gave you line numbers
Line replace	`new_string` + `start_line`/`end_line` (no `old_string`)	Maximum token savings when line numbers are known

# Mode A — find/replace: [old, new]
batch_edit path="/src/app.py" edits='[["old1","new1"],["old2","new2"]]'

# Mode B — scoped: [old, new, start_line, end_line]
batch_edit path="/src/app.py" edits='[["pass","return x",42,42]]'

# Mode C — line replace: [null, new, start_line, end_line]
batch_edit path="/src/app.py" edits='[[null,"    return result\n",80,83]]'

# Mixed modes in one call (object syntax also supported)
batch_edit path="/src/app.py" edits='[
  ["old1", "new1"],
  {"old": "pass", "new": "return x", "start_line": 42, "end_line": 42},
  {"old": null, "new": "    return result\n", "start_line": 80, "end_line": 83}
]' auto_format=true

batch_read paths="/src/a.py,/src/b.py" max_total_tokens=50000
batch_read paths='["/src/a.py","/src/b.py"]' priority="/src/main.py"
batch_read paths="/src/*.py" max_total_tokens=30000

Expands simple globs, honors priority, enforces max_total_tokens, and reports skipped paths with recovery hints.
Unchanged files are collapsed into the summary instead of repeating content.

search query="authentication middleware logic" k=5
similar path="/src/auth.py" k=3
glob pattern="**/*.py" directory="./src" cached_only=true
grep pattern="class Cache" path="src/**/*.py"
diff path1="/src/v1.py" path2="/src/v2.py"

Configuration

Environment Variables

Variable	Default	Description
`LOG_LEVEL`	`INFO`	Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`TOOL_OUTPUT_MODE`	`compact`	Response detail (`compact`, `normal`, `debug`)
`TOOL_MAX_RESPONSE_TOKENS`	`0`	Global response token cap (`0` = disabled)
`TOOL_TIMEOUT`	`30`	Seconds before tool call times out (auto-resets executor)
`MAX_CONTENT_SIZE`	`100000`	Max bytes returned by read operations
`MAX_CACHE_ENTRIES`	`10000`	Max cache entries before LRU-K eviction
`EMBEDDING_DEVICE`	`cpu`	Embedding hardware: `cpu`, `cuda` (GPU), `auto` (detect)
`EMBEDDING_MODEL`	`BAAI/bge-small-en-v1.5`	FastEmbed model for search/similarity (options)
`OPENAI_EMBEDDINGS_ENABLED`	`false`	Use OpenAI-compatible remote embeddings instead of local FastEmbed
`OPENAI_BASE_URL`	`http://localhost:11434/v1`	OpenAI-compatible base URL; default targets Ollama
`OPENAI_API_KEY`	`ollama`	API key for the remote embedding provider
`OPENAI_EMBEDDING_MODEL`	`nomic-embed-text`	Remote embedding model name
`OPENAI_EMBEDDING_DIMENSIONS`	(inferred)	Optional requested/expected remote embedding dimension
`SEMANTIC_CACHE_DIR`	(platform)	Override cache/database directory path

See docs/env_variables.md for detailed descriptions, model selection guidance, and examples.

Safety Limits

Limit	Value	Protects Against
`MAX_WRITE_SIZE`	10 MB	Memory exhaustion via large writes
`MAX_EDIT_SIZE`	10 MB	Memory exhaustion via large file edits
`MAX_MATCHES`	10,000	CPU exhaustion via unbounded `replace_all`

MCP Server Config

{
  "mcpServers": {
    "semantic-cache": {
      "command": "uvx",
      "args": ["semantic-cache-mcp"],
      "env": {
        "LOG_LEVEL": "INFO",
        "TOOL_OUTPUT_MODE": "compact",
        "MAX_CONTENT_SIZE": "100000",
        "EMBEDDING_DEVICE": "cpu",
        "EMBEDDING_MODEL": "BAAI/bge-small-en-v1.5"
      }
    }
  }
}

Cache location: ~/.cache/semantic-cache-mcp/ (Linux), ~/Library/Caches/semantic-cache-mcp/ (macOS), %LOCALAPPDATA%\semantic-cache-mcp\ (Windows). Override with SEMANTIC_CACHE_DIR.

How It Works

┌──────────┐     ┌────────────┐     ┌──────────────────────────┐
│  Claude  │────▶│ smart_read │────▶│ stat() + cache lookup    │
│   Code   │     │            │     │ (BEFORE any disk read)   │
└──────────┘     └────────────┘     └──────────────────────────┘
                        │
       ┌────────────────┼─────────────────┬──────────────────┐
       ▼                ▼                 ▼                  ▼
 ┌──────────┐    ┌──────────┐      ┌──────────┐      ┌────────────┐
 │ mtime    │    │ mtime    │      │ Changed  │      │ New /      │
 │ match    │    │ drift,   │      │ content  │      │ Large      │
 │ FAST     │    │ hash     │      │ → diff   │      │ → summary  │
 │ PATH     │    │ match    │      │ (80-95%) │      │  or full   │
 │ ~5 tok   │    │ ~5 tok   │      └──────────┘      └────────────┘
 │ (99%)    │    │ (99%)    │
 │ ~1 ms    │    │ ~1 ms    │
 │ no I/O   │    │ +update  │
 └──────────┘    └──────────┘

search works the same way. An in-session LRU keyed on (query, k, directory) returns warm hits in ~10 µs; misses fall through to embed + BM25 + HNSW. Every cache mutation (put, clear, delete_path, update_mtime) bumps the LRU, so callers never see a result that predates a write.

Performance

Measured on this project's 43 source files (168,614 tokens), CPU embeddings, i9-13900K, commit 5cd7100. Reproducible via --json output for CI diffing.

Token savings — 98.5% overall (phases 2–6)

Phase	Scenario	Savings
Overall (cached, phases 2–6)	Aggregate token reduction	98.5%
Unchanged re-read	mtime match — fast path skips disk I/O	98.9%
Content hash	mtime drifted, BLAKE3 still matches	98.9%
Batch read	All files via `batch_read`, 200K budget	98.9%
Search previews	5 queries × k=5, previews vs full reads	98.3%
Small edits	Real ~5% line changes in 30% of files	97.3%
Cold read	First read, no cache (baseline)	0%

Latency — unchanged reads ~1 ms; repeat searches ~10 µs

Operation	p50	Notes
Single unchanged read (fast path)	1.1 ms	mtime + cache hit; no disk I/O
Single diff read (changed file)	1.0 ms	hash check + unified diff
Search k=5 (cache hit)	< 0.01 ms	in-session LRU; 2,000×+ vs cold
Search k=5 (cache miss)	5.6 ms	embed query + hybrid BM25/HNSW
Edit (scoped find/replace)	3.3 ms	uses cached content
Find similar (k=3)	2.2 ms	cached embedding reused
Grep (literal `def` )	1.4 ms	FTS5 over cached corpus
Grep (regex)	2.1 ms	regex compiled once
Batch read (43 files, diff mode)	40.2 ms	one ONNX inference for all new/changed files
Unchanged re-read (43 files)	26.9 ms	whole-corpus pass
Cold read (43 files, total)	1,990 ms	includes disk I/O, tokenisation, embedding
Write (200-line file)	49.1 ms	creates + caches + embeds
Single embedding (largest file)	47 ms	ONNX, single thread
Model warmup (one-time)	195 ms	startup only

Run benchmarks yourself:

uv run python benchmarks/benchmark_token_savings.py    # token savings
uv run python benchmarks/benchmark_performance.py      # operation latency

See docs/performance.md for full benchmarks and methodology.

Documentation

Guide	Description
Architecture	Component design, algorithms, data flow
Performance	Optimization techniques, benchmarks
Security	Threat model, input validation, size limits
Advanced Usage	Programmatic API, custom storage backends
Troubleshooting	Common issues, debug logging
Environment Variables	All configurable env vars with defaults and examples

Contributing

git clone https://github.com/CoderDayton/semantic-cache-mcp.git
cd semantic-cache-mcp
uv sync
uv run pytest

See CONTRIBUTING.md for commit conventions, pre-commit hooks, and code standards.

License

MIT License — use freely in personal and commercial projects.

Credits

Built with FastMCP 3.0 and:

FastEmbed — local ONNX embeddings (configurable, default BAAI/bge-small-en-v1.5)
SimpleVecDB ≥ 2.6.0 — HNSW vector storage with FTS5 keyword search, atomic delete_collection, and opt-in embedding persistence (store_embeddings=True)
Semantic summarization based on TCRA-LLM (arXiv:2310.15556)
BLAKE3 cryptographic hashing for content freshness
LRU-K frequency-aware cache eviction

Available Tools

13 tools

batch_editA

Apply many exact edits to one file in a single atomic call.

Preferred over repeated edit calls on the same file: one response, applied atomically, faster on large files. Partial success is allowed — any failed edits are returned with their reason so you can retry just the misses (status is edited when all apply, partial when some fail, no_changes when none do). For edits across different files, call the tool once per file.

edits is a JSON array; each entry is one of:

[old, new] — exact find/replace.
[old, new, start_line, end_line] — find/replace confined to a range.
[null, new, start_line, end_line] — replace that line range wholesale.
{"old": ..., "new": ..., "start_line": ..., "end_line": ...} — object form.

Prefer line-range entries when you already have line numbers from read.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	File path to modify (absolute, or relative to root).
`edits`	Yes	JSON array of edit entries, in any of the forms above.
`dry_run`	No	Preview without writing.
`show_diff`	No	Return the full diff even on a deterministic all-success batch.
`auto_format`	No	Run the formatter after all edits.

Output Schema

ParametersJSON Schema

Name	Required	Description
`diff`	No
`path`	No
`failed`	No
`params`	No
`status`	No
`failures`	No
`outcomes`	No
`succeeded`	No
`truncated`	No
`diff_state`	No
`diff_stats`	No
`from_cache`	No
`content_hash`	No
`diff_omitted`	No
`tokens_saved`	No

TDQS

A4.9/5.0

Behavior5/5

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

Discloses atomicity, partial success (statuses: edited, partial, no_changes), and various edit formats. No annotations provided, so description carries full burden and does so comprehensively. No contradiction with annotations (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?

Well-structured: starts with purpose, then usage advice, then behavior, then parameter details, then closing preference. Every sentence adds value; no repetition or fluff.

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?

Covers all essential aspects: atomicity, partial success, edit formats, when to use, and when not. With an output schema present, the description need not detail return values. Fully adequate for a complex tool.

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 significant value by detailing the edit entry formats (array and object forms, including line-range options), which are not fully captured in the schema's description.

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 'Apply many exact edits to one file in a single atomic call,' specifying a specific verb, resource, and scope. It distinguishes from sibling tools like 'edit' by noting it is preferred for multiple edits on the same file.

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

Usage Guidelines5/5

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

Explicit guidance on when to use this tool over repeated 'edit' calls, with rationale (atomic, faster, one response). Also specifies when to call the tool per file (different files) and explains partial success handling.

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

batch_readA

Read several files at once under a shared token budget.

The efficient way to seed the cache before search/grep, and cheaper than many single read calls. New files return full content, changed files return a diff, and files already in your context are reported as unchanged with no body. Smallest files are read first; once the budget is spent the rest are listed under skipped — recover them with read using offset/limit.

ParametersJSON Schema

Name	Required	Description
`paths`	Yes	The files to read — a comma-separated list, a JSON array, or glob patterns (expanded for you).
`priority`	No	Optional paths to read first, ahead of the remaining files.
`max_total_tokens`	No	Total token budget shared across the whole batch.

Output Schema

ParametersJSON Schema

Name	Required	Description
`files`	No
`skipped`	No
`summary`	No
`truncated`	No

TDQS

A4.7/5.0

Behavior5/5

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

Given no annotations, the description fully bears the burden of disclosing behavior. It details that the tool reads smallest files first, returns full content for new files, diffs for changed files, marks unchanged files with no body, and lists skipped files when budget is exhausted. It also suggests recovery with 'read' using offset/limit, providing comprehensive behavioral insight.

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 front-loaded with the core action, followed by efficiency rationale, then detailed behavior descriptions. Each sentence serves a purpose without redundancy; the structure is logical and easy to parse.

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

Completeness5/5

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

Given the tool's complexity and the presence of an output schema (which presumably covers return format), the description covers input behavior, edge cases (budget exhaustion, file states), and recovery options. It is sufficiently complete for an agent to understand and invoke the tool correctly.

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

Parameters4/5

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

With 100% schema coverage, baseline is 3. The description adds significant value by explaining that 'paths' accepts comma-separated lists, JSON arrays, or glob patterns (expanded), and clarifies that 'priority' reads those files first. This extra detail enhances understanding beyond the schema.

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

Purpose5/5

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

The description clearly states that the tool reads multiple files simultaneously under a shared token budget. It distinguishes itself from sibling tools like 'read' (single file) and 'grep' (search), and mentions efficiency benefits for caching before search/grep.

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

Usage Guidelines4/5

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

The description explicitly positions batch_read as the efficient choice for seeding cache and cheaper than multiple read calls. It provides guidance on when to use it (for multiple files) and hints at alternatives for skipped files (individual read with offset/limit), though it lacks explicit 'when not to use' statements.

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

clearA

Empty the cache. Does not touch any project file.

Removes every cached file entry and returns how many were dropped; the next read/batch_read re-seeds from disk. Use rarely — only to recover from stale cache state or force a cold re-seed. Normal reads already refresh changed files on their own, so this is seldom needed. Takes no arguments.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	No
`status`	No
`truncated`	No
`output_mode`	No

TDQS

A4.9/5.0

Behavior5/5

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

Discloses that it removes cached file entries, returns count, and that subsequent reads re-seed from disk. No annotations exist, so description carries full burden and does so well.

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?

Short, front-loaded sentences. First sentence captures essence; subsequent details are efficient and necessary. 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 tool with no parameters and an output schema indicating returned count, the description fully explains behavior, return value, usage context, and when to use. No gaps.

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

Parameters4/5

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

No parameters in schema, and description confirms 'Takes no arguments.' Baseline for 0 parameters is 4, and description adds clarity beyond the schema.

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

Purpose5/5

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

Description clearly states the tool empties the cache and explicitly says it does not touch project files. The action is specific (empty cache) and distinct from sibling tools which are all about file content operations.

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

Usage Guidelines5/5

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

Explicitly advises to use rarely, only for stale cache or cold re-seed, and notes that normal reads handle refreshes. This provides strong guidance on when to use vs. avoid.

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

deleteA

Delete one file or symlink and evict its cache entries.

Use this for explicit single-path removal instead of shelling out. A missing path is reported as status not_found, not an error.

Statuses: deleted (removed), would_delete (dry-run preview only), not_found (nothing was there). Constraints: one path only — no globs, no recursion, no real-directory deletes. A symlink path deletes the link itself, never its target.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	File or symlink path (absolute, or relative to the project root).
`dry_run`	No	Preview the outcome without deleting or evicting the cache.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	No
`status`	No
`deleted`	No
`dry_run`	No
`symlink`	No
`truncated`	No
`cache_removed`	No

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description fully bears the burden of disclosure. It details statuses ('deleted', 'would_delete', 'not_found'), dry-run behavior, symlink handling (deletes link, not target), and cache eviction. This is comprehensive for a simple deletion tool.

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

Conciseness5/5

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

The description is three sentences long, starting with the core purpose, then usage guidelines, then detailed statuses and constraints. Every sentence adds essential information, with no wasted words.

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

Completeness5/5

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

Given the tool's low complexity (2 parameters, simple file deletion) and the presence of an output schema, the description covers all necessary behavioral aspects: what happens on success, failure, dry-run, and symlinks. No gaps remain.

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

Parameters4/5

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

The input schema covers both parameters with 100% description coverage. The description adds value beyond the schema by introducing cache eviction context, status codes for dry-run, and the 'one path only' constraint. This enriches the agent's understanding without being redundant.

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 'Delete one file or symlink and evict its cache entries.' It specifies the action (delete), the resource (file or symlink), and additional behavior (cache eviction). It distinguishes from sibling tools by noting constraints like 'one path only — no globs, no recursion, no real-directory deletes.'

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

Usage Guidelines4/5

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

The description explicitly advises 'Use this for explicit single-path removal instead of shelling out,' providing a clear usage context. It also lists constraints that indicate when not to use this tool (directories, globs, recursion). However, it does not explicitly mention alternative sibling tools for those cases.

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

editA

Edit one file by exact text replacement.

Three modes:

find/replace: old_string + new_string (the default).
scoped: add start_line/end_line to confine the search to a range.
line-range: omit old_string and give both lines to replace them wholesale.

old_string must match exactly — whitespace and indentation included — and, unless replace_all=true, must be unique, or the edit fails. Use edit_preview first if you're unsure an anchor is unique. Returns the replacement count, affected line numbers, and a unified diff, and refreshes the cache. For several edits to one file use batch_edit; for a full rewrite use write.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	File path to modify (absolute, or relative to root).
`dry_run`	No	Preview without writing.
`end_line`	No	1-based inclusive end line for a scoped or line-range edit.
`show_diff`	No	Return the diff even on a deterministic edit.
`new_string`	No	Replacement text (an empty string deletes the match).
`old_string`	No	Exact text to find. Omit only for a line-range replacement.
`start_line`	No	1-based inclusive start line for a scoped or line-range edit.
`auto_format`	No	Run the formatter after editing.
`replace_all`	No	Replace every occurrence instead of requiring a unique match.

Output Schema

ParametersJSON Schema

Name	Required	Description
`diff`	No
`path`	No
`params`	No
`status`	No
`replaced`	No
`truncated`	No
`diff_state`	No
`diff_stats`	No
`from_cache`	No
`content_hash`	No
`diff_omitted`	No
`line_numbers`	No
`tokens_saved`	No

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: exact match requirement, uniqueness unless replace_all=true, return value (count, line numbers, diff), and cache refresh. No contradictions.

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

Conciseness5/5

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

Well-structured with clear sections, front-loaded purpose, and no wasted words. Every sentence adds value.

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

Completeness5/5

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

For a complex tool with 9 parameters and multiple modes, the description fully covers purpose, usage, parameter interactions, and return value. Adequate given output schema exists.

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% (baseline 3), but the description adds meaning beyond schema by explaining interaction of parameters in three modes and behavior of replace_all and empty new_string.

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

Purpose5/5

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

The description clearly states it edits one file by exact text replacement, and explicitly distinguishes from siblings like batch_edit (for multiple edits) and write (for full rewrite).

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?

Provides explicit when-to-use guidance for three modes, recommends using edit_preview for uniqueness checking, and names batch_edit and write as alternatives for different needs.

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

edit_previewA

Show where old_string would match in a file, without editing it.

Returns the match count, 1-based line numbers, and short snippets so you can confirm an anchor is unique before calling edit. Read-only and cheap (kept under ~200 tokens), so use it freely as a probe. Raises an error on a binary file or an empty old_string.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	File path to search (absolute, or relative to root).
`old_string`	Yes	Anchor text to locate. Must match exactly, including whitespace and indentation. Cannot be empty.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	No
`found`	No
`context`	No
`truncated`	No
`match_count`	No
`line_numbers`	No

TDQS

A4.7/5.0

Behavior5/5

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

No annotations provided, but the description fully discloses behavior: read-only, cheap (~200 tokens), returns match count/line numbers/snippets, raises errors on binary files or empty old_string. This is thorough and exceeds the burden.

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 sentences, front-loaded with purpose, no wasted words. Each sentence earns its place with specific information about behavior, usage, and limitations.

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

Completeness5/5

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

Given simple tool with 2 params and high schema coverage, description covers all essential aspects: purpose, usage guidance, behavioral details, error conditions, and return values. No gaps.

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 has 100% coverage, and description adds extra nuance: old_string 'must match exactly, including whitespace and indentation' and 'Cannot be empty.' Path clarification 'absolute, or relative to root' adds value beyond schema.

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

Purpose5/5

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

The description clearly states 'Show where `old_string` would match in a file, without editing it.' This is a specific verb-resource combination and distinguishes from sibling `edit` which performs actual edits.

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

Usage Guidelines4/5

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

Explicitly advises 'use it freely as a probe' and 'confirm an anchor is unique before calling `edit`.' Provides context for when to use, though does not explicitly list when not to use (implied by contrast with `edit` and `grep`).

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

globA

List files matching a glob and show which are already cached.

Use it to discover files and see what search/grep can already access before you spend reads. Each match carries a cached flag; set cached_only=true to list only files already in the cache. Pair it with batch_read to pull in whatever isn't cached yet.

ParametersJSON Schema

Name	Required	Description	Default
`pattern`	Yes	Glob pattern to match (e.g. `src/*/.py`).
`directory`	No	Base directory the pattern is evaluated from.	.
`cached_only`	No	Return only files that are already cached.

Output Schema

ParametersJSON Schema

Name	Required	Description
`matches`	No
`pattern`	No
`directory`	No
`truncated`	No
`cached_count`	No
`total_matches`	No
`total_cached_tokens`	No

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses that each match has a 'cached' flag and that setting 'cached_only=true' filters results. It implies the tool is read-only and low-cost by saying 'before you spend reads'. This adds value beyond a simple 'list files' definition, though it could be more explicit about side effects or permissions.

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

Conciseness5/5

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

The description is three sentences with no waste. The first sentence states the purpose, the second provides usage guidance and explains a key feature (cached flag), and the third suggests a complementary tool. Every sentence earns its place, and the most important information is front-loaded.

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

Completeness5/5

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

Given the tool's simplicity (3 parameters, all described, output schema exists), the description is complete. It covers the tool's purpose, usage context, key feature (cached flag), and suggests a workflow with 'batch_read'. There are no missing aspects for an agent to correctly select and invoke this tool.

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 context by explaining the 'cached' flag and how 'cached_only' works ('set cached_only=true to list only files already in the cache'). It also provides usage context for the parameters, making them more meaningful than the schema 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 starts with 'List files matching a glob and show which are already cached', clearly stating the verb (list) and resource (files matching a glob). It also differentiates from sibling tools 'search' and 'grep' by mentioning that the tool shows what is already cached, helping the agent decide when to use it.

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

Usage Guidelines4/5

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

The description explicitly advises: 'Use it to discover files and see what search/grep can already access before you spend reads.' It also suggests pairing with 'batch_read' to handle uncached files. While it does not list explicit alternatives or exclusions, the context is clear enough for an agent to understand when this tool is appropriate.

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

grepA

Search cached file contents for an exact string or regex.

Fast, exact, line-numbered matching over files already in the cache — it does NOT touch disk, so seed files first with batch_read/read (empty results usually mean the files aren't cached). For concept-level questions where you don't know the exact term, use search instead.

ParametersJSON Schema

Name	Required	Description
`path`	No	Optional filter — an exact path, a path suffix, or a glob.
`pattern`	Yes	A regular expression, or a literal string when `fixed_string=true`.
`max_files`	No	Cap on the number of files returned.
`max_matches`	No	Cap on total matches returned across all files.
`fixed_string`	No	Match `pattern` literally instead of as a regex.
`context_lines`	No	Lines of surrounding context to include per match.
`case_sensitive`	No	Match case-sensitively.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	No
`files`	No
`pattern`	No
`truncated`	No
`fixed_string`	No
`context_lines`	No
`files_matched`	No
`total_matches`	No
`case_sensitive`	No
`truncated_files`	No
`truncated_matches`	No

TDQS

A4.9/5.0

Behavior5/5

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

Discloses key behaviors: operates on cache only, does not touch disk, returns line-numbered results, and empty results likely mean files aren't cached. No annotations present, so full burden carried.

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 succinct paragraphs with front-loaded purpose. Every sentence adds value; no redundant or filler content.

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

Completeness5/5

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

Given 7 parameters and caching behavior, the description fully explains prerequisites, limitations, and alternatives. Output schema exists, so return values not needed.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the caching context for parameter usage, enhancing understanding beyond the schema.

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

Purpose5/5

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

The description clearly states the tool searches cached file contents for an exact string or regex, specifying 'cached' and distinguishing from the sibling 'search' tool for concept-level queries.

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

Usage Guidelines5/5

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

Explicitly tells when to use: for exact matching on cached files. Provides prerequisite: seed files with batch_read/read. Gives alternative: use search for concept-level questions.

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

readA

Read a file, returning as few tokens as possible. For 2+ files, use batch_read.

The first read returns the full numbered content plus a content_hash. A later read of an unchanged file returns "unchanged": true with no body (you already have it); a changed file returns a unified diff. Reading also caches the file so grep, search, and batch_read can see it.

Whenever you re-read a file you have read before, pass back known_hash (the content_hash from your last read of it). It is the server's only proof that you still hold the content, so use it every time you can; the server then skips re-sending unchanged bytes. Use offset/limit to read or recover an exact line range, for example after a large file was summarized. A binary file returns metadata instead of content; for images use read_image.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	File path (absolute, or relative to the project root). Use an absolute path for files outside the project root.
`limit`	No	Number of lines to return starting at `offset`.
`offset`	No	1-based first line for a ranged read; omit or pass 0 to start from the first line.
`max_size`	No	Byte threshold above which the file is semantically summarized; recover exact lines afterward with `offset`/`limit`.
`known_hash`	No	The `content_hash` from your last read of this file; pass it back to get `"unchanged"` instead of the content re-sent. Omit only on a first read or when you no longer hold the hash.

Output Schema

ParametersJSON Schema

Name	Required	Description
`hint`	No
`mime`	No
`path`	No
`size`	No
`lines`	No
`params`	No
`content`	No
`is_diff`	No
`is_binary`	No
`truncated`	No
`unchanged`	No
`from_cache`	No
`total_lines`	No
`content_hash`	No
`tokens_saved`	No
`total_tokens`	No
`tokens_original`	No
`tokens_returned`	No

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavior: caching on first read, returning 'unchanged' or a diff on subsequent reads, handling of binary files, and the effect of `max_size`. Side effects like caching are explicitly mentioned.

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 tightly written with no superfluous sentences. Core purpose is front-loaded, and each sentence adds distinct value, making it highly concise and well-structured.

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

Completeness5/5

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

Given 5 parameters, no annotations, and an existing output schema, the description covers return behavior, caching, parameter usage, and alternatives comprehensively. An agent has all necessary context to use the tool correctly.

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

Parameters4/5

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

Schema coverage is 100%, baseline 3. The description adds significant value beyond schema: explains `known_hash` as server proof of content, `offset`/`limit` for exact line ranges, and `max_size` triggering summarization. This justifies a score of 4.

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 'Read a file, returning as few tokens as possible.' It distinguishes from sibling tools like `batch_read` and `read_image`, making the tool's specific purpose unambiguous.

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

Usage Guidelines5/5

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

Explicit guidance is given: 'For 2+ files, use `batch_read`.' It explains when to use parameters like `known_hash`, `offset`/`limit`, and `max_size`, providing clear context for when to use this tool vs alternatives.

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

read_imageA

Read an image file so the model can see it.

Returns an MCP image block (base64 data + mime type) plus a small JSON metadata sidecar (size, mime). Use this only when the model needs to view the image; for text or any other file type use read.

The format is detected from the file's magic bytes, not its extension, so a mis-named image still works and a non-image (e.g. text saved as .png) is rejected. Supports PNG, JPEG, GIF, TIFF, BMP, and WebP. Images are never cached — every call re-reads from disk. Oversized images are rejected before encoding; the cap is SCMCP_MAX_IMAGE_BYTES (default 5 MiB), bounded by Anthropic's ~5 MB upload limit.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Image file path (absolute, or relative to the project root).

Output Schema

ParametersJSON Schema

Name	Required	Description
`mime`	No
`path`	No
`size`	No
`truncated`	No

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description fully discloses key behaviors: format detection via magic bytes, supported formats, caching policy (never cached), size limit (configurable cap), and rejection of non-images. This is highly informative.

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 well-structured into three concise paragraphs, each serving a distinct purpose: purpose, return, guidelines, and behavioral notes. No redundant sentences.

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

Completeness5/5

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

Given the single parameter and the fact that an output schema is present, the description still covers return format, error cases, and constraints, making it fully complete for practical use.

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% and its description already covers path handling. The description adds value by explaining format detection via magic bytes, which enriches understanding of how the path parameter is used.

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

Purpose5/5

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

The description clearly states the verb 'read' and resource 'image file', and specifies the purpose 'so the model can see it'. It distinguishes from sibling tool 'read' by indicating it is only for images.

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

Usage Guidelines5/5

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

Explicitly states 'Use this only when the model needs to view the image; for text or any other file type use `read`', providing clear context and an alternative.

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

searchA

Find cached files by keyword relevance (BM25 ranking).

Searches only files already in the cache — seed them first with read/batch_read (thin results usually mean too few files are cached). Ranks by BM25 term relevance, so multi-word and keyword queries work well; matching is lexical, not embedding-based, so synonyms won't match a word that isn't present. For an exact string or regex use grep; to pull more of the repo into the cache use batch_read. Returns matches with a normalized 0–1 relevance score (best match = 1.0) and a short preview.

ParametersJSON Schema

Name	Required	Description
`k`	No	Maximum number of matches to return.
`query`	Yes	Keywords to rank by. Natural-language phrasing is fine, but ranking is on the individual words.
`directory`	No	Restrict matches to files under this directory.
`show_preview`	No	Include a short preview line for each match.

Output Schema

ParametersJSON Schema

Name	Required	Description
`k`	No
`count`	No
`query`	No
`matches`	No
`directory`	No
`truncated`	No
`cached_files`	No
`show_preview`	No
`files_searched`	No

TDQS

A4.7/5.0

Behavior4/5

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

The description discloses that the tool only searches cached files, uses lexical BM25 matching (not embedding-based), and returns a normalized relevance score and preview. However, it does not explicitly state that the tool is read-only or mention any side effects, though these are implied.

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

Conciseness5/5

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

The description is concise with no wasted words, covering key points in 6 sentences. It front-loads the purpose and then provides necessary context and comparisons without redundancy.

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

Completeness5/5

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

Given no annotations and an output schema (present but not provided), the description adequately covers prerequisites (caching), ranking behavior, comparison to siblings, and return format (score and preview). It is complete for the tool's complexity.

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

Parameters4/5

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

The input schema covers all 4 parameters with descriptions (100% coverage). The description adds value by clarifying that queries are ranked on individual words and that multi-word queries work well, which complements the schema's explanation of the 'query' parameter.

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

Purpose5/5

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

The description clearly states the verb 'Find cached files by keyword relevance' and specifies the ranking algorithm (BM25). It distinguishes itself from sibling tools by explicitly mentioning 'grep' for exact/regex and 'batch_read' for caching more files.

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: it states that files must be cached first (using 'read'/'batch_read') and advises when to use alternatives ('grep' for exact/regex, 'batch_read' to cache more). This helps the agent choose correctly.

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

statsA

Report cache health, token savings, and runtime diagnostics.

Returns storage occupancy (files, tokens, documents, DB size), session and lifetime token savings and cache hit rates, per-tool call counts, and process memory. Use it to measure or debug — not as a routine step in read/edit loops. Takes no arguments.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`mode`	No
`session`	No
`storage`	No
`lifetime`	No
`truncated`	No
`process_rss_mb`	No

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavior: read-only diagnostic, no arguments, reports specific metrics. It covers what the tool returns and implies it has no side effects.

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: first states purpose, second lists details and usage hint. Every word earns its place, 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?

With an output schema available, the description does not need to detail return values, but it already does. It covers purpose, usage, behavior, and is self-contained for a zero-parameter diagnostic tool.

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% (no parameters). Baseline for 0 params is 4. The description adds that it takes no arguments, which is already in the schema, but does not provide additional parameter-level meaning beyond that.

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 reports cache health, token savings, and runtime diagnostics. It lists specific metrics (storage occupancy, hit rates, call counts, memory) and distinguishes itself from siblings by noting it is not for routine read/edit loops.

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

Usage Guidelines5/5

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

Explicitly states 'Use it to measure or debug — not as a routine step in read/edit loops,' providing clear when-to-use and when-not-to-use guidance. No alternative tools are named, but the context of siblings (all file operations) makes the diagnostic role obvious.

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

writeA

Create a file or replace its entire contents.

Use this for new files or full rewrites; for localized changes prefer edit or batch_edit. Status is created for a new path or updated for an existing one, and an update returns a unified diff against the previous content. Writing refreshes the cache so later reads, grep, and search see the new text. The response carries the new content_hash; pass it back as read's known_hash to get unchanged instead of re-reading the file you just wrote. Missing parent directories are created unless create_parents=false.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	File path to create or replace (absolute, or relative to root).
`append`	No	Append `content` to the end of the file instead of overwriting.
`content`	Yes	Full file content, or the text to append when `append=true`.
`dry_run`	No	Preview the result without writing.
`show_diff`	No	Return the unified diff even on a deterministic write.
`auto_format`	No	Run the formatter after writing.
`create_parents`	No	Create any missing parent directories.

Output Schema

ParametersJSON Schema

Name	Required	Description
`diff`	No
`path`	No
`status`	No
`created`	No
`dry_run`	No
`truncated`	No
`diff_state`	No
`diff_stats`	No
`from_cache`	No
`content_hash`	No
`diff_omitted`	No
`tokens_saved`	No
`bytes_written`	No
`tokens_written`	No

TDQS

A4.7/5.0

Behavior5/5

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

No annotations provided, so description bears full burden. It discloses status ('created'/'updated'), returns unified diff on updates, refreshes cache for other tools, provides content_hash, and explains the known_hash optimization for read.

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?

Concise and front-loaded: first sentence states purpose, subsequent sentences add essential details (usage, status, diff, cache, hash) without any 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?

Covers all key behavioral aspects: return status and diff, cache invalidation, content_hash and interaction with read, and creation of parent directories. Output schema exists but description still explains important output fields.

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 baseline is 3. Description adds minimal extra meaning beyond schema parameters (e.g., emphasizing create_parents default), but does not significantly deepen understanding of each parameter beyond what schema already offers.

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

Purpose5/5

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

Clearly states the tool creates or replaces file contents, uses specific verb+resource, and distinguishes from siblings by referencing 'edit' and 'batch_edit' for localized changes.

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

Usage Guidelines5/5

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

Explicitly advises to use for new files or full rewrites and to prefer 'edit' or 'batch_edit' for localized changes. Also notes behavior for missing parent directories.

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. Dates show when Glama detected each change.

12 tool updatesv0.5.1Jul 13, 2026

Changedbatch_edit5 fields changed

addedInput schema / properties / auto_format / description
```
Added value: +"Run the formatter after all edits."
```
addedInput schema / properties / dry_run / description
```
Added value: +"Preview without writing."
```

addedInput schema / properties / edits / description

Added value: +"JSON array of edit entries, in any of the forms above."

addedInput schema / properties / path / description

Added value: +"File path to modify (absolute, or relative to root)."

addedInput schema / properties / show_diff / description

Added value: +"Return the full diff even on a deterministic all-success batch."

Changedbatch_read3 fields changed

addedInput schema / properties / max_total_tokens / description

Added value: +"Total token budget shared across the whole batch."

addedInput schema / properties / paths / description

Added value: +"The files to read — a comma-separated list, a JSON array, or\nglob patterns (expanded for you)."

addedInput schema / properties / priority / description

Added value: +"Optional paths to read first, ahead of the remaining files."

Changeddelete2 fields changed

addedInput schema / properties / dry_run / description

Added value: +"Preview the outcome without deleting or evicting the cache."

addedInput schema / properties / path / description

Added value: +"File or symlink path (absolute, or relative to the project root)."

Changededit9 fields changed

addedInput schema / properties / auto_format / description
```
Added value: +"Run the formatter after editing."
```
addedInput schema / properties / dry_run / description
```
Added value: +"Preview without writing."
```

addedInput schema / properties / end_line / description

Added value: +"1-based inclusive end line for a scoped or line-range edit."

addedInput schema / properties / new_string / description

Added value: +"Replacement text (an empty string deletes the match)."

addedInput schema / properties / old_string / description

Added value: +"Exact text to find. Omit only for a line-range replacement."

addedInput schema / properties / path / description

Added value: +"File path to modify (absolute, or relative to root)."

addedInput schema / properties / replace_all / description

Added value: +"Replace every occurrence instead of requiring a unique match."

addedInput schema / properties / show_diff / description

Added value: +"Return the diff even on a deterministic edit."

addedInput schema / properties / start_line / description

Added value: +"1-based inclusive start line for a scoped or line-range edit."

Changededit_preview2 fields changed

addedInput schema / properties / old_string / description

Added value: +"Anchor text to locate. Must match exactly, including\nwhitespace and indentation. Cannot be empty."

addedInput schema / properties / path / description

Added value: +"File path to search (absolute, or relative to root)."

Changedglob3 fields changed
- addedInput schema / properties / cached_only / description
```
Added value: +"Return only files that are already cached."
```
- addedInput schema / properties / directory / description
```
Added value: +"Base directory the pattern is evaluated from."
```
- addedInput schema / properties / pattern / description
```
Added value: +"Glob pattern to match (e.g. `src/**/*.py`)."
```

Changedgrep7 fields changed

addedInput schema / properties / case_sensitive / description
```
Added value: +"Match case-sensitively."
```

addedInput schema / properties / context_lines / description

Added value: +"Lines of surrounding context to include per match."

addedInput schema / properties / fixed_string / description

Added value: +"Match `pattern` literally instead of as a regex."

addedInput schema / properties / max_files / description
```
Added value: +"Cap on the number of files returned."
```

addedInput schema / properties / max_matches / description

Added value: +"Cap on total matches returned across all files."

addedInput schema / properties / path / description

Added value: +"Optional filter — an exact path, a path suffix, or a glob."

addedInput schema / properties / pattern / description

Added value: +"A regular expression, or a literal string when\n`fixed_string=true`."

Changedread6 fields changed

addedInput schema / properties / known_hash

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The `content_hash` from your last read of this file; pass it\nback to get `\"unchanged\"` instead of the content re-sent. Omit only\non a first read or when you no longer hold the hash."
+}

addedInput schema / properties / limit / description

Added value: +"Number of lines to return starting at `offset`."

addedInput schema / properties / max_size / description

Added value: +"Byte threshold above which the file is semantically\nsummarized; recover exact lines afterward with `offset`/`limit`."

addedInput schema / properties / offset / description

Added value: +"1-based first line for a ranged read; omit or pass 0 to start\nfrom the first line."

addedInput schema / properties / path / description

Added value: +"File path (absolute, or relative to the project root). Use an\nabsolute path for files outside the project root."

removedOutput schema / properties / semantic_match

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Semantic Match"
-}

Changedread_image1 field changed
- addedInput schema / properties / path / description
```
Added value: +"Image file path (absolute, or relative to the project root)."
```

Changedsearch4 fields changed

addedInput schema / properties / directory / description

Added value: +"Restrict matches to files under this directory."

addedInput schema / properties / k / description

Added value: +"Maximum number of matches to return."

addedInput schema / properties / query / description

Added value: +"Keywords to rank by. Natural-language phrasing is fine, but\nranking is on the individual words."

addedInput schema / properties / show_preview / description

Added value: +"Include a short preview line for each match."

Changedstats2 fields changed

removedOutput schema / properties / embedding

Removed value: -{
-  "anyOf": [
-    {
-      "properties": {
-        "model": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Model"
-        },
-        "process_rss_mb": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Process Rss Mb"
-        },
-        "provider": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Provider"
-        },
-        "ready": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Ready"
-        },
-        "truncated": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Truncated"
-        }
-      },
-      "title": "StatsEmbedding",
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

addedOutput schema / properties / process_rss_mb

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Process Rss Mb"
+}

Changedwrite7 fields changed

addedInput schema / properties / append / description

Added value: +"Append `content` to the end of the file instead of overwriting."

addedInput schema / properties / auto_format / description
```
Added value: +"Run the formatter after writing."
```

addedInput schema / properties / content / description

Added value: +"Full file content, or the text to append when `append=true`."

addedInput schema / properties / create_parents / description
```
Added value: +"Create any missing parent directories."
```

addedInput schema / properties / dry_run / description

Added value: +"Preview the result without writing."

addedInput schema / properties / path / description

Added value: +"File path to create or replace (absolute, or relative to root)."

addedInput schema / properties / show_diff / description

Added value: +"Return the unified diff even on a deterministic write."

6 tool updatesv0.4.8May 27, 2026

Removeddiff
Addededit_preview

Changedgrep2 fields changed

addedOutput schema / properties / truncated_files

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Truncated Files"
+}

addedOutput schema / properties / truncated_matches

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Truncated Matches"
+}

Changedread5 fields changed

addedOutput schema / properties / content_hash

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Content Hash"
+}

addedOutput schema / properties / is_binary

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Is Binary"
+}

addedOutput schema / properties / mime

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Mime"
+}

addedOutput schema / properties / size

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Size"
+}

addedOutput schema / properties / total_lines

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Total Lines"
+}

Addedread_image
Removedsimilar

13 tool updatesv0.4.5May 4, 2026
- Addedbatch_edit
- Addedbatch_read
- Addedclear
- Addeddelete
- Addeddiff
- Addededit
- Addedglob
- Addedgrep
- Addedread
- Addedsearch
- Addedsimilar
- Addedstats
- Addedwrite
3 tool updatesv0.4.1Apr 7, 2026
- Removedclear
- Removedread
- Removedstats
3 tool updatesv0.4.1Apr 7, 2026
- First observedclear
- First observedread
- First observedstats

Install Server

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

TDQS

A4.7/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: read vs batch_read, edit vs batch_edit vs write, grep vs search, etc. No overlapping functionality, and descriptions provide routing rules to avoid ambiguity.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern (e.g., batch_edit, batch_read, glob, grep). Even single-word names like 'clear' and 'stats' fit the verb or noun role without breaking consistency.

Tool Count5/5

13 tools is a well-scoped set for a semantic cache file editing assistant. The number covers core file operations (read, write, edit, delete), batch operations, search, glob, diff, and diagnostics without being overwhelming.

Completeness4/5

The tool surface provides comprehensive file CRUD, batch reading, search, grep, and cache diagnostics. Minor gaps like missing rename/move or directory listing are non-critical because existing tools (edit/delete/write, glob) cover those workflows.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

ref-tools-ref-tools-mcpOAuth
ai.smithery
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Documentation Access Developer Tools Code Analysis
21,164
kansei-mcp-server A
io.github.kansei-link
SaaS intelligence for AI agents. 5 unified tools cover 1,000+ services with 91-96% token savings.
Developer Tools Agent Orchestration
321
ArchGraphOAuth
dev.archgraph
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code Analysis Software Architecture Developer Tools
2
Axis Iliad — Codebase Intelligence For Agentic Commerce A
io.github.lastmanupinc-hub
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Code Analysis Developer Tools Documentation Access
4

Related MCP Servers

Context Optimizer MCP Server
Code Execution Command Line RAG Systems
malaksedarous
A
license
A
quality
D
maintenance
Provides AI coding assistants with context optimization tools including targeted file analysis, intelligent terminal command execution with LLM-powered output extraction, and web research capabilities. Helps reduce token usage by extracting only relevant information instead of processing entire files and command outputs.
Updated a year ago (2025-08-30 12:04 UTC)
5
22
62
TypeScript
MIT
Ambiance MCP Server
Code Analysis Developer Tools RAG Systems
sbarron
A
license
A
quality
D
maintenance
Provides intelligent code context and analysis through semantic compression, AST parsing, and multi-language support. Offers 60-80% token reduction while enabling AI assistants to understand codebases through local analysis, OpenAI-enhanced insights, and GitHub repository integration.
Updated a year ago (2025-10-19 07:35 UTC)
6
22
3
MIT
cachebro
Developer Tools File Systems Coding Agents
glommer
A
license
Not graded
quality
D
maintenance
Provides file caching and diff tracking for AI coding agents, reducing token usage by returning changes or confirming no changes instead of full file contents on repeated reads.
Updated 4 months ago (2026-05-20 13:26 UTC)
66
218
MIT
CodeXRay
Code Analysis Knowledge & Memory
NeuralRays
A
license
Not graded
quality
C
maintenance
Enables AI coding agents to query a pre-built semantic knowledge graph of code, reducing token usage and tool calls. Supports 16 tools for code exploration, analysis, and context building.
Updated 7 months ago (2026-02-10 05:00 UTC)
13
7
MIT

Appeared in Searches

Token savings strategies for code intelligence tools

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CoderDayton/semantic-cache-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server