notes-mcp provides two read-only tools with clear verb-based naming (search_notes, read_notes) and structured JSON schemas. Descriptions are present and adequate (118-130 chars, within the 10-1024 baseline range). However, several gaps limit overall quality: (1) Parameter descriptions are minimal or missing context about constraints; (2) No documented output schemas, callers must infer structure from implementation; (3) Error handling provides basic failure messages but no recovery guidance; (4) No tool annotations (readOnlyHint) despite both tools being read-only; (5) Limited parameter validation messaging. The tools are functional and reasonably well-named, but fall short of production excellence in the areas of output documentation and error recovery.
Tools (2)
read_notesread onlysource verified73/100
Read one or more Obsidian notes by their relative paths. Returns parsed note data including metadata and tags.
search_notesread onlysource verified75/100
Search through Obsidian notes using ripgrep. Returns matching notes with context lines.
No documented output schema. Tools return JSON but callers must infer structure from implementation (search results vs note metadata format). LLM cannot plan downstream operations without knowing which fields to expect.
Parameter descriptions lack constraint information. Example: 'context_lines' described as 'Number of context lines to show (default: 5)' but no range (min/max) specified. LLM could pass 0, 1000, or negative values. Should state '(default: 5, range: 1-50)' or similar.
Error messages provide no recovery guidance. Code returns 'Error: {error.message}' without context. Pattern: 'Pattern required for search_notes' (good) vs 'Paths array is required for read_notes' (bare message, no suggestion). Should include hints like 'Try search_notes(pattern="your-term") first to discover available notes.'
search_notesread_notes
Recommendations
Document output schemas for both tools. Example for search_notes: 'Returns {matches: [{file: string, lineNumber: number, context: string, matchedText: string}], totalMatches: number}'. For read_notes: 'Returns {notes: [{path: string, title: string, frontmatter: object, content: string, tags: string[]}], failedPaths: [{path: string, reason: string}]}'. This enables LLM to understand available fields.
Add constraint descriptions to numeric parameters. Replace 'Number of context lines to show (default: 5)' with 'Number of context lines to show (default: 5, range: 1-50, must be positive integer)'. Similar for any unbounded numbers.
Enhance error messages with recovery hints. Example: 'Pattern is required for search_notes. Provide a regex or literal string to search within note content. Example: search_notes(pattern="TODO") to find all TODOs.' Wrap error message construction to include actionable context.
Add tool annotations to the tool definitions in ListToolsRequestSchema. Include readOnlyHint: true and idempotentHint: true for both tools since neither modifies state. Agents will benefit from knowing these are safe to retry.
Document result limits and pagination in descriptions. Add statement like 'Returns up to 50 matching files (for search_notes). Use context_lines parameter to control output verbosity.' For read_notes: 'Reads up to 50 notes per call for safety. Provide file paths with or without .md extension.'
Clarify path handling for read_notes. Add to description: 'Paths are relative to OBSIDIAN_VAULT_PATH. Provide with or without .md extension (e.g., "folder/note" or "folder/note.md"). Returns error if path does not exist.' Include examples.
No tool annotations despite both tools being read-only. Should include 'readOnlyHint: true' in tool definitions so LLM and agents know these operations are safe to retry and have no side effects.
No pagination or result limits documented. search_notes could return hundreds of matching lines; read_notes accepts up to 50 paths but makes no statement about max result size. Pattern baseline: tools should cap results at 20-50 items and offer pagination. No limit stated in descriptions.
Parameter 'paths' for read_notes has array type but minimal description. No guidance on: whether .md extension required, relative vs absolute path handling, max array length (code enforces 50 but description silent), or error handling for non-existent paths.
read_notes
Add per-parameter enum constraints where appropriate. Example: if case_sensitive, whole_word, multiline can only be true/false, make that explicit in schema (already done, good). Consider enum for multiline if regex flags have constraints.
Validate and reject oversized inputs explicitly. Code enforces 50-note limit for read_notes but does not document in description. Add: 'Maximum 50 paths per call. Provide fewer paths if you encounter limits.' Return clear error: 'Too many paths (got 73, max 50). Please split into multiple calls.'
Consider adding a discover/list tool. Users may not know note paths. A 'list_notes' tool with optional search term would enable: 'list_notes(pattern="project")' to discover available notes before reading them. This reduces failed read calls.
Log tool invocations with key parameters for observability (already partially done via console.error). Ensure error logs include: tool name, input parameters (sanitized), error message, and recovery hint. This aids debugging agent misbehavior.