docs: improve MCP tool definition quality

Author: ZengLiangYi

server/README.md

@@ -120,11 +120,12 @@ Add to `settings.json`:
 
 | Tool | Description |
 |------|-------------|
-| `search_knowledge` | Semantic search across notes |
+| `search_knowledge` | Semantic search across notes when you need relevance-ranked matches |
 | `get_note` | Get full note content (summary, conclusions, code snippets) |
-| `list_notes` | Browse notes by tag or keyword |
+| `list_notes` | Browse paginated note summaries by tag or title/summary keyword |
 | `get_relations` | Get related notes with relationship types |
-| `recall_for_task` | Recall project-first memories for a coding task |
+| `recall_for_task` | Read-only task recall that loads project memories first, then optional global lessons |
+| `validate_task_memory` | Dry-run validation before writing a task memory; returns acceptance, reasons, warnings, and note fields |
 | `write_task_memory` | Persist reusable task memories after meaningful work |
 
 ## Configuration

server/src/cli/mcp/server.ts

@@ -9,6 +9,28 @@ import {
   WriteTaskMemoryRequestShape,
 } from '../../services/memory/schemas.js';
 
+const LIST_NOTES_DESCRIPTION = [
+  'List note summaries for browsing and narrowing the ChatCrystal knowledge base.',
+  'Use this when you need paginated notes filtered by tag or title/summary keyword.',
+  'Use search_knowledge instead for semantic relevance ranking, and get_note when you already have an id and need the full note body.',
+  'Returns note metadata and summaries, not full note content.',
+].join(' ');
+
+const RECALL_FOR_TASK_DESCRIPTION = [
+  'Retrieve reusable task memories before starting substantive coding work.',
+  'Use this at the beginning of implementation, debugging, migration, configuration, investigation, refactor, or optimization tasks to load project-scoped memories first and optional global lessons second.',
+  'Use mode="debug" when the user reports an error, failing command, regression, or incident; include error_signatures and related_files when available.',
+  'Use search_knowledge instead for ad hoc semantic note search that is not tied to the current task.',
+  'This tool is read-only and returns ranked memories plus optional related-note context without writing anything.',
+].join(' ');
+
+const VALIDATE_TASK_MEMORY_DESCRIPTION = [
+  'Dry-run validation for a candidate task memory before calling write_task_memory.',
+  'Use this after meaningful work and before persisting a lesson to check whether the candidate is durable, specific, reusable, and shaped like a high-quality ChatCrystal note.',
+  'It has no side effects and never writes to the knowledge base.',
+  'Returns acceptance, rejection reason, warnings, and materialized note fields so agents can revise the candidate or skip weak work logs.',
+].join(' ');
+
 export async function startMcpServer(options?: string | CrystalClientOptions) {
   const client = new CrystalClient(options);
   const status = await client.status();
@@ -58,11 +80,11 @@ export async function startMcpServer(options?: string | CrystalClientOptions) {
   // Tool 3: list_notes
   server.tool(
     'list_notes',
-    'Browse notes in the knowledge base. Filter by tag or keyword search.',
+    LIST_NOTES_DESCRIPTION,
     {
-      tag: z.string().optional().describe('Filter by tag name'),
-      search: z.string().optional().describe('Filter by keyword in title/summary'),
-      page: z.number().optional().default(1).describe('Page number'),
+      tag: z.string().optional().describe('Exact tag name to filter notes by, for example "mcp" or "cursor".'),
+      search: z.string().optional().describe('Literal keyword filter applied to note title and summary; not semantic search.'),
+      page: z.number().optional().default(1).describe('1-based page number for paginated note summaries. Each page returns up to 20 notes.'),
     },
     async ({ tag, search, page }) => {
       const limit = 20;
@@ -97,7 +119,7 @@ export async function startMcpServer(options?: string | CrystalClientOptions) {
 
   server.tool(
     'recall_for_task',
-    'Recall project-first and global-supplement memories for a task.',
+    RECALL_FOR_TASK_DESCRIPTION,
     RecallForTaskRequestShape,
     async (input) => {
       const data = await client.recallForTask(input);
@@ -112,7 +134,7 @@ export async function startMcpServer(options?: string | CrystalClientOptions) {
 
   server.tool(
     'validate_task_memory',
-    'Preflight a task memory candidate without side effects. Use this before write_task_memory when available. Returns materialized ChatCrystal note fields, acceptance, reason, and warnings.',
+    VALIDATE_TASK_MEMORY_DESCRIPTION,
     ValidateTaskMemoryRequestShape,
     async (input) => {
       const data = await client.validateTaskMemory(input);

server/src/services/memory/schemas.ts

@@ -7,10 +7,10 @@ export const SourceAgentSchema = z.enum([
   'cursor',
   'trae',
   'unknown',
-]);
+]).describe('AI coding tool or agent that is calling ChatCrystal; use unknown when unsure.');
 
 const TaskBaseSchema = z.object({
-  goal: z.string().min(1),
+  goal: z.string().min(1).describe('Plain-language task goal or user request. Include enough context to retrieve relevant memories.'),
   task_kind: z.enum([
     'debug',
     'implement',
@@ -19,70 +19,70 @@ const TaskBaseSchema = z.object({
     'config',
     'investigate',
     'optimization',
-  ]),
-  project_key: z.string().optional(),
-  project_dir: z.string().optional(),
-  cwd: z.string().optional(),
-  branch: z.string().optional(),
-  files_touched: z.array(z.string()).optional(),
-  error_signatures: z.array(z.string()).optional(),
+  ]).describe('Kind of work being performed. Use debug for failures; choose the closest non-debug category for planned work.'),
+  project_key: z.string().optional().describe('Stable project identifier used to prioritize project-scoped memories, such as a repository or workspace key.'),
+  project_dir: z.string().optional().describe('Absolute project directory when known; helps ChatCrystal match memories to the right local workspace.'),
+  cwd: z.string().optional().describe('Current working directory of the agent session.'),
+  branch: z.string().optional().describe('Current VCS branch when relevant to the task.'),
+  files_touched: z.array(z.string()).optional().describe('Files already touched or expected to be touched; improves project memory matching.'),
+  error_signatures: z.array(z.string()).optional().describe('Concrete errors, stack traces, failing commands, or symptoms. Most useful with debug tasks.'),
   source_agent: SourceAgentSchema.optional(),
 });
 
 const RecallTaskSchema = TaskBaseSchema.extend({
-  related_files: z.array(z.string()).optional(),
+  related_files: z.array(z.string()).optional().describe('Additional files related to the task but not necessarily modified.'),
 });
 
 const NormalizedTaskSchema = TaskBaseSchema.transform((task) => ({
   ...task,
   source_agent: task.source_agent ?? 'unknown',
-}));
+})).describe('Current task context used to scope, rank, and store memories.');
 
 export const RecallForTaskOptionsShape = {
-  project_limit: z.number().int().nonnegative().default(5),
-  global_limit: z.number().int().nonnegative().default(3),
-  include_relations: z.boolean().default(true),
+  project_limit: z.number().int().nonnegative().default(5).describe('Maximum number of project-scoped memories to return first.'),
+  global_limit: z.number().int().nonnegative().default(3).describe('Maximum number of cross-project/global lessons to append after project memories.'),
+  include_relations: z.boolean().default(true).describe('Whether to include related-note context for returned memories.'),
 } as const;
 
 export const RecallForTaskRequestShape = {
-  mode: z.enum(['task', 'debug']).default('task'),
+  mode: z.enum(['task', 'debug']).default('task').describe('Use task for normal work and debug when the task starts from an error, failing test, or incident.'),
   task: RecallTaskSchema.transform((task) => ({
     ...task,
     source_agent: task.source_agent ?? 'unknown',
-  })),
-  options: z.object(RecallForTaskOptionsShape).optional(),
+  })).describe('Current task context used to retrieve relevant project and global memories.'),
+  options: z.object(RecallForTaskOptionsShape).optional().describe('Optional limits and relation expansion controls for recall results.'),
 } as const;
 
 export const RecallForTaskRequestSchema = z.object(RecallForTaskRequestShape);
 
 export const WriteTaskMemoryPayloadShape = {
-  title: z.string().optional(),
-  summary: z.string().min(1),
-  outcome_type: z.enum(['pitfall', 'fix', 'pattern', 'decision']),
-  pitfalls: z.array(z.string()).optional(),
-  root_cause: z.string().optional(),
-  resolution: z.string().optional(),
-  reusable_patterns: z.array(z.string()).optional(),
-  decisions: z.array(z.string()).optional(),
-  key_conclusions: z.array(z.string()).optional(),
+  title: z.string().optional().describe('Specific note title. Prefer the durable lesson over a generic task name.'),
+  summary: z.string().min(1).describe('Concrete summary of what was learned or decided, written so it remains useful in a later session.'),
+  outcome_type: z.enum(['pitfall', 'fix', 'pattern', 'decision']).describe('Primary kind of reusable memory being saved.'),
+  pitfalls: z.array(z.string()).optional().describe('Mistakes, traps, or failure modes future agents should avoid.'),
+  root_cause: z.string().optional().describe('Underlying cause of the problem when the memory is about a fix or pitfall.'),
+  resolution: z.string().optional().describe('Specific fix or action that resolved the issue.'),
+  reusable_patterns: z.array(z.string()).optional().describe('Generalizable implementation, debugging, migration, or configuration patterns.'),
+  decisions: z.array(z.string()).optional().describe('Durable design, product, architecture, or process decisions made during the task.'),
+  key_conclusions: z.array(z.string()).optional().describe('Important takeaways that should be recalled before similar future work.'),
   code_snippets: z.array(
     z.object({
-      language: z.string(),
-      code: z.string(),
-      description: z.string(),
+      language: z.string().describe('Programming or markup language for the snippet.'),
+      code: z.string().describe('Minimal code, command, config, or query that illustrates the reusable lesson.'),
+      description: z.string().describe('Why this snippet matters and when to reuse it.'),
     }),
-  ).optional(),
-  files_touched: z.array(z.string()).optional(),
-  error_signatures: z.array(z.string()).optional(),
-  tags: z.array(z.string()).optional(),
+  ).optional().describe('Small snippets that make the memory actionable without copying large files.'),
+  files_touched: z.array(z.string()).optional().describe('Files that provide useful provenance for the memory.'),
+  error_signatures: z.array(z.string()).optional().describe('Exact errors or symptoms that should trigger this memory in future debug recall.'),
+  tags: z.array(z.string()).optional().describe('Short tags for retrieval, such as framework, subsystem, source tool, or failure type.'),
 } as const;
 
 export const WriteTaskMemoryRequestShape = {
-  mode: z.enum(['auto', 'manual']),
-  source_run_key: z.string().optional(),
-  scope: z.enum(['project', 'global']).optional(),
+  mode: z.enum(['auto', 'manual']).describe('Use auto for agent-generated writebacks and manual for explicit user-curated memories.'),
+  source_run_key: z.string().optional().describe('Idempotency key for auto writebacks; required in auto mode to avoid duplicate memory receipts.'),
+  scope: z.enum(['project', 'global']).optional().describe('Store as project memory by default; global is reserved for broadly reusable manual lessons.'),
   task: NormalizedTaskSchema,
-  memory: z.object(WriteTaskMemoryPayloadShape),
+  memory: z.object(WriteTaskMemoryPayloadShape).describe('Candidate ChatCrystal note content to validate or persist as reusable task memory.'),
 } as const;
 
 export const WriteTaskMemoryRequestSchema = z