From e41bb3798cfd793db637dd3ab793c4fddafec103 Mon Sep 17 00:00:00 2001
From: John CSA <103165870+jluocsa@users.noreply.github.com>
Date: Thu, 7 May 2026 20:16:55 -0700
Subject: [PATCH] warn that issue_write body REPLACES content, not appends

The `body` parameter on `issue_write` (method='update') replaces the
entire issue body, matching REST API semantics. However, LLM agents
frequently misinterpret `body` as "add a note about this issue" and
end up silently destroying the original issue description (#2410).

Update the parameter description to make the replace-not-append
semantics explicit and to point users at `add_issue_comment` for the
common "leave a note" use case.

Updates the issue_write toolsnap and README accordingly.

Fixes #2410.
---
 README.md                                 | 2 +-
 pkg/github/__toolsnaps__/issue_write.snap | 2 +-
 pkg/github/issues.go                      | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5f9baa780e..21ad688f7e 100644
--- a/README.md
+++ b/README.md
@@ -839,7 +839,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, it does NOT append. To add a comment to an issue without modifying its body, use the add_issue_comment tool instead. (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 24cff5df97..95e4094d3f 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, it does NOT append. To add a comment to an issue without modifying its body, use the add_issue_comment tool instead.",
         "type": "string"
       },
       "duplicate_of": {
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 81161626bb..4c98b60db6 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -1017,7 +1017,7 @@ Options are:
 					},
 					"body": {
 						Type:        "string",
-						Description: "Issue body content",
+						Description: "Issue body content (Markdown). On method='update', this REPLACES the entire issue body, it does NOT append. To add a comment to an issue without modifying its body, use the add_issue_comment tool instead.",
 					},
 					"assignees": {
 						Type:        "array",