Folio
Folio is a privacy-first document assistant for interacting with files in explicitly granted folders using your own LLM — no data leaves your machine. It can:
List authorized folders (
list_roots): Discover which directories the assistant may access.Browse directory contents (
list_dir): List files and sub-folders within a granted root.Read file contents (
read_file): Retrieve the full text of any file within a granted root.Search documents (
search): Perform keyword-based searches across granted files, returning matching lines with file name and line number.Answer natural-language questions (
answer): Ask questions in plain English — the server retrieves relevant context and uses the host's LLM to generate a grounded answer.Summarize files (
summarize): Generate a concise summary of a file's key points using the host's own LLM.Edit files (
edit_file): Make targeted in-place edits by specifying an exact string to find and replace.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Foliosummarize the file README.md"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Folio
A privacy-first, zero-AI-cost "chat with your documents" assistant. One engine, two front doors: a fully offline command-line app, and an OAuth-secured web app.
Point Folio at a folder and it can read, search, summarize, answer questions about, and reformat the files inside it — and nothing else. Your documents never leave your machine, and the generation runs on your own model, so there is no per-token AI bill.
Folio is built on the Model Context Protocol (MCP) and is designed to exercise its most advanced features in a way that is essential to the use case, not bolted on.

The Aurora web UI answering with live search progress. Demo recorded on a cloud provider for speed — Folio runs identically on local Ollama (just slower).
Why the design is meaningful
Feature | Why it matters here |
Roots | The assistant can only touch the folders you explicitly grant — enforced on every file operation. The rest of your disk is unreachable. This is privacy by construction. |
Sampling | The generation is done by the host's own model (local Ollama by default), not the server. A hosted Folio therefore never racks up AI bills, and each person's documents are processed by their own model. |
Dual transport | The same server runs locally over stdio (the CLI) or remotely over Streamable HTTP (the web app). |
OAuth 2.1 | The web app identifies users with GitHub sign-in; the server validates every request's bearer token before running a tool. |
Logging & progress | Long jobs ("search the whole folder") stream live status, so you can see real work happening instead of a frozen spinner. |
Related MCP server: lilbee
Features
🔒 Granted-folder access only — a non-negotiable path guard on every tool.
🔎 Search across files with live progress.
📝 Summarize a file and answer questions grounded in your documents.
✏️ Reformat / edit files in place.
💻 Offline CLI (stdio) — private, $0, works with no internet.
🌐 Web app (FastAPI + GitHub login) — a designed browser UI: upload or pick documents, ask questions, and watch live search progress stream in over SSE.
🔁 Provider-agnostic — local Ollama by default, with Cerebras and OpenRouter as drop-in cloud fallbacks, plus Anthropic and OpenAI as optional bring-your-own-key upgrades in the CLI (switch via two lines in
.env).
Architecture
┌───────────────────────────────────────┐
CLI (local): │ mcp_server.py │
main.py ──stdio────▶│ ONE FastMCP engine: │
│ • tools (list/read/search/...) │
Web (remote): │ • resources (roots, files) │
Browser ⇄ FastAPI ──┤ • prompts (/summarize, /format) │
host │ roots guard · sampling · logging · │
──HTTP + OAuth─────▶│ progress · OAuth (HTTP mode) │
└───────────────────────────────────────┘Both hosts speak to the same server; only the transport differs. In each case the host (the CLI or the FastAPI app) is the MCP client: it runs the agent loop, holds the model keys, and answers the server's sampling / roots / logging / progress callbacks.
Requirements
(First) run and build the previous repository to setup local ollama + litellm tool-calling environment repo-here
ollama pull qwen2.5:7b(No API key needed for the local path. Cerebras / OpenRouter are optional cloud fallbacks.)
Python 3.10+ (developed on 3.13)
uv for dependency + run management
Install
uv syncConfigure
Copy the template and fill in values locally (the real .env is git-ignored):
cp .env.example .envThe default configuration uses local Ollama and needs no keys:
LLM_PROVIDER=ollama
LLM_MODEL=ollama_chat/qwen2.5:7bSwitch provider by changing LLM_PROVIDER + LLM_MODEL together (see .env.example for the
Cerebras / OpenRouter forms).
Run the CLI
Grant one or more folders and start chatting:
uv run main.py path/to/your/folderWith no folder it defaults to the bundled sample-docs/. At the > prompt you can:
ask questions in plain English (e.g. "how long are backups retained?"),
mention a file with
@, e.g.@policies/data-retention.md what does this say?,run a command, e.g.
/summarize README.md.
Exit with Ctrl+C.
Run the web app
The OAuth-secured FastAPI web app runs with:
uv run uvicorn web.app:app --port 8000Then open http://localhost:8000 and sign in with GitHub. From there you can load the bundled
sample documents or upload your own, click a file to ground a question, and watch live search
progress as Folio answers. It runs the same MCP engine as the CLI, just over HTTP.
Screenshots
|
|
Sign in → load the bundled sample set or upload your own. | Click a document to drop its exact |
|
|
Live search log + progress stream while Folio works. | The fully-offline CLI host (stdio), grounded in your docs. |
Benchmarks & tradeoffs
Folio is provider-agnostic, so which model you point it at is a real tradeoff. These numbers come
from running the actual agent loop over a small e-commerce document set (5 grounded questions
with known answers), paced to respect free-tier rate limits — see benchmarks/ for
the reproducible harness and full results.
Model | Correct | Median latency/call | Notes |
Cerebras | 5/5 | ~0.5s | fast + accurate |
Cerebras | 5/5 | ~0.7s | fast + accurate |
OpenRouter | 3/5* | ~3.1s | *2 misses were free-tier rate-limit 429s, not wrong answers |
Ollama | 3/5 | ~9.5s | private + $0, but ~15–20× slower and less consistent |
Three takeaways:
Speed — Cerebras answers ~15–20× faster per call than the local 7B (~0.5s vs ~9.5s).
Accuracy — the bigger cloud models are consistently correct; the small local 7B is inconsistent (it confabulated a non-existent file path and sometimes answered "no information").
Free-tier reality — free cloud tiers rate-limit/throttle under load (OpenRouter's free
llama-3.3-70bwas entirely unusable in a burst). For real throughput, bring your own key.
The honest tradeoff triangle: privacy (local Ollama) ↔ speed + quality (Cerebras) ↔ cost (free,
but throttled). Reproduce with uv run python benchmarks/benchmark.py.
Which provider should I use?
Privacy / offline / $0 →
ollama(local; slower and less consistent, but nothing leaves your machine).Fast + accurate, free →
cerebras(near-instant; free tier throttles under heavy use).Maximum quality (paid, CLI only) →
anthropicoropenaiwith your own key (e.g.LLM_MODEL=anthropic/claude-opus-4-8). The web app never accepts keys — this is a CLI upgrade.
Limitations (honest)
Local 7B is slow and inconsistent.
qwen2.5:7bis private and free but answers in seconds-to-tens-of-seconds and occasionally mis-uses tools (confabulates a path, or gives up). For reliable, fast answers, use a cloud provider.Free cloud tiers throttle. Cerebras and OpenRouter free tiers rate-limit under sustained/burst use; the benchmark above was captured with fresh quota — re-running on an exhausted free tier shows worse numbers (a quota artifact, not the models). Bring your own key for real throughput.
The web app is a shared/hosted convenience, not the fully-private path. Uploaded documents go to the server (isolated per user, deleted on logout + a TTL sweep). For fully offline / private use, run the CLI with local Ollama.
Text documents only. Folio reads text files (Markdown,
.txt,.csv, code, …) — no images/audio/video.Anthropic / OpenAI need paid API credits. They are optional CLI upgrades, not required.
Tech stack
MCP Python SDK (FastMCP) — the server engine, the client session, both transports, and the OAuth modules.
litellm — one OpenAI-shaped API over Ollama, Cerebras, OpenRouter, Anthropic, and OpenAI (routes by the model-string prefix).
FastAPI + uvicorn — the async web host; its native async + SSE match the MCP SDK and the live-progress requirement.
sse-starlette — streams live log/progress events to the browser over Server-Sent Events.
itsdangerous — the web app remembers your GitHub sign-in in a small signed-cookie session;
itsdangerouscryptographically signs that cookie so it can't be tampered with (a tamper-evident seal). It's what makes "stay logged in" trustworthy.prompt-toolkit — the interactive CLI prompt, autocompletion, and history.
Security notes
The roots guard (
is_path_allowed) is enforced in every file tool — the SDK provides the roots mechanism, but Folio enforces the policy.OAuth applies to the HTTP transport only; the local stdio CLI needs none (you launched the process yourself).
Secrets live only in the git-ignored
.env..env.exampleships blank placeholders.
Project status
Complete: the MCP engine (roots, sampling, logging/progress, dual transport, OAuth), the offline CLI, and the OAuth-secured FastAPI web app. A hosted public deployment is intentionally not provided — a shared demo on free model tiers would burn the operator's quota, and the web app deliberately never accepts a visitor's API key — so run it locally (it works fully on your own machine, with the steps above).
License & credits
MIT. Built by extending
ollama-mcp-chat-cli, an earlier MCP chat-CLI project.
Available Tools
7 toolsanswerA
USE THIS to answer any natural-language question about the documents (e.g. 'how long are backups kept?'). It retrieves the relevant lines across the granted files and has the host's LLM answer from them in one step. Prefer this over 'search' for questions.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional single file to ground the answer in; if omitted, the documents are searched for relevant context. | |
| question | Yes | The question to answer using the contents of the granted documents. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the one-step retrieval and answer process and hints at read-only behavior, but lacks details on side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise—two sentences with no redundancy. The front-loaded 'USE THIS' is direct, though slightly informal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values are covered. Sibling tools are listed and comparison made. Parameters are well-documented. Minor missing context about 'granted files' but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions, achieving 100% coverage. The description adds 'ground the answer in' for path, but not much extra beyond schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it answers natural-language questions about documents, provides an example, and distinguishes from sibling tool 'search', making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use it for questions and recommends it over 'search'. However, it does not explicitly state when not to use it (e.g., for keyword matching), but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_fileA
Edit a file inside a granted root by replacing an exact string with a new string, then saving it to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the file to edit, inside a granted root. | |
| new_str | Yes | The new text to insert in place of old_str. | |
| old_str | Yes | The exact text to find and replace. Must match exactly, including whitespace. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses replacement and save behavior but omits failure modes (e.g., file not found, old_str not found), permissions, or idempotency. Adequate for basic understanding but incomplete for robust agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action ('Edit a file'), no redundant words. Every word contributes meaning. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and 100% schema coverage, the description is minimally complete. It covers the core operation but lacks context on prerequisites (file existence, root grant) and error handling, which would enhance completeness for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds no extra meaning beyond the schema (e.g., 'inside a granted root' is repeated from path's schema description). Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits a file via exact string replacement and mentions the 'granted root' constraint. It is distinct from sibling tools like read_file (read-only) and search (content search), showing specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like read_file or search. It implies usage for file modification but lacks 'when not to use' or comparative context, though the sibling list provides some indirect differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_dirB
List the entries (files and sub-folders) of a directory inside a granted root.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a directory inside a granted root (or a path relative to a root). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'granted root' implying permission context but does not disclose behavior for invalid paths, empty directories, recursive listing, or error handling. Key behavioral traits are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given schema coverage and existence of output schema, description is adequate for a simple list operation but lacks behavioral context (e.g., sorting, limits, recursion). Missing guidance on when to use this tool over siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (path parameter well-described). Description adds no additional meaning beyond schema. Baseline 3 is appropriate as schema already documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list' and resource 'entries of a directory', and context 'inside a granted root'. It distinguishes from siblings like 'read_file' (file content) and 'list_roots' (roots). However, it does not explicitly differentiate from 'search' or 'summarize'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It implicitly suggests listing directory contents but provides no context about prerequisites, performance, or when to choose it over sibling tools like 'read_file' or 'search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_rootsA
List the folders this assistant is allowed to access. Call this first to discover where files live.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It accurately describes the read-only behavior of listing accessible folders. No side effects mentioned, but output schema exists to cover return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence states purpose, second provides usage context. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a zero-parameter tool with an output schema. It covers what it does and when to use it. Could mention that it's read-only, but that is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters, so baseline is 4 per instructions. Description adds no parameter info because none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list' and resource 'folders this assistant is allowed to access'. It distinguishes from siblings like list_dir (lists directory contents) by specifying 'allowed to access' and positioning as a discovery tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Call this first to discover where files live' provides clear context for when to use this tool. While it does not explicitly mention alternatives, the sibling list suggests it is the starting point for file operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_fileA
Read the full text contents of a file inside a granted root.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a text file inside a granted root (or a path relative to a root). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates a non-destructive read but omits details on handling binary files, size limits, permissions, or output format. The existence of an output schema may partially compensate, but the description itself is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Every part is essential and contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description is largely complete. However, it lacks guidance on usage context and potential edge cases (e.g., binary files), which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a detailed parameter description. The tool description adds marginal value by reiterating the 'granted root' context. It does not provide additional clarity beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('read'), the resource ('full text contents of a file'), and the constraint ('inside a granted root'). It distinguishes itself from sibling tools like 'edit_file' (modification) and 'list_dir' (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading file contents but provides no explicit guidance on when to use this tool versus alternatives like 'search' or 'summarize'. It lacks 'when not to use' or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchA
Search the documents for the SIGNIFICANT WORDS in your query (case-insensitive; a line matches when it contains those words, in any order — so 'free shipping' matches 'shipping is free'). Returns matching lines with file and line number. For a full natural-language question, prefer the 'answer' tool.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional sub-folder to limit the search to; defaults to all granted roots. | |
| query | Yes | Words to search for; a line matches when it contains those significant words in any order (case-insensitive). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains the tool's behavior: case-insensitive, order-independent matching, and the output format (matching lines with file and line number). No side effects or destructive actions are relevant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences packing essential information: matching logic, output format, and alternative tool usage. No fluff, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, usage, behavior, and parameters. Given the presence of an output schema (not shown), it does not need to detail return values further. Complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description's parameter details (e.g., 'query: Words to search for...') largely duplicate the schema descriptions, adding no new information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches documents for significant words, explains case-insensitive matching and order flexibility, and returns matching lines with file and line number. It distinguishes from sibling tool 'answer' by specifying that tool is for natural-language questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs users to prefer the 'answer' tool for full natural-language questions, providing clear guidance on when not to use this tool. Implicitly, it's for keyword searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
summarizeA
Summarize a file using the host's own LLM (via MCP sampling). Returns a concise summary of the file's key points.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file to summarize, inside a granted root (absolute, or relative to a root). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description discloses that it uses the host's LLM via MCP sampling, which is a key behavioral trait. However, it does not mention potential limitations like file size or speed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates the action, method, and result without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers the return value. It could mention possible file type restrictions, but is otherwise complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter (path) with a clear description. The tool description does not add extra information beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Summarize' and the resource 'file', with a specific method ('via MCP sampling'). It is distinct from sibling tools like read_file, answer, or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicit. The description does not provide when-to-use or when-not-to-use guidance relative to siblings.
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.
7 tool updates
v0.1.0- First observed
answer - First observed
edit_file - First observed
list_dir - First observed
list_roots - First observed
read_file - First observed
search - First observed
summarize
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes. The only overlap is between 'answer' and 'search', but their descriptions clarify the appropriate use case (natural language vs. keyword search).
All tool names use snake_case and follow a consistent verb_noun pattern (e.g., edit_file, list_dir) or single verbs (answer, search). No mixing of conventions.
With 7 tools, the set is well-scoped for a document query and editing server. Not too many or too few, though some minor operations (e.g., create file) are absent.
The domain of file management is partially covered: read, edit, list, search, summarize. However, missing tools for file creation, deletion, or renaming leave noticeable gaps for full lifecycle operations.
Maintenance
Related MCP Connectors
Your private knowledge base: upload documents (.md, .txt, .docx, PDF, images), the platform indexes
Run AI customer support from your terminal: conversations, knowledge base, and chat widget.
- KumbukaOAuthai.kumbuka
Governed, auditable knowledge your team curates for its AI assistants, self-hostable
A personal RAG database you build from chat, so AI creates work that sounds like you.
Related MCP Servers
- AlicenseAqualityAmaintenancePrivacy-first local document search using semantic search. Runs entirely on your machine with no cloud services, supporting PDF, DOCX, TXT, and Markdown files.2295,156 npm401MIT
- AlicenseBqualityAmaintenanceFind, run, and manage your local AI models, then talk to your files, your code, and the sites you crawl. Every answer cites the source, it all runs on your own machine, and it's one program with nothing else to set up.29904 PyPI55MIT
- FlicenseAqualityDmaintenanceEnables indexing local documents (PDF, Markdown, text, code) into a knowledge base and querying them via semantic search using local embeddings, all running privately on your machine.4-
- AlicenseNot gradedqualityAmaintenanceLocal-first memory and retrieval for private project knowledge. Enables indexing files, searching, and asking questions about project documents using local embeddings and LLM.6AGPL 3.0



