Add optional rationale parameter to update_issue_type tool

Add an optional `rationale` string parameter (max 280 chars) to the
`update_issue_type` MCP tool. When provided, the type is sent as an
object `{"name": "...", "rationale": "..."}` to the REST API,
enabling agents to explain their classification decisions. When omitted,
existing behavior is preserved (type sent as a plain string).

This supports the agent rationale experiment for type mutations. The
parameter is always visible in the schema — the API gracefully ignores
the rationale when the server-side feature flag is disabled.

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

Author: alondahari

pkg/github/__toolsnaps__/update_issue_type.snap

@@ -20,6 +20,11 @@
         "description": "Repository owner (username or organization)",
         "type": "string"
       },
+      "rationale": {
+        "description": "One concise sentence explaining what specifically about the issue led you to choose this type. State the concrete signal (e.g. 'Reports a crash when saving' → bug, 'Asks for dark mode support' → feature).",
+        "maxLength": 280,
+        "type": "string"
+      },
       "repo": {
         "description": "Repository name",
         "type": "string"

pkg/github/granular_tools_test.go

@@ -304,24 +304,57 @@ func TestGranularUpdateIssueMilestone(t *testing.T) {
 }
 
 func TestGranularUpdateIssueType(t *testing.T) {
-	client := gogithub.NewClient(MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
-		PatchReposIssuesByOwnerByRepoByIssueNumber: expectRequestBody(t, map[string]any{
-			"type": "bug",
-		}).andThen(mockResponse(t, http.StatusOK, &gogithub.Issue{Number: gogithub.Ptr(1)})),
-	}))
-	deps := BaseDeps{Client: client}
-	serverTool := GranularUpdateIssueType(translations.NullTranslationHelper)
-	handler := serverTool.Handler(deps)
+	tests := []struct {
+		name        string
+		requestArgs map[string]any
+		expectedReq map[string]any
+	}{
+		{
+			name: "type only",
+			requestArgs: map[string]any{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(1),
+				"issue_type":   "bug",
+			},
+			expectedReq: map[string]any{
+				"type": "bug",
+			},
+		},
+		{
+			name: "type with rationale",
+			requestArgs: map[string]any{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(1),
+				"issue_type":   "feature",
+				"rationale":    "This issue requests a new capability",
+			},
+			expectedReq: map[string]any{
+				"type": map[string]any{
+					"value":     "feature",
+					"rationale": "This issue requests a new capability",
+				},
+			},
+		},
+	}
 
-	request := createMCPRequest(map[string]any{
-		"owner":        "owner",
-		"repo":         "repo",
-		"issue_number": float64(1),
-		"issue_type":   "bug",
-	})
-	result, err := handler(ContextWithDeps(context.Background(), deps), &request)
-	require.NoError(t, err)
-	assert.False(t, result.IsError)
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			client := gogithub.NewClient(MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
+				PatchReposIssuesByOwnerByRepoByIssueNumber: expectRequestBody(t, tc.expectedReq).
+					andThen(mockResponse(t, http.StatusOK, &gogithub.Issue{Number: gogithub.Ptr(1)})),
+			}))
+			deps := BaseDeps{Client: client}
+			serverTool := GranularUpdateIssueType(translations.NullTranslationHelper)
+			handler := serverTool.Handler(deps)
+
+			request := createMCPRequest(tc.requestArgs)
+			result, err := handler(ContextWithDeps(context.Background(), deps), &request)
+			require.NoError(t, err)
+			assert.False(t, result.IsError)
+		})
+	}
 }
 
 func TestGranularUpdateIssueState(t *testing.T) {

pkg/github/issues_granular.go

@@ -18,13 +18,24 @@ import (
 	"github.com/shurcooL/githubv4"
 )
 
+// issueEditBody is implemented by any type that can serve as the body
+// of a PATCH /repos/{owner}/{repo}/issues/{issue_number} request.
+type issueEditBody interface {
+	issueEditBody()
+}
+
+// standardIssueEdit wraps a *github.IssueRequest to satisfy issueEditBody.
+type standardIssueEdit struct{ *github.IssueRequest }
+
+func (standardIssueEdit) issueEditBody() {}
+
 // issueUpdateTool is a helper to create single-field issue update tools.
 func issueUpdateTool(
 	t translations.TranslationHelperFunc,
 	name, description, title string,
 	extraProps map[string]*jsonschema.Schema,
 	extraRequired []string,
-	buildRequest func(args map[string]any) (*github.IssueRequest, error),
+	buildRequest func(args map[string]any) (issueEditBody, error),
 ) inventory.ServerTool {
 	props := map[string]*jsonschema.Schema{
 		"owner": {
@@ -77,7 +88,7 @@ func issueUpdateTool(
 				return utils.NewToolResultError(err.Error()), nil, nil
 			}
 
-			issueReq, err := buildRequest(args)
+			body, err := buildRequest(args)
 			if err != nil {
 				return utils.NewToolResultError(err.Error()), nil, nil
 			}
@@ -87,7 +98,14 @@ func issueUpdateTool(
 				return utils.NewToolResultErrorFromErr("failed to get GitHub client", err), nil, nil
 			}
 
-			issue, resp, err := client.Issues.Edit(ctx, owner, repo, issueNumber, issueReq)
+			apiURL := fmt.Sprintf("repos/%s/%s/issues/%d", owner, repo, issueNumber)
+			req, err := client.NewRequest("PATCH", apiURL, body)
+			if err != nil {
+				return utils.NewToolResultErrorFromErr("failed to create request", err), nil, nil
+			}
+
+			issue := &github.Issue{}
+			resp, err := client.Do(ctx, req, issue)
 			if err != nil {
 				return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to update issue", resp, err), nil, nil
 			}
@@ -201,12 +219,12 @@ func GranularUpdateIssueTitle(t translations.TranslationHelperFunc) inventory.Se
 			"title": {Type: "string", Description: "The new title for the issue"},
 		},
 		[]string{"title"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			title, err := RequiredParam[string](args, "title")
 			if err != nil {
 				return nil, err
 			}
-			return &github.IssueRequest{Title: &title}, nil
+			return standardIssueEdit{&github.IssueRequest{Title: &title}}, nil
 		},
 	)
 }
@@ -221,12 +239,12 @@ func GranularUpdateIssueBody(t translations.TranslationHelperFunc) inventory.Ser
 			"body": {Type: "string", Description: "The new body content for the issue"},
 		},
 		[]string{"body"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			body, err := RequiredParam[string](args, "body")
 			if err != nil {
 				return nil, err
 			}
-			return &github.IssueRequest{Body: &body}, nil
+			return standardIssueEdit{&github.IssueRequest{Body: &body}}, nil
 		},
 	)
 }
@@ -245,15 +263,15 @@ func GranularUpdateIssueAssignees(t translations.TranslationHelperFunc) inventor
 			},
 		},
 		[]string{"assignees"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			if _, ok := args["assignees"]; !ok {
 				return nil, fmt.Errorf("missing required parameter: assignees")
 			}
 			assignees, err := OptionalStringArrayParam(args, "assignees")
 			if err != nil {
 				return nil, err
 			}
-			return &github.IssueRequest{Assignees: &assignees}, nil
+			return standardIssueEdit{&github.IssueRequest{Assignees: &assignees}}, nil
 		},
 	)
 }
@@ -272,15 +290,15 @@ func GranularUpdateIssueLabels(t translations.TranslationHelperFunc) inventory.S
 			},
 		},
 		[]string{"labels"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			if _, ok := args["labels"]; !ok {
 				return nil, fmt.Errorf("missing required parameter: labels")
 			}
 			labels, err := OptionalStringArrayParam(args, "labels")
 			if err != nil {
 				return nil, err
 			}
-			return &github.IssueRequest{Labels: &labels}, nil
+			return standardIssueEdit{&github.IssueRequest{Labels: &labels}}, nil
 		},
 	)
 }
@@ -299,16 +317,31 @@ func GranularUpdateIssueMilestone(t translations.TranslationHelperFunc) inventor
 			},
 		},
 		[]string{"milestone"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			milestone, err := RequiredInt(args, "milestone")
 			if err != nil {
 				return nil, err
 			}
-			return &github.IssueRequest{Milestone: &milestone}, nil
+			return standardIssueEdit{&github.IssueRequest{Milestone: &milestone}}, nil
 		},
 	)
 }
 
+// issueTypeWithRationale represents the object form of the issue type field,
+// allowing a rationale to be sent alongside the type value.
+type issueTypeWithRationale struct {
+	Value     string `json:"value"`
+	Rationale string `json:"rationale"`
+}
+
+// issueTypeUpdateRequest is a custom request body for updating an issue type
+// with an optional rationale, using the object form that the REST API accepts.
+type issueTypeUpdateRequest struct {
+	Type issueTypeWithRationale `json:"type"`
+}
+
+func (*issueTypeUpdateRequest) issueEditBody() {}
+
 // GranularUpdateIssueType creates a tool to update an issue's type.
 func GranularUpdateIssueType(t translations.TranslationHelperFunc) inventory.ServerTool {
 	return issueUpdateTool(t,
@@ -320,14 +353,29 @@ func GranularUpdateIssueType(t translations.TranslationHelperFunc) inventory.Ser
 				Type:        "string",
 				Description: "The issue type to set",
 			},
+			"rationale": {
+				Type: "string",
+				Description: "One concise sentence explaining what specifically about the issue led you to choose this type. " +
+					"State the concrete signal (e.g. 'Reports a crash when saving' → bug, 'Asks for dark mode support' → feature).",
+				MaxLength: jsonschema.Ptr(280),
+			},
 		},
 		[]string{"issue_type"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			issueType, err := RequiredParam[string](args, "issue_type")
 			if err != nil {
 				return nil, err
 			}
-			return &github.IssueRequest{Type: &issueType}, nil
+			rationale, _ := OptionalParam[string](args, "rationale")
+			if rationale != "" {
+				return &issueTypeUpdateRequest{
+					Type: issueTypeWithRationale{
+						Value:     issueType,
+						Rationale: rationale,
+					},
+				}, nil
+			}
+			return standardIssueEdit{&github.IssueRequest{Type: &issueType}}, nil
 		},
 	)
 }
@@ -351,7 +399,7 @@ func GranularUpdateIssueState(t translations.TranslationHelperFunc) inventory.Se
 			},
 		},
 		[]string{"state"},
-		func(args map[string]any) (*github.IssueRequest, error) {
+		func(args map[string]any) (issueEditBody, error) {
 			state, err := RequiredParam[string](args, "state")
 			if err != nil {
 				return nil, err
@@ -362,7 +410,7 @@ func GranularUpdateIssueState(t translations.TranslationHelperFunc) inventory.Se
 			if stateReason != "" {
 				req.StateReason = &stateReason
 			}
-			return req, nil
+			return standardIssueEdit{req}, nil
 		},
 	)
 }