The server provides 11 tools with good naming conventions (all start with action verbs: list_, get_, search_, execute_). Descriptions are present for all tools and most are substantive (100-200 chars), meeting the 10-1024 character guideline. However, there are critical gaps in schema completeness and parameter descriptions. All tools have input schemas defined with proper type information (object with typed fields), but parameter descriptions vary significantly in quality. Output schemas are documented in code but not explicitly exposed to clients. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present despite the spec supporting them since 2025. Error handling is minimal, no recovery guidance, no actionable error messages, and no indication of retryable vs fatal errors. All tools are read-only (which reduces risk), but the lack of error patterns and output documentation limits LLM reasoning quality.

• Add readOnlyHint: true to all 11 tool definitions to signal to LLMs that these tools are safe to call without user confirmation.
• Formalize output schemas in MCP tool definitions using a structured 'output' or 'result_schema' field. Example: { 'type': 'object', 'properties': { 'id': { 'type': 'string' }, 'title': { 'type': 'string' }, ... }, 'required': [...] }. This enables LLM planning without inspecting code.
• Implement structured error handling: catch exceptions from use cases and return { 'error': 'NOT_FOUND', 'message': 'Document "Notes/Missing.md" not found in vault "main". Available documents in Notes/: [list]. Try search_documents() if path is uncertain.', 'retryable': false }. Guide LLM next steps explicitly.
• Enhance parameter descriptions with constraints and examples. Change 'The vault slug' to 'The vault slug (unique identifier, 2-50 lowercase alphanumeric + hyphens, example: "my-vault")'.
• Add total_count and next_cursor fields to list_documents, list_tables, list_rows responses. Example: { 'items': [...], 'total_count': 150, 'next_cursor': 'offset_50' }. This enables LLMs to handle large result sets correctly.
• Validate mutually exclusive parameters in get_document. Add logic: if both 'path' and 'document_id' are provided, return error: 'Cannot specify both path and document_id. Choose one.' Prevents ambiguous calls.
• Add an optional 'explain_when_to_use' field to search_documents description clarifying the difference between semantic (vector/embedding-based) and fulltext search. LLMs often conflate them.