vault-mcp has 12 tools with basic schemas and descriptions, but significant quality gaps. Tool names lack consistent verb-noun structure (vault_resolve, vault_search are acceptable; vault_dashboard, vault_profile are vague). Descriptions are present but generic, most are 20-80 chars, below the 50-200 char LLM-optimized baseline. Parameter descriptions exist but lack actionable constraints (no enums, ranges, or format specs). Output schemas are not documented, responses are JSON-stringified text, not structured objects. Error handling returns raw error messages without recovery guidance. No tool annotations (readOnlyHint/destructiveHint). Risk classifications are declared but not enforced in schema.

• Document output schemas for all tools. Define typed response objects (e.g., {skills: [{id, name, description, tags}], total_count, next_cursor}) instead of JSON-stringified text. This enables LLMs to extract and chain data.
• Convert free-form string parameters to enums where applicable. E.g., vault_search 'type' should be enum('agent'|'task'|'command'|'skill'). Add min/max bounds to numeric params (limit: 1-100, quick: boolean).
• Enhance error messages with recovery guidance. E.g., 'Provide id or squad. Example: id="design:agent:brad-frost" or squad="design"' or 'Candidate not found. Call vault_list_candidates() to see pending candidates.'
• Rename noun-only tools to verb-noun form: vault_dashboard → generate_dashboard, vault_profile → detect_profile, vault_config → get_config/set_config. This clarifies intent and improves LLM tool selection.
• Add tool annotations to schema. Mark vault_approve_candidate, vault_reject_candidate, vault_scan, vault_config with destructiveHint=true. Mark vault_resolve, vault_search, vault_list_candidates, vault_dashboard, vault_profile with readOnlyHint=true.