@mandujs/mcp 0.18.2 → 0.18.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",

package/src/activity-monitor.ts

@@ -7,7 +7,7 @@
 
 import fs from "fs";
 import path from "path";
-import { spawn, type ChildProcess } from "child_process";
+import type { Subprocess } from "bun";
 
 const TOOL_ICONS: Record<string, string> = {
   // Spec
@@ -266,7 +266,7 @@ function writeDefaultConfig(projectRoot: string, config: Required<MonitorConfig>
 export class ActivityMonitor {
   private logFile = "";
   private logStream: fs.WriteStream | null = null;
-  private tailProcess: ChildProcess | null = null;
+  private tailProcess: Subprocess | null = null;
   private projectRoot: string;
   private config: Required<MonitorConfig>;
   private outputFormat: MonitorOutputFormat;
@@ -813,9 +813,9 @@ export class ActivityMonitor {
   private openTerminal(): void {
     try {
       if (process.platform === "win32") {
-        this.tailProcess = spawn(
-          "cmd",
+        this.tailProcess = Bun.spawn(
           [
+            "cmd",
             "/c",
             "start",
             "Mandu Activity Monitor",
@@ -824,22 +824,19 @@ export class ActivityMonitor {
             "-Command",
             `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; chcp 65001 | Out-Null; Get-Content '${this.logFile}' -Wait -Encoding UTF8`,
           ],
-          { cwd: this.projectRoot, detached: true, stdio: "ignore" }
+          { cwd: this.projectRoot, stdio: ["ignore", "ignore", "ignore"] }
         );
       } else if (process.platform === "darwin") {
-        this.tailProcess = spawn(
-          "osascript",
-          ["-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`],
-          { detached: true, stdio: "ignore" }
+        this.tailProcess = Bun.spawn(
+          ["osascript", "-e", `tell application "Terminal" to do script "tail -f '${this.logFile}'"`],
+          { stdio: ["ignore", "ignore", "ignore"] }
         );
       } else {
-        this.tailProcess = spawn(
-          "x-terminal-emulator",
-          ["-e", `tail -f '${this.logFile}'`],
-          { cwd: this.projectRoot, detached: true, stdio: "ignore" }
+        this.tailProcess = Bun.spawn(
+          ["x-terminal-emulator", "-e", `tail -f '${this.logFile}'`],
+          { cwd: this.projectRoot, stdio: ["ignore", "ignore", "ignore"] }
         );
       }
-      this.tailProcess?.unref();
     } catch {
       // Terminal auto-open failed silently
     }

package/src/server.ts

@@ -322,7 +322,10 @@ export class ManduMcpServer {
  * 리소스 패턴 매칭
  */
 function matchResourcePattern(pattern: string, uri: string): boolean {
-  const regexPattern = pattern.replace(/\{[^}]+\}/g, "([^/]+)");
+  const regexPattern = pattern
+    .split(/\{[^}]+\}/)
+    .map(part => part.replace(/[.+*?^${}()|[\]\\]/g, "\\$&"))
+    .join("([^/]+)");
   const regex = new RegExp(`^${regexPattern}$`);
   return regex.test(uri);
 }
@@ -332,10 +335,16 @@ function matchResourcePattern(pattern: string, uri: string): boolean {
  */
 function extractResourceParams(pattern: string, uri: string): Record<string, string> {
   const paramNames: string[] = [];
-  const regexPattern = pattern.replace(/\{([^}]+)\}/g, (_, name) => {
-    paramNames.push(name);
-    return "([^/]+)";
-  });
+  const regexPattern = pattern
+    .split(/\{([^}]+)\}/)
+    .map((part, index) => {
+      if (index % 2 === 1) {
+        paramNames.push(part);
+        return "([^/]+)";
+      }
+      return part.replace(/[.+*?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
 
   const regex = new RegExp(`^${regexPattern}$`);
   const match = uri.match(regex);

package/src/tools/ate.ts

@@ -14,61 +14,110 @@ import {
 export const ateToolDefinitions: Tool[] = [
   {
     name: "mandu.ate.extract",
-    description: "ATE: AST 기반 상호작용 그래프 추출",
+    description:
+      "ATE Step 1 — Extract: Statically analyze the Mandu project's AST to build an interaction graph of routes, slots, contracts, and data flow. " +
+      "Identifies all testable interactions without running the server. " +
+      "Output is stored in .mandu/ate/extract/ and used by mandu.ate.generate.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        tsconfigPath: { type: "string" },
-        routeGlobs: { type: "array", items: { type: "string" } },
-        buildSalt: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        tsconfigPath: { type: "string", description: "Path to tsconfig.json (default: tsconfig.json in repoRoot)" },
+        routeGlobs: {
+          type: "array",
+          items: { type: "string" },
+          description: "Glob patterns to limit which routes are analyzed (e.g. ['app/api/**', 'app/blog/**']). Omit for all routes.",
+        },
+        buildSalt: {
+          type: "string",
+          description: "Cache invalidation salt — change this to force re-extraction even if source hasn't changed",
+        },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.generate",
-    description: "ATE: 시나리오 생성 + Playwright spec codegen",
+    description:
+      "ATE Step 2 — Generate: Create Playwright test scenarios from the interaction graph produced by mandu.ate.extract. " +
+      "Oracle level controls assertion depth: " +
+      "L0 = no assertions (smoke test only), " +
+      "L1 = basic HTTP status checks, " +
+      "L2 = contract schema validation (response shape matches Zod contract), " +
+      "L3 = full behavioral contract (side effects, state changes, error paths). " +
+      "Output: .mandu/ate/tests/*.spec.ts ready to run with Playwright.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        oracleLevel: { type: "string", enum: ["L0", "L1", "L2", "L3"] },
-        onlyRoutes: { type: "array", items: { type: "string" } },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        oracleLevel: {
+          type: "string",
+          enum: ["L0", "L1", "L2", "L3"],
+          description: "Assertion depth: L0=smoke, L1=HTTP status, L2=contract schema, L3=full behavioral",
+        },
+        onlyRoutes: {
+          type: "array",
+          items: { type: "string" },
+          description: "Limit test generation to specific routeIds (e.g. ['api-users', 'blog-slug']). Omit for all routes.",
+        },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.run",
-    description: "ATE: Playwright runner 실행(artifacts 수집)",
+    description:
+      "ATE Step 3 — Run: Execute the generated Playwright specs against a running Mandu dev server. " +
+      "Collects test artifacts (screenshots, traces, results) in .mandu/ate/runs/{runId}/. " +
+      "Requires the Mandu dev server to be running (use mandu_dev_start first). " +
+      "Returns a runId for use with mandu.ate.report and mandu.ate.heal.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        baseURL: { type: "string" },
-        ci: { type: "boolean" },
-        headless: { type: "boolean" },
-        browsers: { type: "array", items: { type: "string", enum: ["chromium", "firefox", "webkit"] } },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        baseURL: {
+          type: "string",
+          description: "Dev server URL (default: http://localhost:3333). Must match the running mandu dev server.",
+        },
+        ci: { type: "boolean", description: "CI mode: stricter timeouts, no interactive prompts" },
+        headless: { type: "boolean", description: "Run browsers headlessly (default: true)" },
+        browsers: {
+          type: "array",
+          items: { type: "string", enum: ["chromium", "firefox", "webkit"] },
+          description: "Browsers to test against (default: ['chromium'])",
+        },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.report",
-    description: "ATE: 테스트 리포트 생성 (JSON, HTML, 또는 both)",
+    description:
+      "ATE Step 4 — Report: Generate a test report from run artifacts. " +
+      "Produces pass/fail summary, coverage by route, and failure details. " +
+      "Use the runId returned by mandu.ate.run. " +
+      "If tests failed, follow up with mandu.ate.heal to get fix suggestions.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        runId: { type: "string" },
-        startedAt: { type: "string" },
-        finishedAt: { type: "string" },
-        exitCode: { type: "number" },
-        oracleLevel: { type: "string", enum: ["L0", "L1", "L2", "L3"] },
-        format: { type: "string", enum: ["json", "html", "both"], description: "리포트 포맷 (기본값: both)" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID returned by mandu.ate.run" },
+        startedAt: { type: "string", description: "ISO timestamp when run started" },
+        finishedAt: { type: "string", description: "ISO timestamp when run finished" },
+        exitCode: { type: "number", description: "Playwright process exit code (0=pass, non-zero=fail)" },
+        oracleLevel: {
+          type: "string",
+          enum: ["L0", "L1", "L2", "L3"],
+          description: "Oracle level used during generation (for report context)",
+        },
+        format: {
+          type: "string",
+          enum: ["json", "html", "both"],
+          description: "Report format: json (machine-readable), html (visual), both (default)",
+        },
         impact: {
           type: "object",
+          description: "Impact analysis context — set if tests were run on a subset of routes via mandu.ate.impact",
           properties: {
             mode: { type: "string", enum: ["full", "subset"] },
             changedFiles: { type: "array", items: { type: "string" } },
@@ -82,61 +131,89 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.heal",
-    description: "ATE: 실패 원인 분류 + 복구 제안(diff) 생성 (자동 커밋 금지)",
+    description:
+      "ATE Step 5 — Heal: Analyze test failures from a run and generate safe diff suggestions for fixing the code. " +
+      "Classifies failures by root cause (schema mismatch, missing handler, wrong status, selector stale, etc.) " +
+      "and produces reviewable diffs — never auto-commits or overwrites files. " +
+      "Use mandu.ate.apply_heal to apply a specific suggestion after review. " +
+      "Supports rollback via mandu_rollback if applied changes cause regressions.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        runId: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID from mandu.ate.run with failures to analyze" },
       },
       required: ["repoRoot", "runId"],
     },
   },
   {
     name: "mandu.ate.impact",
-    description: "ATE: git diff 기반 subset 계산",
+    description:
+      "ATE Optimization — Impact Analysis: Calculate the minimal subset of routes affected by changed files using git diff. " +
+      "Avoids running the full test suite when only part of the codebase changed. " +
+      "Returns selectedRoutes to pass to mandu.ate.generate (onlyRoutes) or mandu.ate.run. " +
+      "Typical use: run after `git commit` to test only affected routes in CI.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        base: { type: "string" },
-        head: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        base: { type: "string", description: "Git base ref for diff (default: HEAD~1 or main branch)" },
+        head: { type: "string", description: "Git head ref for diff (default: current working tree)" },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.auto_pipeline",
-    description: "ATE: 전체 파이프라인 자동 실행 (Extract → Generate → Run → Report → Heal)",
+    description:
+      "ATE Full Pipeline — Run the complete ATE cycle in one call: " +
+      "Extract AST → Generate Playwright specs → Run tests → Create report → Suggest heals. " +
+      "Recommended for: initial setup, scheduled CI runs, and full regression testing. " +
+      "For incremental development, prefer individual steps (extract → generate → run → report → heal). " +
+      "Set useImpactAnalysis=true to automatically limit tests to changed routes.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string" },
-        baseURL: { type: "string" },
-        oracleLevel: { type: "string", enum: ["L0", "L1", "L2", "L3"] },
-        ci: { type: "boolean" },
-        useImpactAnalysis: { type: "boolean" },
-        base: { type: "string" },
-        head: { type: "string" },
-        autoHeal: { type: "boolean" },
-        tsconfigPath: { type: "string" },
-        routeGlobs: { type: "array", items: { type: "string" } },
-        buildSalt: { type: "string" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        baseURL: { type: "string", description: "Dev server URL (default: http://localhost:3333)" },
+        oracleLevel: {
+          type: "string",
+          enum: ["L0", "L1", "L2", "L3"],
+          description: "Assertion depth: L0=smoke, L1=HTTP status, L2=contract schema, L3=full behavioral",
+        },
+        ci: { type: "boolean", description: "CI mode: stricter timeouts" },
+        useImpactAnalysis: {
+          type: "boolean",
+          description: "Run impact analysis first and only test changed routes (faster in CI)",
+        },
+        base: { type: "string", description: "Git base ref for impact analysis" },
+        head: { type: "string", description: "Git head ref for impact analysis" },
+        autoHeal: {
+          type: "boolean",
+          description: "Automatically run heal analysis after failures (produces diff suggestions, never auto-applies)",
+        },
+        tsconfigPath: { type: "string", description: "Path to tsconfig.json" },
+        routeGlobs: { type: "array", items: { type: "string" }, description: "Limit extraction to specific route patterns" },
+        buildSalt: { type: "string", description: "Cache invalidation salt for extraction" },
       },
       required: ["repoRoot"],
     },
   },
   {
     name: "mandu.ate.feedback",
-    description: "ATE: 테스트 실패 원인 분석 및 heal 제안 평가",
+    description:
+      "ATE Feedback — Evaluate heal suggestions from a failed run and classify which fixes are safe to auto-apply. " +
+      "Safe-to-auto-apply: selector-map updates (CSS selector changes). " +
+      "Requires human review: contract schema changes, handler logic, route restructuring. " +
+      "Returns priority ranking of suggestions to guide review order.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string", description: "프로젝트 루트 디렉토리" },
-        runId: { type: "string", description: "테스트 실행 ID" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID with heal suggestions to evaluate" },
         autoApply: {
           type: "boolean",
-          description: "자동 적용 가능 여부 (selector-map만 안전)",
+          description: "If true, auto-apply only selector-map changes (CSS selectors) — other changes always require review",
         },
       },
       required: ["repoRoot", "runId"],
@@ -144,19 +221,23 @@ export const ateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.ate.apply_heal",
-    description: "ATE: heal diff를 실제 코드에 적용 (rollback 가능)",
+    description:
+      "ATE Apply — Apply a specific heal suggestion diff to the codebase. " +
+      "Always creates a backup snapshot first (use mandu_rollback to undo). " +
+      "Run mandu.ate.feedback first to get the healIndex and confirm the fix is safe. " +
+      "After applying, re-run mandu.ate.run to verify the fix resolved the failure.",
     inputSchema: {
       type: "object",
       properties: {
-        repoRoot: { type: "string", description: "프로젝트 루트 디렉토리" },
-        runId: { type: "string", description: "테스트 실행 ID" },
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
+        runId: { type: "string", description: "Run ID containing the heal suggestion to apply" },
         healIndex: {
           type: "number",
-          description: "적용할 heal suggestion의 인덱스 (0부터 시작)",
+          description: "0-based index of the heal suggestion to apply (from mandu.ate.heal or mandu.ate.feedback results)",
         },
         createBackup: {
           type: "boolean",
-          description: "백업 생성 여부 (기본값: true, 필수 권장)",
+          description: "Create a snapshot before applying (default: true, strongly recommended — enables mandu_rollback)",
         },
       },
       required: ["repoRoot", "runId", "healIndex"],

package/src/tools/brain.ts

@@ -26,7 +26,7 @@ import {
   generateJsonStatus,
   initializeArchitectureAnalyzer,
   getArchitectureAnalyzer,
-} from "../../../core/src/index.js";
+} from "@mandujs/core";
 import { getProjectPaths } from "../utils/project.js";
 
 export const brainToolDefinitions: Tool[] = [

package/src/tools/contract.ts

@@ -16,7 +16,15 @@ import fs from "fs/promises";
 export const contractToolDefinitions: Tool[] = [
   {
     name: "mandu_list_contracts",
-    description: "List all contracts in the current Mandu project",
+    description:
+      "List all routes that have a contract module defined. " +
+      "In Mandu, a 'contract' is a Zod-based schema file (spec/contracts/{routeId}.contract.ts) that defines " +
+      "the request/response shape for an API route. Contracts enable: " +
+      "(1) automatic input validation and sanitization (strip/strict/passthrough normalize modes), " +
+      "(2) TypeScript type inference for slot handlers, " +
+      "(3) OpenAPI 3.0 spec generation via mandu_generate_openapi, " +
+      "(4) ATE L2 (schema validation) and L3 (full behavioral) test generation. " +
+      "Also returns a list of API routes that are missing contracts.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -25,13 +33,17 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_get_contract",
-    description: "Get details of a specific contract by route ID",
+    description:
+      "Get the full TypeScript source of a contract file for a specific route. " +
+      "Returns the raw content of spec/contracts/{routeId}.contract.ts, " +
+      "which contains Zod schemas for each HTTP method's request body/query params and response shape. " +
+      "If the route has no contract, returns a suggestion to create one with mandu_create_contract.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to retrieve contract for",
+          description: "The route ID to retrieve the contract for",
         },
       },
       required: ["routeId"],
@@ -39,22 +51,27 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_create_contract",
-    description: "Create a new contract for a route",
+    description:
+      "Create a new contract file for a route and link it in the manifest. " +
+      "Generates spec/contracts/{routeId}.contract.ts with Zod schema stubs for each HTTP method. " +
+      "Template includes: request schema (body for POST/PUT/PATCH, query for GET/DELETE) and response schema. " +
+      "After creation: edit the Zod schemas to match your actual API shape, " +
+      "then run mandu_generate to regenerate typed handlers with validation.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to create contract for",
+          description: "The route ID to create a contract for",
         },
         description: {
           type: "string",
-          description: "API description (optional)",
+          description: "Human-readable API description added as a comment in the contract file",
         },
         methods: {
           type: "array",
           items: { type: "string" },
-          description: "HTTP methods to include (default: route methods or ['GET', 'POST'])",
+          description: "HTTP methods to generate schemas for (default: route's declared methods or ['GET', 'POST'])",
         },
       },
       required: ["routeId"],
@@ -62,7 +79,11 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_update_route_contract",
-    description: "Update a route to add or change its contract module",
+    description:
+      "Update the manifest to link an existing contract file to a route. " +
+      "Use this when the contract file already exists but the manifest's contractModule path needs updating, " +
+      "or when moving a contract file to a new location. " +
+      "Does not modify the contract file itself — only updates the manifest reference and lock file.",
     inputSchema: {
       type: "object",
       properties: {
@@ -72,7 +93,7 @@ export const contractToolDefinitions: Tool[] = [
         },
         contractModule: {
           type: "string",
-          description: "Path to contract file (e.g., spec/contracts/users.contract.ts)",
+          description: "Relative path to the contract file from project root (e.g., spec/contracts/users.contract.ts)",
         },
       },
       required: ["routeId", "contractModule"],
@@ -80,7 +101,12 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_validate_contracts",
-    description: "Validate all contracts against their slot implementations",
+    description:
+      "Validate all contracts against their linked slot implementations for consistency. " +
+      "Checks that every HTTP method defined in a contract has a matching handler in the slot, " +
+      "response types are compatible, and no orphaned contracts exist. " +
+      "Run this after modifying contracts or slots, or before running ATE tests to catch mismatches early. " +
+      "Returns a list of violations with file locations, descriptions, and fix suggestions.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -89,18 +115,27 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_sync_contract_slot",
-    description: "Sync contract and slot to resolve mismatches",
+    description:
+      "Detect and generate code to resolve HTTP method mismatches between a contract and its slot. " +
+      "'contract-to-slot': finds HTTP methods defined in the contract but missing from the slot — " +
+      "generates handler stub code to add to the slot file. " +
+      "'slot-to-contract': finds slot handlers not documented in the contract — " +
+      "generates Zod schema stubs to add to the contract. " +
+      "Returns generated code snippets to review — does NOT auto-write files. " +
+      "Copy the output and use the Edit tool to apply the changes.",
     inputSchema: {
       type: "object",
       properties: {
         routeId: {
           type: "string",
-          description: "The route ID to sync",
+          description: "The route ID to sync (must have both contractModule and slotModule)",
         },
         direction: {
           type: "string",
           enum: ["contract-to-slot", "slot-to-contract"],
-          description: "Direction of sync: contract-to-slot adds slot stubs, slot-to-contract adds contract schemas",
+          description:
+            "'contract-to-slot': generate slot handler stubs for undocumented contract methods. " +
+            "'slot-to-contract': generate contract schema stubs for undocumented slot handlers.",
         },
       },
       required: ["routeId", "direction"],
@@ -108,21 +143,25 @@ export const contractToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_generate_openapi",
-    description: "Generate OpenAPI 3.0 specification from contracts",
+    description:
+      "Generate an OpenAPI 3.0 specification JSON file from all routes with contract modules. " +
+      "Only routes with a defined contractModule are included — add contracts with mandu_create_contract first. " +
+      "Output is written to openapi.json (or a custom path). " +
+      "The generated spec can be served with Swagger UI, Redoc, or imported into any OpenAPI-compatible tooling.",
     inputSchema: {
       type: "object",
       properties: {
         output: {
           type: "string",
-          description: "Output file path (default: openapi.json)",
+          description: "Output file path relative to project root (default: openapi.json)",
         },
         title: {
           type: "string",
-          description: "API title (default: Mandu API)",
+          description: "API title shown in the spec (default: 'Mandu API')",
         },
         version: {
           type: "string",
-          description: "API version (default: from manifest)",
+          description: "API version string (default: taken from the manifest version)",
         },
       },
       required: [],

package/src/tools/generate.ts

@@ -8,17 +8,27 @@ export const generateToolDefinitions: Tool[] = [
   {
     name: "mandu_generate",
     description:
-      "Generate route handlers, components, and resource artifacts. Creates server handlers, page components, slot files, and resource CRUD operations.",
+      "Generate all Mandu framework artifacts from the current routes manifest and resource schemas. " +
+      "Runs two generation steps: " +
+      "(1) Route generation: for every route in .mandu/routes.manifest.json, creates " +
+      "a server-side handler in .mandu/generated/server/{routeId}.route.ts and " +
+      "a web component in .mandu/generated/web/{routeId}.route.tsx. " +
+      "These generated files wire up slots and contracts automatically — do NOT edit them directly. " +
+      "Instead, edit source files in app/ (route definition) or spec/ (slots, contracts). " +
+      "(2) Resource generation (resources=true, default): scans spec/resources/{name}/schema.ts " +
+      "and generates CRUD boilerplate (repository, service, handlers) for each declared resource. " +
+      "Run this after adding routes, modifying slot/contract files, or changing resource schemas. " +
+      "Use dryRun=true to preview what would be created or overwritten without writing any files.",
     inputSchema: {
       type: "object",
       properties: {
         dryRun: {
           type: "boolean",
-          description: "If true, show what would be generated without writing files",
+          description: "Preview what would be generated without writing files (default: false)",
         },
         resources: {
           type: "boolean",
-          description: "Include resource artifact generation (default: true)",
+          description: "Include resource artifact generation from spec/resources/ (default: true)",
         },
       },
       required: [],
@@ -26,7 +36,11 @@ export const generateToolDefinitions: Tool[] = [
   },
   {
     name: "mandu_generate_status",
-    description: "Get the current generation status and generated file map",
+    description:
+      "Show the current state of all generated artifacts from .mandu/generated.map.json. " +
+      "Returns: generation timestamp, source spec version, total file count, " +
+      "and a list of generated files per route with their kinds (server handler, web component, slot stub). " +
+      "If no generated.map.json exists, prompts to run mandu_generate first.",
     inputSchema: {
       type: "object",
       properties: {},