diff --git a/README.md b/README.md
index b387b61f1..77efbd0df 100644
--- a/README.md
+++ b/README.md
@@ -853,7 +853,7 @@ The following sets of tools are available:
 - **issue_write** - Create or update issue
   - **Required OAuth Scopes**: `repo`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body content (Markdown). On `method="update"`, this REPLACES the entire issue body; use `add_issue_comment` to add a comment without modifying the body. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
diff --git a/docs/feature-flags.md b/docs/feature-flags.md
index a552e71a0..5bc11f802 100644
--- a/docs/feature-flags.md
+++ b/docs/feature-flags.md
@@ -54,7 +54,7 @@ runtime behavior (such as output formatting) won't appear here.
   - **Required OAuth Scopes**: `repo`
   - **MCP App UI**: `ui://github-mcp-server/issue-write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body content (Markdown). On `method="update"`, this REPLACES the entire issue body; use `add_issue_comment` to add a comment without modifying the body. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
diff --git a/docs/insiders-features.md b/docs/insiders-features.md
index c221b8758..732df7363 100644
--- a/docs/insiders-features.md
+++ b/docs/insiders-features.md
@@ -48,7 +48,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
   - **Required OAuth Scopes**: `repo`
   - **MCP App UI**: `ui://github-mcp-server/issue-write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body content (Markdown). On `method="update"`, this REPLACES the entire issue body; use `add_issue_comment` to add a comment without modifying the body. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
diff --git a/pkg/github/__toolsnaps__/issue_write.snap b/pkg/github/__toolsnaps__/issue_write.snap
index a125864f0..e4930dae0 100644
--- a/pkg/github/__toolsnaps__/issue_write.snap
+++ b/pkg/github/__toolsnaps__/issue_write.snap
@@ -22,7 +22,7 @@
         "type": "array"
       },
       "body": {
-        "description": "Issue body content",
+        "description": "Issue body content (Markdown). On `method=\"update\"`, this REPLACES the entire issue body; use `add_issue_comment` to add a comment without modifying the body.",
         "type": "string"
       },
       "duplicate_of": {
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 0074bbd58..16804db06 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -1471,7 +1471,7 @@ Options are:
 					},
 					"body": {
 						Type:        "string",
-						Description: "Issue body content",
+						Description: "Issue body content (Markdown). On `method=\"update\"`, this REPLACES the entire issue body; use `add_issue_comment` to add a comment without modifying the body.",
 					},
 					"assignees": {
 						Type:        "array",