diff --git a/packages/core/src/agent/agent-system-prompt.ts b/packages/core/src/agent/agent-system-prompt.ts
index ba76cbf0..a8469a34 100644
--- a/packages/core/src/agent/agent-system-prompt.ts
+++ b/packages/core/src/agent/agent-system-prompt.ts
@@ -82,8 +82,8 @@ export function buildAgentSystemPrompt(bookId: string | null, language: string):
 - **write_truth_file** — 整文件覆盖真相文件（story_bible、volume_outline、book_rules、current_focus 等）
 - **rename_entity** — 统一改角色/实体名
 - **patch_chapter_text** — 对已有章节做局部定点修补
-- **edit** — 通用精确字符串替换编辑
-- **write** — 新建或整文件覆盖写入
+- **edit** — 在设定文件里做精确字符串替换（章节正文请用 patch_chapter_text）
+- **write** — 新建文件，或者重写整个文件（已有内容会被覆盖；真相文件优先用 write_truth_file，章节修订用 revise_chapter）
 - **grep** — 搜索内容（如"哪一章提到了某个角色"）
 - **ls** — 列出文件或章节
 
@@ -131,8 +131,8 @@ export function buildAgentSystemPrompt(bookId: string | null, language: string):
 - **write_truth_file** — Replace a canonical truth file in story/
 - **rename_entity** — Rename a character or entity across the book
 - **patch_chapter_text** — Apply a local deterministic patch to a chapter
-- **edit** — Generic exact string replacement editor
-- **write** — Create or fully overwrite a file
+- **edit** — Exact string replacement on setting files (use patch_chapter_text for chapter text)
+- **write** — Create a new file, or fully replace an existing file's content (prefer write_truth_file for canonical truth files, revise_chapter for chapter revisions)
 - **grep** — Search content across chapters
 - **ls** — List files or chapters
 
diff --git a/packages/core/src/agent/agent-tools.ts b/packages/core/src/agent/agent-tools.ts
index d1a2a61f..9a061a67 100644
--- a/packages/core/src/agent/agent-tools.ts
+++ b/packages/core/src/agent/agent-tools.ts
@@ -393,8 +393,9 @@ export function createEditTool(projectRoot: string): AgentTool<typeof EditParams
   return {
     name: "edit",
     description:
-      "Edit a file using exact string replacement. " +
-      "old_string must appear exactly once in the file. Path is relative to books/.",
+      "Edit a file under books/ via exact string replacement. " +
+      "old_string must appear exactly once in the file. " +
+      "For chapter text use patch_chapter_text; for canonical truth files (story_bible/volume_outline/book_rules/current_focus) prefer write_truth_file.",
     label: "Edit File",
     parameters: EditParams,
     async execute(
@@ -436,8 +437,9 @@ export function createWriteFileTool(projectRoot: string): AgentTool<typeof Write
   return {
     name: "write",
     description:
-      "Create a new file or overwrite an existing file. " +
-      "Path is relative to books/. Parent directories are created automatically.",
+      "Create a new file, or fully replace an existing file's content under books/. " +
+      "Parent directories are created automatically. Existing content is overwritten silently — " +
+      "for canonical truth files prefer write_truth_file; for chapter revisions use revise_chapter.",
     label: "Write File",
     parameters: WriteFileParams,
     async execute(