vault-mcp has 15 tools with complete input schemas and descriptions. Naming is verb-forward and clear (vault_search, vault_inject_env, vault_delete_secret). Descriptions are present and contextual (avg ~80 chars), explaining WHAT and WHEN. However, parameter descriptions are sparse, many lack detail on format, constraints, or dependencies. Output schemas are not documented in the tool definitions. Error handling is minimal; no recovery guidance or actionable error messages visible. Security is strong (secrets never exposed as params, server-side injection via environment), but composition could be tighter, vault_inject_env and vault_render_file overlap in intent. The INSTRUCTIONS resource is excellent for agent guidance but does not substitute for per-tool schema documentation.

• Document output schemas for all tools. Example: 'vault_search returns {results: [{path, description, tags, environment}], total_count}'. Include field types and what downstream tools expect.
• Enhance parameter descriptions with format constraints. For 'filePath', add '(absolute or relative path; must be writable)'. For 'passphrase', add '(10+ chars, alphanumeric + symbols)'. For 'environment', reference the enum values inline.
• Add error recovery hints to tool descriptions. E.g., vault_search: 'If no results, try vault_presets to see available services.' vault_restore: 'If restore fails, call vault_list_backups to verify the backup exists.'
• Clarify vault_inject_env vs vault_render_file in descriptions. E.g., inject_env: 'For .env files with KEY=VALUE format.' render_file: 'For config files with {{vault:path}} template placeholders.' Prevents tool confusion.
• Add a vault_confirm_delete tool or require a confirmation parameter (e.g., 'confirmed: true') for vault_delete_secret. Prevents accidental destructive operations by agents.