MCP server enabling AI agents to perform natural knowledge discovery and analysis across Obsidian vaults
The server defines three well-named tools (search_vault, get_note_content, browse_vault_structure) with action verbs and clear intent. All tools have descriptions and input schemas with types. However, significant gaps emerge on deeper inspection: parameter descriptions are present but often lack specificity on constraints and formats; output schemas are not formally documented; error handling provides basic recovery but lacks actionable guidance; and parameter validation rules are not explicit in descriptions. The search_vault tool is particularly complex with 14 parameters, some with undocumented dependencies (e.g., title_contains and tag accept multiple formats via JSON string parsing, but this is not stated in the parameter description). Naming is strong (verb_noun pattern), but schema completeness and parameter constraint documentation are weak, typical of a functional but not production-hardened implementation.
Browse vault directory structure.
Get the full content and metadata of a specific note by path.
Search Obsidian vault for notes matching criteria.
Output schemas not documented. Tools return Dict[str, Any] with fields like 'success', 'error', 'data' visible in code but not formally specified in docstrings. LLMs cannot predict response structure reliably, preventing downstream tool chaining and forcing guesswork about field names.
search_vault parameter 'title_contains' and 'tag' accept both string and array types, with undocumented JSON string parsing fallback. The description states '(string or array)' but does not explain the JSON string format or when to use it. This ambiguity invites LLM errors and wasted parsing attempts.
Parameter constraints not documented in descriptions. Numeric parameters (context_length: 100, page_size: 50, page: 1, max_matches_per_file: 5) have no min/max bounds specified. Date parameters (modified_since, modified_until, created_since, created_until) state 'YYYY-MM-DD' format but lack validation rules. LLMs may pass out-of-range or malformed values without guidance.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 59 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 49 | - | v1 |
Error handling returns generic success/error fields but provides limited recovery guidance. Errors like 'Failed to get note at path...' do not suggest next steps (e.g., 'Try search_vault() to find available notes'). This violates recovery-guide pattern and leaves LLMs stuck on failure.
search_vault has 14 parameters, with complex inter-dependencies (title_match_mode, tag_match_mode only apply when title_contains/tag are provided). These dependencies are not documented, forcing LLMs to reason about valid combinations without guidance.
Pagination fields (page_size, page) documented but no indication of max result count or total_count in response. LLMs cannot determine if pagination is required or what the total result set size is, risking context window exhaustion on large vaults.