Bernard exposes 6 tools with clear naming (verb_noun pattern: search, add, list, invalidate, update, suggest) and reasonable descriptions (avg ~100 chars). All tools have input schemas using Zod with type definitions. However, parameter descriptions are minimal or missing context about constraints, valid values, and error recovery. Output schemas are not documented, responses are formatted as text blobs rather than structured objects. Error handling is basic (returns text messages but no recovery guidance). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk profiles (WRITE, REVERSIBLE, READ_ONLY). Missing pagination for list/search despite potential for large result sets.

• Add tool annotations to server.registerTool() calls: readOnlyHint for bernard_search/list/suggest, destructiveHint for bernard_invalidate, idempotentHint for bernard_add (if deduplication is supported). See MCP SDK docs for annotation syntax.
• Restructure all tool responses to return JSON objects instead of text blobs. E.g., bernard_search should return { records: [{ id, type, title, content, tags, score }], total: N } instead of formatted text. This enables LLM parsing and tool chaining.
• Document parameter constraints in descriptions. For bernard_add type param, add: 'One of: decision, architecture, bug, preference, note'. For bernard_suggest n param, add: 'Number of commits to fetch (1-50, default 5)'.
• Add pagination to bernard_list and bernard_search: accept limit (1-100, default 20) and offset parameters; return total count and next_offset in response. Cap results at 20-50 items per call.
• Enhance error messages with recovery guidance. E.g., 'Record ID "xyz" not found. Try bernard_search() to find records by content, or bernard_list() to see all records.' Include available options when applicable.