From edbb4b71521c0c67d237e5226dde875c8122a971 Mon Sep 17 00:00:00 2001
From: helm <lukasparsons2013@gmail.com>
Date: Mon, 6 Jul 2026 21:33:23 -0400
Subject: [PATCH] =?UTF-8?q?fix:=20disambiguate=20MCP=20tool=20descriptions?=
 =?UTF-8?q?=20=E2=80=94=20mark=20all=20as=20FILESYSTEM=20TOOL?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Qwen3.5-9B was conflating these tools with manage_memory because the
descriptions sounded similar ('list vault contents' vs 'search memory').

Every tool now opens with 'FILESYSTEM TOOL' to create a hard routing
boundary from conversation/memory tools. Added explicit NOT clauses
('NOT a memory search, NOT a conversation search') and USE THIS TO
guidance so the model routes correctly on first attempt.
---
 server.py | 29 +++++++++++++++++++++++------
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/server.py b/server.py
index c668d6e..fd33dfb 100644
--- a/server.py
+++ b/server.py
@@ -124,7 +124,9 @@ mcp = FastMCP("Obsidian Vaults")
 
 @mcp.tool()
 def get_vaults() -> dict[str, Any]:
-    """List all Obsidian vaults found in the configured vaults root directory.
+    """FILESYSTEM TOOL — List all Obsidian vaults found on disk in the vaults root directory.
+
+    USE THIS TO: discover which vaults are available before browsing one.
 
     Returns a list of vaults with name, path, and note counts.
     """
@@ -160,10 +162,15 @@ def list_vault(
     include_directories: bool = True,
     file_extensions: list[str] | None = None,
 ) -> dict[str, Any]:
-    """List the contents of a vault directory — both files and subdirectories.
+    """FILESYSTEM TOOL — Reads your Obsidian vault from disk. Lists files and folders.
 
-    This is THE primary tool for browsing a vault. Use it to discover what
-    documents exist before calling get_vault_document to read them.
+    USE THIS TO: browse your campaign notes, discover what documents exist,
+    find folders, see the vault structure. Call this BEFORE get_vault_document
+    so you know what's available to read.
+
+    IMPORTANT: This reads the ACTUAL FILESYSTEM. It is NOT a memory search,
+    NOT a conversation search, NOT a database query. It looks at real files
+    and folders on disk in your Obsidian vault directory.
 
     Args:
         vault_name: Name of the vault (subdirectory name under vaults root)
@@ -230,7 +237,10 @@ def list_vault(
 
 @mcp.tool()
 def get_vault_document(vault_name: str, doc_path: str) -> dict[str, Any]:
-    """Read a markdown document from a vault.
+    """FILESYSTEM TOOL — Read a markdown document from a vault on disk.
+
+    USE THIS TO: read the full content of a note you discovered via list_vault
+    or search_vault. Returns the complete markdown text with metadata.
 
     Args:
         vault_name: Name of the vault.
@@ -262,7 +272,14 @@ def get_vault_document(vault_name: str, doc_path: str) -> dict[str, Any]:
 
 @mcp.tool()
 def search_vault(vault_name: str, query: str, max_results: int = 50) -> dict[str, Any]:
-    """Full-text search across all markdown files in a vault.
+    """FILESYSTEM TOOL — Full-text search across all markdown files on disk in a vault.
+
+    USE THIS TO: find which notes mention a character, location, or concept.
+    Searches the actual file contents of every .md file in the vault.
+
+    IMPORTANT: This searches REAL FILES on disk. It is NOT a memory search
+    or conversation search. It reads every markdown file and looks for your
+    query string inside the document text.
 
     Args:
         vault_name: Name of the vault to search.