refactor(pull-requests): type granular MCP tools

Preserve exact legacy validation and response text while advertising concrete protocol-gated outputs for all granular PR mutations and both thread-resolution variants.

Make the inherited overflow assertion architecture-independent.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

docs/feature-flags.md

@@ -237,23 +237,23 @@ as output formatting) won't appear here.
   - `path`: The relative path of the file to comment on (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
-  - `side`: The side of the diff to comment on (optional) (string, optional)
+  - `side`: The side of the diff to comment on (LEFT or RIGHT, optional) (string, optional)
   - `startLine`: The start line of a multi-line comment (optional) (number, optional)
-  - `startSide`: The start side of a multi-line comment (optional) (string, optional)
-  - `subjectType`: The subject type of the comment (string, required)
+  - `startSide`: The start side of a multi-line comment (LEFT or RIGHT, optional) (string, optional)
+  - `subjectType`: The subject type of the comment (FILE or LINE) (string, required)
 
 - **add_pull_request_review_comment_reaction** - Add Pull Request Review Comment Reaction
   - **OAuth Challenge Scopes**: `repo`
   - `comment_id`: The numeric pull request review comment ID. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...). (number, required)
-  - `content`: The emoji reaction type (string, required)
+  - `content`: The emoji reaction type (+1, -1, laugh, confused, heart, hooray, rocket, or eyes) (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
   - `repo`: Repository name (string, required)
 
 - **create_pull_request_review** - Create Pull Request Review
   - **OAuth Challenge Scopes**: `repo`
   - `body`: The review body text (optional) (string, optional)
   - `commitID`: The SHA of the commit to review (optional, defaults to latest) (string, optional)
-  - `event`: The review action to perform. If omitted, creates a pending review. (string, optional)
+  - `event`: The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review. (string, optional)
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
@@ -300,7 +300,7 @@ as output formatting) won't appear here.
 - **submit_pending_pull_request_review** - Submit Pending Pull Request Review
   - **OAuth Challenge Scopes**: `repo`
   - `body`: The review body text (optional) (string, optional)
-  - `event`: The review action to perform (string, required)
+  - `event`: The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT) (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
@@ -341,7 +341,7 @@ as output formatting) won't appear here.
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
-  - `state`: The new state for the pull request (string, required)
+  - `state`: The new state for the pull request (open or closed) (string, required)
 
 - **update_pull_request_title** - Update Pull Request Title
   - **OAuth Challenge Scopes**: `repo`

pkg/github/__toolsnaps__/add_pull_request_review_comment.snap

@@ -27,39 +27,26 @@
       },
       "pullNumber": {
         "description": "The pull request number",
-        "minimum": 1,
         "type": "number"
       },
       "repo": {
         "description": "Repository name",
         "type": "string"
       },
       "side": {
-        "description": "The side of the diff to comment on (optional)",
-        "enum": [
-          "LEFT",
-          "RIGHT"
-        ],
+        "description": "The side of the diff to comment on (LEFT or RIGHT, optional)",
         "type": "string"
       },
       "startLine": {
         "description": "The start line of a multi-line comment (optional)",
         "type": "number"
       },
       "startSide": {
-        "description": "The start side of a multi-line comment (optional)",
-        "enum": [
-          "LEFT",
-          "RIGHT"
-        ],
+        "description": "The start side of a multi-line comment (LEFT or RIGHT, optional)",
         "type": "string"
       },
       "subjectType": {
-        "description": "The subject type of the comment",
-        "enum": [
-          "FILE",
-          "LINE"
-        ],
+        "description": "The subject type of the comment (FILE or LINE)",
         "type": "string"
       }
     },

pkg/github/__toolsnaps__/add_pull_request_review_comment_reaction.snap

@@ -11,21 +11,10 @@
     "properties": {
       "comment_id": {
         "description": "The numeric pull request review comment ID. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...).",
-        "minimum": 1,
         "type": "number"
       },
       "content": {
-        "description": "The emoji reaction type",
-        "enum": [
-          "+1",
-          "-1",
-          "laugh",
-          "confused",
-          "heart",
-          "hooray",
-          "rocket",
-          "eyes"
-        ],
+        "description": "The emoji reaction type (+1, -1, laugh, confused, heart, hooray, rocket, or eyes)",
         "type": "string"
       },
       "owner": {

pkg/github/__toolsnaps__/add_pull_request_review_comment_reaction_typed.snap

@@ -0,0 +1,68 @@
+{
+  "annotations": {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": true,
+    "readOnlyHint": false,
+    "title": "Add Pull Request Review Comment Reaction"
+  },
+  "description": "Add a reaction to a pull request review comment.",
+  "icons": [
+    {
+      "mimeType": "image/png",
+      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAACwUlEQVRIie2Vz28UZRjHP993pi0QIC3YahNjirtmd3bS3Q1eUHvQEPUiEv8A4kXjwRJ78MCFBLjBBRKCHowHE38cNCbGGx6IUoKiodtNpoNmTJp4oSJNQ3pw29l5POxus2wo3QTwxPc0887zfD7zvu9kXnjEUfdNrjj5vJOmMP4e9JrfR1G02tuQD8tvgpck0dxCPwK30ViqnJTcr4bOmfRlI/PrhUJ5313woDpDpu8ss7f6nYHrvDnGcYlPsoY/bKaXwHY3HWfvgmNnMX0zvMM7069A3c3pkEYWa7UVgFxQPSfs7SSeH3k2rEy5jMubMBoG1yQ+SBbm53of+gCybMkk/H8VAFdbZisZLAFsJ11oyL+BUURcwrjWAZixXeIwxs/5UuVAr0QAYRjubGR+HWy3mb6QCIBXQe8nce0jgIkwfMo3/xLG085x8I9ofkMyUa0O+w2rgS0mcf3lboEDiKJo1cvsIDDr4D1DhTb8407hYhTdTJW+AvrdMnuhG9Je1m9BBzbfjXbyQcXypeqJLQt7+0rVE/mgYr3j7l7FDzOPBY8FDx6vc1EolPeNjI5/Jpgw7Lm9o+Pry//c/K0PhnLFyrSMDxE79jwxvn9079gvt28vrUD7V1EoFHalbltd2C7DfS4sAF4DTSdx7cL96LliZVriPPADuL+geRh0Z8il5SiKVn2ATENvCCYw78U/b8xdBcgHlYuGHQXuK5A4ClxM4vnXW8Lqp5JdWWt6h4CvWnsgxgDSbRZ3Gg0tCJ7sY4nGwDZOt/WBZtzN9FswLgM2sGann5mcPDaw5pWEHQH7cUu86SdkR3LF6tfrA814MNVpwNrM1leUxPXrSKfMeHcwdctyNotY8c3NbMX3LJsB3ZHsymDqlkHvYHYyievXWxPpSj4o75eYIuPWZof+vRKG4c61pncIx6gZsx34/5L/ACy3ElqUYhuvAAAAAElFTkSuQmCC",
+      "theme": "light"
+    },
+    {
+      "mimeType": "image/png",
+      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAABn0lEQVRIie2Vvy5EURDGvyMUkhUU/pS2Q2clwvIKqL0Cm9ArrBcQShJPoLFR2YaIhIjQ7a7E39IiCgqVn8KsPY697E3oTHPumTPf990z986M9Mfm/A0wKGlMUlnSlnPuOQQAE5LOnXOFWErAIvBK1S6BZBAzZ2fzcckHjXwVaAXSwD2wWYN8A2iKK1ABt3m+ZeDRnseIthdgDxioxd1o662tfZIO7Lnf8xcklST1StqRdORxNEualHQIDDvnTmvdIGE5vwdWgLy93bQX0w0UgSdgKMC3AdfA7ndpSgKbduUbYBoI/7Ju4BiYrYFfAl4iBbxAgOyPgV9xWYDQ3xCXKK79C/wL/KJZoeW8QpsJCy0C54AMULaGmQu7sIAW4MpaxTKwbQU3U4dAxmLzwLpxXAIJP2jKgkY8Xx4o1SFwBmx7+7RxTUnVb9Bpa9HDFiR1/SRgWH+6FT3/h2qK6sBpB0aBB7yB880NcpaWtGHXjCsVBmb5PDIvgJ46BJKW84q9AguV87Adp/Q+9O8UMfQjRBKSxiV1SNp3zp3Ug/sVewPruexhKwhGXQAAAABJRU5ErkJggg==",
+      "theme": "dark"
+    }
+  ],
+  "inputSchema": {
+    "properties": {
+      "comment_id": {
+        "description": "The numeric pull request review comment ID. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...).",
+        "type": "number"
+      },
+      "content": {
+        "description": "The emoji reaction type (+1, -1, laugh, confused, heart, hooray, rocket, or eyes)",
+        "type": "string"
+      },
+      "owner": {
+        "description": "Repository owner (username or organization)",
+        "type": "string",
+        "x-mcp-header": "owner"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string",
+        "x-mcp-header": "repo"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "comment_id",
+      "content"
+    ],
+    "type": "object"
+  },
+  "name": "add_pull_request_review_comment_reaction",
+  "outputSchema": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "url"
+    ],
+    "type": "object"
+  }
+}

pkg/github/__toolsnaps__/add_pull_request_review_comment_typed.snap

@@ -0,0 +1,90 @@
+{
+  "annotations": {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": true,
+    "readOnlyHint": false,
+    "title": "Add Pull Request Review Comment"
+  },
+  "description": "Add a review comment to the current user's pending pull request review.",
+  "icons": [
+    {
+      "mimeType": "image/png",
+      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAACwUlEQVRIie2Vz28UZRjHP993pi0QIC3YahNjirtmd3bS3Q1eUHvQEPUiEv8A4kXjwRJ78MCFBLjBBRKCHowHE38cNCbGGx6IUoKiodtNpoNmTJp4oSJNQ3pw29l5POxus2wo3QTwxPc0887zfD7zvu9kXnjEUfdNrjj5vJOmMP4e9JrfR1G02tuQD8tvgpck0dxCPwK30ViqnJTcr4bOmfRlI/PrhUJ5313woDpDpu8ss7f6nYHrvDnGcYlPsoY/bKaXwHY3HWfvgmNnMX0zvMM7069A3c3pkEYWa7UVgFxQPSfs7SSeH3k2rEy5jMubMBoG1yQ+SBbm53of+gCybMkk/H8VAFdbZisZLAFsJ11oyL+BUURcwrjWAZixXeIwxs/5UuVAr0QAYRjubGR+HWy3mb6QCIBXQe8nce0jgIkwfMo3/xLG085x8I9ofkMyUa0O+w2rgS0mcf3lboEDiKJo1cvsIDDr4D1DhTb8407hYhTdTJW+AvrdMnuhG9Je1m9BBzbfjXbyQcXypeqJLQt7+0rVE/mgYr3j7l7FDzOPBY8FDx6vc1EolPeNjI5/Jpgw7Lm9o+Pry//c/K0PhnLFyrSMDxE79jwxvn9079gvt28vrUD7V1EoFHalbltd2C7DfS4sAF4DTSdx7cL96LliZVriPPADuL+geRh0Z8il5SiKVn2ATENvCCYw78U/b8xdBcgHlYuGHQXuK5A4ClxM4vnXW8Lqp5JdWWt6h4CvWnsgxgDSbRZ3Gg0tCJ7sY4nGwDZOt/WBZtzN9FswLgM2sGann5mcPDaw5pWEHQH7cUu86SdkR3LF6tfrA814MNVpwNrM1leUxPXrSKfMeHcwdctyNotY8c3NbMX3LJsB3ZHsymDqlkHvYHYyievXWxPpSj4o75eYIuPWZof+vRKG4c61pncIx6gZsx34/5L/ACy3ElqUYhuvAAAAAElFTkSuQmCC",
+      "theme": "light"
+    },
+    {
+      "mimeType": "image/png",
+      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAABn0lEQVRIie2Vvy5EURDGvyMUkhUU/pS2Q2clwvIKqL0Cm9ArrBcQShJPoLFR2YaIhIjQ7a7E39IiCgqVn8KsPY697E3oTHPumTPf990z986M9Mfm/A0wKGlMUlnSlnPuOQQAE5LOnXOFWErAIvBK1S6BZBAzZ2fzcckHjXwVaAXSwD2wWYN8A2iKK1ABt3m+ZeDRnseIthdgDxioxd1o662tfZIO7Lnf8xcklST1StqRdORxNEualHQIDDvnTmvdIGE5vwdWgLy93bQX0w0UgSdgKMC3AdfA7ndpSgKbduUbYBoI/7Ju4BiYrYFfAl4iBbxAgOyPgV9xWYDQ3xCXKK79C/wL/KJZoeW8QpsJCy0C54AMULaGmQu7sIAW4MpaxTKwbQU3U4dAxmLzwLpxXAIJP2jKgkY8Xx4o1SFwBmx7+7RxTUnVb9Bpa9HDFiR1/SRgWH+6FT3/h2qK6sBpB0aBB7yB880NcpaWtGHXjCsVBmb5PDIvgJ46BJKW84q9AguV87Adp/Q+9O8UMfQjRBKSxiV1SNp3zp3Ug/sVewPruexhKwhGXQAAAABJRU5ErkJggg==",
+      "theme": "dark"
+    }
+  ],
+  "inputSchema": {
+    "properties": {
+      "body": {
+        "description": "The comment body",
+        "type": "string"
+      },
+      "line": {
+        "description": "The line number in the diff to comment on (optional)",
+        "type": "number"
+      },
+      "owner": {
+        "description": "Repository owner (username or organization)",
+        "type": "string",
+        "x-mcp-header": "owner"
+      },
+      "path": {
+        "description": "The relative path of the file to comment on",
+        "type": "string"
+      },
+      "pullNumber": {
+        "description": "The pull request number",
+        "type": "number"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string",
+        "x-mcp-header": "repo"
+      },
+      "side": {
+        "description": "The side of the diff to comment on (LEFT or RIGHT, optional)",
+        "type": "string"
+      },
+      "startLine": {
+        "description": "The start line of a multi-line comment (optional)",
+        "type": "number"
+      },
+      "startSide": {
+        "description": "The start side of a multi-line comment (LEFT or RIGHT, optional)",
+        "type": "string"
+      },
+      "subjectType": {
+        "description": "The subject type of the comment (FILE or LINE)",
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "pullNumber",
+      "path",
+      "body",
+      "subjectType"
+    ],
+    "type": "object"
+  },
+  "name": "add_pull_request_review_comment",
+  "outputSchema": {
+    "additionalProperties": false,
+    "properties": {
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "message"
+    ],
+    "type": "object"
+  }
+}

pkg/github/__toolsnaps__/create_pull_request_review.snap

@@ -18,12 +18,7 @@
         "type": "string"
       },
       "event": {
-        "description": "The review action to perform. If omitted, creates a pending review.",
-        "enum": [
-          "APPROVE",
-          "REQUEST_CHANGES",
-          "COMMENT"
-        ],
+        "description": "The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review.",
         "type": "string"
       },
       "owner": {
@@ -32,7 +27,6 @@
       },
       "pullNumber": {
         "description": "The pull request number",
-        "minimum": 1,
         "type": "number"
       },
       "repo": {

pkg/github/__toolsnaps__/create_pull_request_review_typed.snap

@@ -0,0 +1,71 @@
+{
+  "annotations": {
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": true,
+    "readOnlyHint": false,
+    "title": "Create Pull Request Review"
+  },
+  "description": "Create a review on a pull request. If event is provided, the review is submitted immediately; otherwise a pending review is created.",
+  "icons": [
+    {
+      "mimeType": "image/png",
+      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAACwUlEQVRIie2Vz28UZRjHP993pi0QIC3YahNjirtmd3bS3Q1eUHvQEPUiEv8A4kXjwRJ78MCFBLjBBRKCHowHE38cNCbGGx6IUoKiodtNpoNmTJp4oSJNQ3pw29l5POxus2wo3QTwxPc0887zfD7zvu9kXnjEUfdNrjj5vJOmMP4e9JrfR1G02tuQD8tvgpck0dxCPwK30ViqnJTcr4bOmfRlI/PrhUJ5313woDpDpu8ss7f6nYHrvDnGcYlPsoY/bKaXwHY3HWfvgmNnMX0zvMM7069A3c3pkEYWa7UVgFxQPSfs7SSeH3k2rEy5jMubMBoG1yQ+SBbm53of+gCybMkk/H8VAFdbZisZLAFsJ11oyL+BUURcwrjWAZixXeIwxs/5UuVAr0QAYRjubGR+HWy3mb6QCIBXQe8nce0jgIkwfMo3/xLG085x8I9ofkMyUa0O+w2rgS0mcf3lboEDiKJo1cvsIDDr4D1DhTb8407hYhTdTJW+AvrdMnuhG9Je1m9BBzbfjXbyQcXypeqJLQt7+0rVE/mgYr3j7l7FDzOPBY8FDx6vc1EolPeNjI5/Jpgw7Lm9o+Pry//c/K0PhnLFyrSMDxE79jwxvn9079gvt28vrUD7V1EoFHalbltd2C7DfS4sAF4DTSdx7cL96LliZVriPPADuL+geRh0Z8il5SiKVn2ATENvCCYw78U/b8xdBcgHlYuGHQXuK5A4ClxM4vnXW8Lqp5JdWWt6h4CvWnsgxgDSbRZ3Gg0tCJ7sY4nGwDZOt/WBZtzN9FswLgM2sGann5mcPDaw5pWEHQH7cUu86SdkR3LF6tfrA814MNVpwNrM1leUxPXrSKfMeHcwdctyNotY8c3NbMX3LJsB3ZHsymDqlkHvYHYyievXWxPpSj4o75eYIuPWZof+vRKG4c61pncIx6gZsx34/5L/ACy3ElqUYhuvAAAAAElFTkSuQmCC",
+      "theme": "light"
+    },
+    {
+      "mimeType": "image/png",
+      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAABn0lEQVRIie2Vvy5EURDGvyMUkhUU/pS2Q2clwvIKqL0Cm9ArrBcQShJPoLFR2YaIhIjQ7a7E39IiCgqVn8KsPY697E3oTHPumTPf990z986M9Mfm/A0wKGlMUlnSlnPuOQQAE5LOnXOFWErAIvBK1S6BZBAzZ2fzcckHjXwVaAXSwD2wWYN8A2iKK1ABt3m+ZeDRnseIthdgDxioxd1o662tfZIO7Lnf8xcklST1StqRdORxNEualHQIDDvnTmvdIGE5vwdWgLy93bQX0w0UgSdgKMC3AdfA7ndpSgKbduUbYBoI/7Ju4BiYrYFfAl4iBbxAgOyPgV9xWYDQ3xCXKK79C/wL/KJZoeW8QpsJCy0C54AMULaGmQu7sIAW4MpaxTKwbQU3U4dAxmLzwLpxXAIJP2jKgkY8Xx4o1SFwBmx7+7RxTUnVb9Bpa9HDFiR1/SRgWH+6FT3/h2qK6sBpB0aBB7yB880NcpaWtGHXjCsVBmb5PDIvgJ46BJKW84q9AguV87Adp/Q+9O8UMfQjRBKSxiV1SNp3zp3Ug/sVewPruexhKwhGXQAAAABJRU5ErkJggg==",
+      "theme": "dark"
+    }
+  ],
+  "inputSchema": {
+    "properties": {
+      "body": {
+        "description": "The review body text (optional)",
+        "type": "string"
+      },
+      "commitID": {
+        "description": "The SHA of the commit to review (optional, defaults to latest)",
+        "type": "string"
+      },
+      "event": {
+        "description": "The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review.",
+        "type": "string"
+      },
+      "owner": {
+        "description": "Repository owner (username or organization)",
+        "type": "string",
+        "x-mcp-header": "owner"
+      },
+      "pullNumber": {
+        "description": "The pull request number",
+        "type": "number"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string",
+        "x-mcp-header": "repo"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "pullNumber"
+    ],
+    "type": "object"
+  },
+  "name": "create_pull_request_review",
+  "outputSchema": {
+    "additionalProperties": false,
+    "properties": {
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "message"
+    ],
+    "type": "object"
+  }
+}

pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap

@@ -15,7 +15,6 @@
       },
       "pullNumber": {
         "description": "The pull request number",
-        "minimum": 1,
         "type": "number"
       },
       "repo": {