From 7f204102f21b66ecedab5014d504452117fd2e19 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 1/2] 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 +- docs/feature-flags.md | 2 +- docs/insiders-features.md | 2 +- pkg/github/__toolsnaps__/issue_write.snap | 2 +- pkg/github/issues.go | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b387b61f1..c1e2da461 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). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool. (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..089699edf 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). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool. (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..d9f40e2b7 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). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool. (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..ba48568e4 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). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool.", "type": "string" }, "duplicate_of": { diff --git a/pkg/github/issues.go b/pkg/github/issues.go index 0074bbd58..120b93e0e 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). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool.", }, "assignees": { Type: "array", From 532c950188926075ee0455d9cb53fa5cfaa03040 Mon Sep 17 00:00:00 2001 From: John CSA <103165870+jluocsa@users.noreply.github.com> Date: Fri, 22 May 2026 20:08:30 -0700 Subject: [PATCH 2/2] docs(issue_write): tighten body description and add inline code formatting Address reviewer feedback on the issue_write body warning: - Use backticks around method="update" and add_issue_comment so they render as inline code in the README rather than as plain prose. - Tighten the sentence (drop the redundant 'rather than appending to it' and 'without modifying the body'). - Keep REPLACES as the single emphatic marker, which is the entire point of #2410 (LLM agents silently destroying issue bodies on update). Regenerates pkg/github/__toolsnaps__/issue_write.snap and the auto-generated README / docs surfaces via script/generate-docs. --- README.md | 2 +- docs/feature-flags.md | 2 +- docs/insiders-features.md | 2 +- pkg/github/__toolsnaps__/issue_write.snap | 2 +- pkg/github/issues.go | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c1e2da461..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 (Markdown). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool. (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 089699edf..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 (Markdown). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool. (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 d9f40e2b7..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 (Markdown). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool. (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 ba48568e4..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 (Markdown). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool.", + "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 120b93e0e..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 (Markdown). When method='update', this REPLACES the entire issue body rather than appending to it; to add a comment without modifying the body, use the add_issue_comment tool.", + 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",