Local, private AI second brain over MCP — hybrid search of any Markdown/Obsidian vault.
brain-mcp has 5 tools with basic descriptions and partial schemas. Tool names follow verb_noun convention (search, read, write, list, status). However, descriptions are minimal (10-60 chars, well below the 194-char baseline), parameter descriptions are sparse or missing, and output schemas are undocumented. The write tool lacks clear error guidance for permission/disk failures. No tool annotations (readOnlyHint, destructiveHint) despite clear risk profiles. Schemas present but incomplete, missing type info for some parameters and no documented return structures. This is typical community-server quality: functional but not LLM-optimized.
List all indexed files in the vault with their metadata (path, size, last modified).
Read the full content of a note file from the vault.
Hybrid search (semantic + keyword) over the vault. Returns ranked results with snippets.
Get indexing status: total files, chunks, last index time, and any errors.
Write or append content to a note file in the vault. Creates the file if it doesn't exist.
Descriptions are too short (10-60 chars vs 194-char baseline). LLMs cannot distinguish when to use search vs read, or understand write's mode parameter without longer, context-rich descriptions.
Output schemas are not documented. Callers cannot know what fields search returns (e.g., does it include snippet, score, path?), forcing LLMs to guess or make extra calls.
write tool lacks error guidance. If disk is full or permissions denied, LLM gets no recovery hint. Should return 'Permission denied on path X. Check BRAIN_VAULT permissions.' or similar.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). write is clearly destructive; search/read/list/status are read-only. Annotations help LLMs reason about safety and retry logic.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 41 | <=2025-11-25 | v2 |
Parameter descriptions missing or minimal. 'path' in read/write lacks format guidance (relative? absolute? must exist?). 'limit' in search has no min/max bounds. LLMs cannot validate inputs.