Vault MCP demonstrates solid fundamentals: all 5 tools have clear verb-noun names (list_, read_, write_, delete_, search_), descriptions between 80-180 chars, and complete Zod schemas with typed parameters. Tool descriptions accurately convey purpose and state-changing intent (write_note, delete_note). Parameters are well-described with examples ('user_profile/identity.md'). However, output schemas are not documented, callers cannot see what fields to expect from responses. Error handling is present but generic (VaultError wrapping). No tool annotations (readOnlyHint, destructiveHint) despite clear risk profiles. search_notes correctly constrains limit (1-30, default 10) following pagination best practices.

• Document output schemas for all tools. E.g., list_notes returns {notes: [{path: string}], truncated: boolean}; search_notes returns {hits: [{path: string, fragments: string[]}]}. Include these in tool descriptions or a separate schema reference.
• Add tool annotations via MCP SDK: mark list_notes, read_note, search_notes with readOnlyHint=true; mark write_note and delete_note with destructiveHint=true; mark write_note with idempotentHint=true (overwrites are idempotent).
• Enhance error messages with recovery guidance. E.g., 'Note not found at user_profile/identity.md. Try search_notes("identity") to find similar notes.' or 'Write failed: path must end in .md'.
• Refactor search_notes response to return structured JSON: {hits: [{path, fragments: []}]} instead of markdown blocks. Easier for LLMs to parse and chain to read_note.
• Add optional dry_run parameter to delete_note (default false). When true, return what would be deleted without committing. Agents can preview before confirming.