fix(github): restore canonical input descriptions

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
SamMorrowDrums · Oct 2, 2026 · Oct 5, 2026 · Oct 5, 2026 · Oct 6, 2026 · Oct 6, 2026
commit 1ca45339131aeb5b0934195e7b6c3937e077cc82
@@ -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 (LEFT or RIGHT, optional) (string, optional)
+  - `side`: The side of the diff to comment on (optional) (string, optional)
   - `startLine`: The start line of a multi-line comment (optional) (number, optional)
-  - `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)
+  - `startSide`: The start side of a multi-line comment (optional) (string, optional)
+  - `subjectType`: The subject type of the comment (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 (+1, -1, laugh, confused, heart, hooray, rocket, or eyes) (string, required)
+  - `content`: The emoji reaction type (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 (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review. (string, optional)
+  - `event`: The review action to perform. 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 (APPROVE, REQUEST_CHANGES, or COMMENT) (string, required)
+  - `event`: The review action to perform (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 (open or closed) (string, required)
+  - `state`: The new state for the pull request (string, required)
 
 - **update_pull_request_title** - Update Pull Request Title
   - **OAuth Challenge Scopes**: `repo`
@@ -402,8 +402,8 @@ as output formatting) won't appear here.
   - `confidence_threshold`: Minimum similarity threshold a candidate must meet to be returned; higher values are stricter. When omitted, the API's high-precision default is used. The scale is defined by the API, so no client-side bounds are enforced. (number, optional)
   - `issue_number`: The number of the existing issue to find duplicates for (number, required)
   - `owner`: The owner of the repository (string, required)
-  - `page`: Page number for pagination (min 1). An explicit 0 is forwarded to the API as-is rather than being replaced with 1. (number, optional)
-  - `perPage`: Results per page for pagination (min 1, max 100). An explicit 0 is forwarded to the API as-is rather than being replaced with 30. (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: The name of the repository (string, required)
 
 ### `thread_resolution_reason`

@@ -49,7 +49,7 @@
         "x-mcp-header": "repo"
       },
       "side": {
-        "description": "The side of the diff to comment on (LEFT or RIGHT, optional)",
+        "description": "The side of the diff to comment on (optional)",
         "enum": [
           "LEFT",
           "RIGHT"
@@ -61,15 +61,15 @@
         "type": "number"
       },
       "startSide": {
-        "description": "The start side of a multi-line comment (LEFT or RIGHT, optional)",
+        "description": "The start side of a multi-line comment (optional)",
         "enum": [
           "LEFT",
           "RIGHT"
         ],
         "type": "string"
       },
       "subjectType": {
-        "description": "The subject type of the comment (FILE or LINE)",
+        "description": "The subject type of the comment",
         "enum": [
           "FILE",
           "LINE"

@@ -27,7 +27,7 @@
         "type": "number"
       },
       "content": {
-        "description": "The emoji reaction type (+1, -1, laugh, confused, heart, hooray, rocket, or eyes)",
+        "description": "The emoji reaction type",
         "enum": [
           "+1",
           "-1",

@@ -30,7 +30,7 @@
         "type": "string"
       },
       "event": {
-        "description": "The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review.",
+        "description": "The review action to perform. If omitted, creates a pending review.",
         "enum": [
           "APPROVE",
           "REQUEST_CHANGES",

@@ -20,12 +20,12 @@
         "type": "string"
       },
       "page": {
-        "description": "Page number for pagination (min 1). An explicit 0 is forwarded to the API as-is rather than being replaced with 1.",
+        "description": "Page number for pagination (min 1)",
         "minimum": 1,
         "type": "number"
       },
       "perPage": {
-        "description": "Results per page for pagination (min 1, max 100). An explicit 0 is forwarded to the API as-is rather than being replaced with 30.",
+        "description": "Results per page for pagination (min 1, max 100)",
         "maximum": 100,
         "minimum": 1,
         "type": "number"

@@ -26,7 +26,7 @@
         "type": "string"
       },
       "event": {
-        "description": "The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT)",
+        "description": "The review action to perform",
         "enum": [
           "APPROVE",
           "REQUEST_CHANGES",

@@ -37,7 +37,7 @@
         "x-mcp-header": "repo"
       },
       "state": {
-        "description": "The new state for the pull request (open or closed)",
+        "description": "The new state for the pull request",
         "enum": [
           "open",
           "closed"

@@ -62,14 +62,6 @@ func FindDuplicate(t translations.TranslationHelperFunc) inventory.ServerTool {
 		Required: []string{"owner", "repo", "issue_number"},
 	}
 	WithPagination(schema)
-	// Unlike most tools, find_duplicate does not substitute its own default
-	// for an explicit 0: it forwards whatever page/perPage value is supplied
-	// (including 0) to the API unchanged, letting the API apply its own
-	// default. Document that exception here instead of relying solely on the
-	// generic WithPagination wording.
-	schema.Properties["page"].Description = "Page number for pagination (min 1). An explicit 0 is forwarded to the API as-is rather than being replaced with 1."
-	schema.Properties["perPage"].Description = "Results per page for pagination (min 1, max 100). An explicit 0 is forwarded to the API as-is rather than being replaced with 30."
-
 	st := NewToolWithSchemaOptions[FindDuplicateInput, []DuplicateCandidate](
 		ToolsetMetadataIssues,
 		mcp.Tool{

@@ -40,15 +40,11 @@ func Test_FindDuplicate(t *testing.T) {
 	assert.Contains(t, schema.Properties, "perPage")
 	assert.ElementsMatch(t, schema.Required, []string{"owner", "repo", "issue_number"})
 
-	// Unlike most paginated tools, find_duplicate forwards an explicit 0 to
-	// the API unchanged instead of substituting the usual default. The
-	// advertised minimum stays canonical (matching WithPagination), but the
-	// description must say so to avoid misleading callers.
 	assert.Equal(t, 1.0, *schema.Properties["page"].Minimum)
 	assert.Equal(t, 1.0, *schema.Properties["perPage"].Minimum)
 	assert.Equal(t, 100.0, *schema.Properties["perPage"].Maximum)
-	assert.Contains(t, schema.Properties["page"].Description, "An explicit 0 is forwarded to the API as-is")
-	assert.Contains(t, schema.Properties["perPage"].Description, "An explicit 0 is forwarded to the API as-is")
+	assert.Equal(t, "Page number for pagination (min 1)", schema.Properties["page"].Description)
+	assert.Equal(t, "Results per page for pagination (min 1, max 100)", schema.Properties["perPage"].Description)
 }
 
 func Test_FindDuplicate_RankedResults(t *testing.T) {

@@ -164,7 +164,7 @@ func GranularUpdatePullRequestState(t translations.TranslationHelperFunc) invent
 		map[string]*jsonschema.Schema{
 			"state": {
 				Type:        "string",
-				Description: "The new state for the pull request (open or closed)",
+				Description: "The new state for the pull request",
 				Enum:        GranularPullRequestState("").JSONSchema().Enum,
 			},
 		},
@@ -363,7 +363,7 @@ func GranularCreatePullRequestReview(t translations.TranslationHelperFunc) inven
 					"repo":       {Type: "string", Description: "Repository name"},
 					"pullNumber": {Type: "number", Description: "The pull request number", Minimum: new(1.0)},
 					"body":       {Type: "string", Description: "The review body text (optional)"},
-					"event":      {Type: "string", Description: "The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review.", Enum: GranularPullRequestReviewEvent("").JSONSchema().Enum},
+					"event":      {Type: "string", Description: "The review action to perform. If omitted, creates a pending review.", Enum: GranularPullRequestReviewEvent("").JSONSchema().Enum},
 					"commitID":   {Type: "string", Description: "The SHA of the commit to review (optional, defaults to latest)"},
 				},
 				Required: []string{"owner", "repo", "pullNumber"},
@@ -419,7 +419,7 @@ func GranularSubmitPendingPullRequestReview(t translations.TranslationHelperFunc
 					"owner":      {Type: "string", Description: "Repository owner (username or organization)"},
 					"repo":       {Type: "string", Description: "Repository name"},
 					"pullNumber": {Type: "number", Description: "The pull request number", Minimum: new(1.0)},
-					"event":      {Type: "string", Description: "The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT)", Enum: GranularPullRequestReviewEvent("").JSONSchema().Enum},
+					"event":      {Type: "string", Description: "The review action to perform", Enum: GranularPullRequestReviewEvent("").JSONSchema().Enum},
 					"body":       {Type: "string", Description: "The review body text (optional)"},
 				},
 				Required: []string{"owner", "repo", "pullNumber", "event"},
@@ -515,11 +515,11 @@ func GranularAddPullRequestReviewComment(t translations.TranslationHelperFunc) i
 					"pullNumber":  {Type: "number", Description: "The pull request number", Minimum: new(1.0)},
 					"path":        {Type: "string", Description: "The relative path of the file to comment on"},
 					"body":        {Type: "string", Description: "The comment body"},
-					"subjectType": {Type: "string", Description: "The subject type of the comment (FILE or LINE)", Enum: GranularPullRequestCommentSubject("").JSONSchema().Enum},
+					"subjectType": {Type: "string", Description: "The subject type of the comment", Enum: GranularPullRequestCommentSubject("").JSONSchema().Enum},
 					"line":        {Type: "number", Description: "The line number in the diff to comment on (optional)"},
-					"side":        {Type: "string", Description: "The side of the diff to comment on (LEFT or RIGHT, optional)", Enum: GranularPullRequestDiffSide("").JSONSchema().Enum},
+					"side":        {Type: "string", Description: "The side of the diff to comment on (optional)", Enum: GranularPullRequestDiffSide("").JSONSchema().Enum},
 					"startLine":   {Type: "number", Description: "The start line of a multi-line comment (optional)"},
-					"startSide":   {Type: "string", Description: "The start side of a multi-line comment (LEFT or RIGHT, optional)", Enum: GranularPullRequestDiffSide("").JSONSchema().Enum},
+					"startSide":   {Type: "string", Description: "The start side of a multi-line comment (optional)", Enum: GranularPullRequestDiffSide("").JSONSchema().Enum},
 				},
 				Required: []string{"owner", "repo", "pullNumber", "path", "body", "subjectType"},
 			},
@@ -742,7 +742,7 @@ func GranularAddPullRequestReviewCommentReaction(t translations.TranslationHelpe
 					},
 					"content": {
 						Type:        "string",
-						Description: "The emoji reaction type (+1, -1, laugh, confused, heart, hooray, rocket, or eyes)",
+						Description: "The emoji reaction type",
 						Enum:        PullRequestCommentReactionType("").JSONSchema().Enum,
 					},
 				},

@@ -436,6 +436,48 @@ func TestGranularPullRequestAdvertisedInputConstraints(t *testing.T) {
 	}
 }
 
+func TestTypedInputDescriptionsMatchMain(t *testing.T) {
+	descriptions := map[string]map[string]string{
+		"add_pull_request_review_comment": {
+			"side":        "The side of the diff to comment on (optional)",
+			"startSide":   "The start side of a multi-line comment (optional)",
+			"subjectType": "The subject type of the comment",
+		},
+		"add_pull_request_review_comment_reaction": {
+			"content": "The emoji reaction type",
+		},
+		"create_pull_request_review": {
+			"event": "The review action to perform. If omitted, creates a pending review.",
+		},
+		"submit_pending_pull_request_review": {
+			"event": "The review action to perform",
+		},
+		"update_pull_request_state": {
+			"state": "The new state for the pull request",
+		},
+		"find_duplicate": {
+			"page":    "Page number for pagination (min 1)",
+			"perPage": "Results per page for pagination (min 1, max 100)",
+		},
+	}
+	tools := append(granularPullRequestTools(), FindDuplicate(translations.NullTranslationHelper))
+	for _, tool := range tools {
+		for field, description := range descriptions[tool.Tool.Name] {
+			schema, ok := tool.Tool.InputSchema.(*jsonschema.Schema)
+			require.True(t, ok, tool.Tool.Name)
+			property := schema.Properties[field]
+			require.NotNil(t, property, tool.Tool.Name+"/"+field)
+			assert.Equal(t, description, property.Description, tool.Tool.Name+"/"+field)
+		}
+	}
+
+	findDuplicate, ok := FindDuplicate(translations.NullTranslationHelper).Tool.InputSchema.(*jsonschema.Schema)
+	require.True(t, ok)
+	assert.Equal(t, 1.0, *findDuplicate.Properties["page"].Minimum)
+	assert.Equal(t, 1.0, *findDuplicate.Properties["perPage"].Minimum)
+	assert.Equal(t, 100.0, *findDuplicate.Properties["perPage"].Maximum)
+}
+
 func TestGranularPullRequestReactionSchema(t *testing.T) {
 	schema, err := minimalPullRequestCommentReactionSchema().Resolve(nil)
 	require.NoError(t, err)