markdown-vault-mcp defines 5 tools with reasonable coverage of input schemas and descriptions. All tools have descriptions (10-50 chars median, well within 10-1024 range) that explain the action clearly. Schemas are mostly complete with proper enum constraints and type definitions. However, several tools exhibit parameter structure issues: the 'vault' and 'edit' tools accept multiple optional parameters that are interdependent but lack explicit documentation of those dependencies. Output schemas are not visible in the provided source, so composition efficiency cannot be verified. Error handling is minimal, no evidence of recovery guidance, retry classification, or actionable error messages. The 'edit' tool description is exceptionally detailed (excellent), but others are more generic. No tool exposes secrets, and destructive operations are marked with Risk labels, but no dry-run or confirmation patterns are explicitly enforced at the SDK layer.

• Document the return type and field structure for each tool. Example: 'vault list action returns {success: bool, files: [{path: string, mtime: number, size: number}], total: number}'. Without this, LLMs cannot chain results into downstream tools.
• Add explicit parameter dependency rules to 'vault' and 'edit' schemas. Example: 'When action=list, directory is required and path/content/templatePath must be omitted. When action=read, path is required. When action=create_from_template, templatePath and variables are required.'
• Make dryRun an explicit, documented parameter in the 'edit' tool schema with default=true to encourage preview-before-execute workflows. Document that dryRun=false requires explicit user confirmation in the agent flow.
• Add a 'confirm' parameter or implement a two-phase pattern for destructive vault operations: first call returns a confirmation_token; second call includes that token to execute. This prevents accidental deletions from mid-plan failures.
• Enhance error messages with recovery guidance. Example: Instead of 'File not found', return 'File at path="notes/old.md" not found. Did you mean: notes/archive/old.md? (or search_vault for "old" to find similar files).'
• Add format/constraint hints to parameter descriptions: 'path (string, required): Relative file path from vault root, e.g. "notes/2024/january.md", use forward slashes, no leading slash.' Similar for templatePath (must be a .template file), query (min 1 char, max 100), limit (1-50).
• Consider accepting partial path matches or aliases. Example: allow 'design' to resolve to 'notes/project/design.md' if unambiguous, reducing need for upfront path discovery.