Add confidence parameter to issue mutation MCP tools

Add an optional confidence integer parameter (0–100) to update_issue_type,
update_issue_labels, and set_issue_fields MCP tools. The confidence score
is passed through to the REST/GraphQL API on mutation calls.

- Rename structs to WithIntent (labelWithIntent, issueTypeWithIntent)
- Add confidence schema property (integer, min 0, max 100) with prompt
  guidance describing what different confidence levels represent
- Update tool descriptions to encourage including confidence scores
- Pass confidence in the API request body alongside rationale/suggest

Closes github/plan-track-agentic-toolkit#219

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

Author: alondahari

docs/feature-flags.md

@@ -198,6 +198,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **update_issue_type** - Update Issue Type
   - **Required OAuth Scopes**: `repo`
+  - `confidence`: How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative. (number, optional)
   - `is_suggestion`: If true, this issue type change is sent to the API as a suggestion (suggest:true) rather than an applied value. Whether the type is applied or recorded as a proposal is determined by the API. (boolean, optional)
   - `issue_number`: The issue number to update (number, required)
   - `issue_type`: The issue type to set (string, required)
@@ -240,7 +241,7 @@ runtime behavior (such 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)
-  - `reviewers`: GitHub usernames to request reviews from (string[], required)
+  - `reviewers`: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], required)
 
 - **resolve_review_thread** - Resolve Review Thread
   - **Required OAuth Scopes**: `repo`

pkg/github/__toolsnaps__/request_pull_request_reviewers.snap

@@ -37,4 +37,4 @@
     "type": "object"
   },
   "name": "request_pull_request_reviewers"
-}
+}

pkg/github/__toolsnaps__/set_issue_fields.snap

@@ -4,13 +4,19 @@
     "openWorldHint": true,
     "title": "Set Issue Fields"
   },
-  "description": "Set issue field values for an issue. Fields are organization-level custom fields (text, number, date, or single select). Use this to create or update field values on an issue.",
+  "description": "Set issue field values for an issue. Fields are organization-level custom fields (text, number, date, or single select). Use this to create or update field values on an issue. When setting values, include a confidence score (0–100) reflecting how certain you are about the choice.",
   "inputSchema": {
     "properties": {
       "fields": {
         "description": "Array of issue field values to set. Each element must have a 'field_id' (string, the GraphQL node ID of the field) and exactly one value field: 'text_value' for text fields, 'number_value' for number fields, 'date_value' (ISO 8601 date string) for date fields, or 'single_select_option_id' (the GraphQL node ID of the option) for single select fields. Set 'delete' to true to remove a field value.",
         "items": {
           "properties": {
+            "confidence": {
+              "description": "How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative.",
+              "maximum": 100,
+              "minimum": 0,
+              "type": "integer"
+            },
             "date_value": {
               "description": "The value to set for a date field (ISO 8601 date string)",
               "type": "string"

pkg/github/__toolsnaps__/update_issue_labels.snap

@@ -4,7 +4,7 @@
     "openWorldHint": true,
     "title": "Update Issue Labels"
   },
-  "description": "Update the labels of an existing issue. This replaces the current labels with the provided list.",
+  "description": "Update the labels of an existing issue. This replaces the current labels with the provided list. When setting values, include a confidence score (0–100) reflecting how certain you are about the choice.",
   "inputSchema": {
     "properties": {
       "issue_number": {
@@ -22,6 +22,12 @@
             },
             {
               "properties": {
+                "confidence": {
+                  "description": "How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative.",
+                  "maximum": 100,
+                  "minimum": 0,
+                  "type": "integer"
+                },
                 "is_suggestion": {
                   "description": "If true, this label is sent to the API as a suggestion (suggest:true) rather than an applied label. Whether the label is applied or recorded as a proposal is determined by the API.",
                   "type": "boolean"

pkg/github/__toolsnaps__/update_issue_type.snap

@@ -4,9 +4,15 @@
     "openWorldHint": true,
     "title": "Update Issue Type"
   },
-  "description": "Update the type of an existing issue (e.g. 'bug', 'feature').",
+  "description": "Update the type of an existing issue (e.g. 'bug', 'feature'). When setting values, include a confidence score (0–100) reflecting how certain you are about the choice.",
   "inputSchema": {
     "properties": {
+      "confidence": {
+        "description": "How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative.",
+        "maximum": 100,
+        "minimum": 0,
+        "type": "integer"
+      },
       "is_suggestion": {
         "description": "If true, this issue type change is sent to the API as a suggestion (suggest:true) rather than an applied value. Whether the type is applied or recorded as a proposal is determined by the API.",
         "type": "boolean"

pkg/github/__toolsnaps__/update_pull_request.snap

@@ -61,4 +61,4 @@
     "type": "object"
   },
   "name": "update_pull_request"
-}
+}

pkg/github/issues_granular.go

@@ -258,17 +258,18 @@ func GranularUpdateIssueAssignees(t translations.TranslationHelperFunc) inventor
 	)
 }
 
-// labelWithRationale represents the object form of a label entry, allowing a
-// rationale and/or suggest flag to be sent alongside the label name.
-type labelWithRationale struct {
-	Name      string `json:"name"`
-	Rationale string `json:"rationale,omitempty"`
-	Suggest   bool   `json:"suggest,omitempty"`
+// labelWithIntent represents the object form of a label entry, allowing a
+// rationale, confidence score, and/or suggest flag to be sent alongside the label name.
+type labelWithIntent struct {
+	Name       string `json:"name"`
+	Rationale  string `json:"rationale,omitempty"`
+	Confidence *int   `json:"confidence,omitempty"`
+	Suggest    bool   `json:"suggest,omitempty"`
 }
 
 // labelsUpdateRequest is a custom request body for updating an issue's labels
 // where individual labels may optionally include a rationale. Each element of
-// Labels is either a string (label name) or a labelWithRationale object.
+// Labels is either a string (label name) or a labelWithIntent object.
 type labelsUpdateRequest struct {
 	Labels []any `json:"labels"`
 }
@@ -279,7 +280,7 @@ func GranularUpdateIssueLabels(t translations.TranslationHelperFunc) inventory.S
 		ToolsetMetadataIssues,
 		mcp.Tool{
 			Name:        "update_issue_labels",
-			Description: t("TOOL_UPDATE_ISSUE_LABELS_DESCRIPTION", "Update the labels of an existing issue. This replaces the current labels with the provided list."),
+			Description: t("TOOL_UPDATE_ISSUE_LABELS_DESCRIPTION", "Update the labels of an existing issue. This replaces the current labels with the provided list. When setting values, include a confidence score (0–100) reflecting how certain you are about the choice."),
 			Annotations: &mcp.ToolAnnotations{
 				Title:           t("TOOL_UPDATE_ISSUE_LABELS_USER_TITLE", "Update Issue Labels"),
 				ReadOnlyHint:    false,
@@ -321,6 +322,12 @@ func GranularUpdateIssueLabels(t translations.TranslationHelperFunc) inventory.S
 												"State the concrete signal (e.g. 'Reports a crash when saving' → bug).",
 											MaxLength: jsonschema.Ptr(280),
 										},
+										"confidence": {
+											Type:        "integer",
+											Description: "How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative.",
+											Minimum:     jsonschema.Ptr(0.0),
+											Maximum:     jsonschema.Ptr(100.0),
+										},
 										"is_suggestion": {
 											Type: "boolean",
 											Description: "If true, this label is sent to the API as a suggestion (suggest:true) rather than an applied label. " +
@@ -387,18 +394,29 @@ func GranularUpdateIssueLabels(t translations.TranslationHelperFunc) inventory.S
 					if len([]rune(rationale)) > 280 {
 						return utils.NewToolResultError("label rationale must be 280 characters or less"), nil, nil
 					}
+					var confidence *int
+					if _, exists := v["confidence"]; exists {
+						c, err := OptionalIntParam(v, "confidence")
+						if err != nil {
+							return utils.NewToolResultError(err.Error()), nil, nil
+						}
+						if c < 0 || c > 100 {
+							return utils.NewToolResultError("confidence must be between 0 and 100"), nil, nil
+						}
+						confidence = &c
+					}
 					isSuggestion, err := OptionalParam[bool](v, "is_suggestion")
 					if err != nil {
 						return utils.NewToolResultError(err.Error()), nil, nil
 					}
-					if rationale == "" && !isSuggestion {
+					if rationale == "" && !isSuggestion && confidence == nil {
 						payload = append(payload, name)
 					} else {
 						useObjectForm = true
-						payload = append(payload, labelWithRationale{Name: name, Rationale: rationale, Suggest: isSuggestion})
+						payload = append(payload, labelWithIntent{Name: name, Rationale: rationale, Confidence: confidence, Suggest: isSuggestion})
 					}
 				default:
-					return utils.NewToolResultError("each label must be a string or an object with 'name' and optional 'rationale' and/or 'is_suggestion'"), nil, nil
+					return utils.NewToolResultError("each label must be a string or an object with 'name' and optional 'rationale', 'confidence', and/or 'is_suggestion'"), nil, nil
 				}
 			}
 
@@ -470,18 +488,19 @@ func GranularUpdateIssueMilestone(t translations.TranslationHelperFunc) inventor
 	)
 }
 
-// issueTypeWithRationale represents the object form of the issue type field,
-// allowing a rationale and/or suggest flag to be sent alongside the type name.
-type issueTypeWithRationale struct {
-	Value     string `json:"value"`
-	Rationale string `json:"rationale,omitempty"`
-	Suggest   bool   `json:"suggest,omitempty"`
+// issueTypeWithIntent represents the object form of the issue type field,
+// allowing a rationale, confidence score, and/or suggest flag to be sent alongside the type name.
+type issueTypeWithIntent struct {
+	Value      string `json:"value"`
+	Rationale  string `json:"rationale,omitempty"`
+	Confidence *int   `json:"confidence,omitempty"`
+	Suggest    bool   `json:"suggest,omitempty"`
 }
 
 // issueTypeUpdateRequest is a custom request body for updating an issue type
-// with an optional rationale, using the object form that the REST API accepts.
+// with optional intent metadata, using the object form that the REST API accepts.
 type issueTypeUpdateRequest struct {
-	Type issueTypeWithRationale `json:"type"`
+	Type issueTypeWithIntent `json:"type"`
 }
 
 // GranularUpdateIssueType creates a tool to update an issue's type.
@@ -490,7 +509,7 @@ func GranularUpdateIssueType(t translations.TranslationHelperFunc) inventory.Ser
 		ToolsetMetadataIssues,
 		mcp.Tool{
 			Name:        "update_issue_type",
-			Description: t("TOOL_UPDATE_ISSUE_TYPE_DESCRIPTION", "Update the type of an existing issue (e.g. 'bug', 'feature')."),
+			Description: t("TOOL_UPDATE_ISSUE_TYPE_DESCRIPTION", "Update the type of an existing issue (e.g. 'bug', 'feature'). When setting values, include a confidence score (0–100) reflecting how certain you are about the choice."),
 			Annotations: &mcp.ToolAnnotations{
 				Title:           t("TOOL_UPDATE_ISSUE_TYPE_USER_TITLE", "Update Issue Type"),
 				ReadOnlyHint:    false,
@@ -523,6 +542,12 @@ func GranularUpdateIssueType(t translations.TranslationHelperFunc) inventory.Ser
 							"State the concrete signal (e.g. 'Reports a crash when saving' → bug, 'Asks for dark mode support' → feature).",
 						MaxLength: jsonschema.Ptr(280),
 					},
+					"confidence": {
+						Type:        "integer",
+						Description: "How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative.",
+						Minimum:     jsonschema.Ptr(0.0),
+						Maximum:     jsonschema.Ptr(100.0),
+					},
 					"is_suggestion": {
 						Type: "boolean",
 						Description: "If true, this issue type change is sent to the API as a suggestion (suggest:true) rather than an applied value. " +
@@ -558,6 +583,17 @@ func GranularUpdateIssueType(t translations.TranslationHelperFunc) inventory.Ser
 			if len([]rune(rationale)) > 280 {
 				return utils.NewToolResultError("parameter rationale must be 280 characters or less"), nil, nil
 			}
+			var confidence *int
+			if _, exists := args["confidence"]; exists {
+				c, err := OptionalIntParam(args, "confidence")
+				if err != nil {
+					return utils.NewToolResultError(err.Error()), nil, nil
+				}
+				if c < 0 || c > 100 {
+					return utils.NewToolResultError("confidence must be between 0 and 100"), nil, nil
+				}
+				confidence = &c
+			}
 			isSuggestion, err := OptionalParam[bool](args, "is_suggestion")
 			if err != nil {
 				return utils.NewToolResultError(err.Error()), nil, nil
@@ -569,12 +605,13 @@ func GranularUpdateIssueType(t translations.TranslationHelperFunc) inventory.Ser
 			}
 
 			var body any
-			if rationale != "" || isSuggestion {
+			if rationale != "" || isSuggestion || confidence != nil {
 				body = &issueTypeUpdateRequest{
-					Type: issueTypeWithRationale{
-						Value:     issueType,
-						Rationale: rationale,
-						Suggest:   isSuggestion,
+					Type: issueTypeWithIntent{
+						Value:      issueType,
+						Rationale:  rationale,
+						Confidence: confidence,
+						Suggest:    isSuggestion,
 					},
 				}
 			} else {
@@ -887,6 +924,7 @@ type IssueFieldCreateOrUpdateInput struct {
 	SingleSelectOptionID *githubv4.ID      `json:"singleSelectOptionId,omitempty"`
 	Delete               *githubv4.Boolean `json:"delete,omitempty"`
 	Rationale            *githubv4.String  `json:"rationale,omitempty"`
+	Confidence           *int              `json:"confidence,omitempty"`
 	Suggest              *githubv4.Boolean `json:"suggest,omitempty"`
 }
 
@@ -896,7 +934,7 @@ func GranularSetIssueFields(t translations.TranslationHelperFunc) inventory.Serv
 		ToolsetMetadataIssues,
 		mcp.Tool{
 			Name:        "set_issue_fields",
-			Description: t("TOOL_SET_ISSUE_FIELDS_DESCRIPTION", "Set issue field values for an issue. Fields are organization-level custom fields (text, number, date, or single select). Use this to create or update field values on an issue."),
+			Description: t("TOOL_SET_ISSUE_FIELDS_DESCRIPTION", "Set issue field values for an issue. Fields are organization-level custom fields (text, number, date, or single select). Use this to create or update field values on an issue. When setting values, include a confidence score (0–100) reflecting how certain you are about the choice."),
 			Annotations: &mcp.ToolAnnotations{
 				Title:           t("TOOL_SET_ISSUE_FIELDS_USER_TITLE", "Set Issue Fields"),
 				ReadOnlyHint:    false,
@@ -956,6 +994,12 @@ func GranularSetIssueFields(t translations.TranslationHelperFunc) inventory.Serv
 										"State the concrete signal (e.g. 'Reports a crash when saving' → high priority).",
 									MaxLength: jsonschema.Ptr(280),
 								},
+								"confidence": {
+									Type:        "integer",
+									Description: "How confident you are in this choice (0–100). 90–100: very high — clear signal or explicit user request. 70–89: high — strong signals, likely correct. 50–69: moderate — reasonable inference but ambiguous. 30–49: low — best guess, user review recommended. 0–29: very low — speculative.",
+									Minimum:     jsonschema.Ptr(0.0),
+									Maximum:     jsonschema.Ptr(100.0),
+								},
 								"is_suggestion": {
 									Type: "boolean",
 									Description: "If true, this field value is sent to the API as a suggestion (suggest:true) rather than an applied value. " +
@@ -1073,6 +1117,21 @@ func GranularSetIssueFields(t translations.TranslationHelperFunc) inventory.Serv
 					}
 				}
 
+				var confidence *int
+				if _, exists := fieldMap["confidence"]; exists {
+					c, err := OptionalIntParam(fieldMap, "confidence")
+					if err != nil {
+						return utils.NewToolResultError(err.Error()), nil, nil
+					}
+					if c < 0 || c > 100 {
+						return utils.NewToolResultError("confidence must be between 0 and 100"), nil, nil
+					}
+					confidence = &c
+				}
+				if confidence != nil {
+					input.Confidence = confidence
+				}
+
 				isSuggestion, err := OptionalParam[bool](fieldMap, "is_suggestion")
 				if err != nil {
 					return utils.NewToolResultError(err.Error()), nil, nil