fix(issues): preserve zero pagination for duplicate search

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

Author: SamMorrowDrums

docs/feature-flags.md

@@ -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) (number, optional)
-  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
+  - `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)
   - `repo`: The name of the repository (string, required)
 
 ### `thread_resolution_reason`

pkg/github/__toolsnaps__/find_duplicate_ff_duplicate_detection.snap

@@ -20,14 +20,14 @@
         "type": "string"
       },
       "page": {
-        "description": "Page number for pagination (min 1)",
-        "minimum": 0,
+        "description": "Page number for pagination (min 1). An explicit 0 is forwarded to the API as-is rather than being replaced with 1.",
+        "minimum": 1,
         "type": "number"
       },
       "perPage": {
-        "description": "Results per page for pagination (min 1, max 100)",
+        "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.",
         "maximum": 100,
-        "minimum": 0,
+        "minimum": 1,
         "type": "number"
       },
       "repo": {
@@ -42,5 +42,66 @@
     ],
     "type": "object"
   },
-  "name": "find_duplicate"
+  "name": "find_duplicate",
+  "outputSchema": {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "confidence": {
+          "description": "The API-provided confidence category.",
+          "type": "string"
+        },
+        "issue": {
+          "additionalProperties": false,
+          "properties": {
+            "html_url": {
+              "description": "The web URL of the candidate issue.",
+              "type": "string"
+            },
+            "number": {
+              "description": "The candidate issue number.",
+              "type": "integer"
+            },
+            "state": {
+              "description": "The candidate issue state.",
+              "type": "string"
+            },
+            "title": {
+              "description": "The sanitized candidate issue title.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "number",
+            "title",
+            "state",
+            "html_url"
+          ],
+          "type": "object"
+        },
+        "likely_duplicate": {
+          "description": "Whether the API considers this candidate a likely duplicate.",
+          "type": "boolean"
+        },
+        "score": {
+          "description": "Similarity score on the API-defined scale; null when the API does not return a score.",
+          "type": [
+            "null",
+            "number"
+          ]
+        }
+      },
+      "required": [
+        "issue",
+        "score",
+        "confidence",
+        "likely_duplicate"
+      ],
+      "type": "object"
+    },
+    "type": [
+      "null",
+      "array"
+    ]
+  }
 }

pkg/github/__toolsnaps__/find_duplicate_typed.snap

@@ -33,15 +33,6 @@ type rankedSimilarIssue struct {
 	LikelyDuplicate bool     `json:"likely_duplicate"`
 }
 
-// DuplicateCandidate is the trimmed output for a ranked duplicate candidate,
-// carrying only what an agent needs to explain and act on it.
-type DuplicateCandidate struct {
-	Issue           MinimalIssueRef `json:"issue"`
-	Score           *float64        `json:"score"`
-	Confidence      string          `json:"confidence"`
-	LikelyDuplicate bool            `json:"likely_duplicate"`
-}
-
 // FindDuplicate creates a read-only tool that returns ranked duplicate
 // candidates for an existing issue. It is a separate, feature-flagged tool so
 // duplicate detection is only advertised when explicitly opted in, keeping the
@@ -71,14 +62,15 @@ func FindDuplicate(t translations.TranslationHelperFunc) inventory.ServerTool {
 		Required: []string{"owner", "repo", "issue_number"},
 	}
 	WithPagination(schema)
-	// This endpoint owns its defaults. Unlike issue_dependency_read, explicit
-	// zero pagination values must be forwarded, not replaced by SDK defaults.
-	for _, field := range []string{"page", "perPage"} {
-		schema.Properties[field].Default = nil
-		schema.Properties[field].Minimum = new(0.0)
-	}
+	// 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 := NewTool[FindDuplicateInput, []DuplicateCandidate](
+	st := NewToolWithSchemaOptions[FindDuplicateInput, []DuplicateCandidate](
 		ToolsetMetadataIssues,
 		mcp.Tool{
 			Name:        "find_duplicate",
@@ -87,9 +79,11 @@ func FindDuplicate(t translations.TranslationHelperFunc) inventory.ServerTool {
 				Title:        t("TOOL_FIND_DUPLICATE_USER_TITLE", "Find duplicate issues"),
 				ReadOnlyHint: true,
 			},
-			InputSchema: schema,
+			InputSchema:  schema,
+			OutputSchema: findDuplicateOutputSchema(),
 		},
 		scopes.PublicRead(scopes.Repo),
+		inventory.TypedSchemaOptions{ValidationInputSchema: issuePaginationValidationSchema(schema)},
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, input FindDuplicateInput) (*mcp.CallToolResult, []DuplicateCandidate, error) {
 			owner, repo, issueNumber := input.Owner, input.Repo, input.IssueNumber
 			if err := validateIssueCoordinate(owner, repo, issueNumber); err != nil {
@@ -132,30 +126,41 @@ func FindDuplicate(t translations.TranslationHelperFunc) inventory.ServerTool {
 			defer func() { _ = resp.Body.Close() }()
 
 			candidates := make([]DuplicateCandidate, 0, len(results))
+			legacyCandidates := make([]LegacyDuplicateCandidate, 0, len(results))
 			for _, res := range results {
 				// A bare issue (no ranking metadata) means ranked duplicate
 				// detection is not enabled for this caller; fail clearly rather
 				// than returning incomplete candidates.
 				if res.Confidence == "" || res.Issue == nil {
 					return utils.NewToolResultError("ranked duplicate detection is unavailable: the semantic-similarity endpoint returned issues without ranking metadata (the server-side duplicate-ranking feature is not enabled for this caller or repository)"), nil, nil
 				}
+				ref := newMinimalIssueRef(
+					res.Issue.Number,
+					res.Issue.Title,
+					res.Issue.State,
+					res.Issue.HTMLURL,
+					"",
+				)
 				candidates = append(candidates, DuplicateCandidate{
 					// Candidates are always scoped to the requested repository, so the
 					// ref's repository field is left empty as it was before.
-					Issue: newMinimalIssueRef(
-						res.Issue.Number,
-						res.Issue.Title,
-						res.Issue.State,
-						res.Issue.HTMLURL,
-						"",
-					),
+					Issue: MinimalDuplicateIssue{
+						Number: ref.Number, Title: ref.Title,
+						State: DuplicateIssueState(ref.State), HTMLURL: ref.URL,
+					},
+					Score:           res.Score,
+					Confidence:      DuplicateConfidence(res.Confidence),
+					LikelyDuplicate: res.LikelyDuplicate,
+				})
+				legacyCandidates = append(legacyCandidates, LegacyDuplicateCandidate{
+					Issue:           ref,
 					Score:           res.Score,
-					Confidence:      res.Confidence,
+					Confidence:      DuplicateConfidence(res.Confidence),
 					LikelyDuplicate: res.LikelyDuplicate,
 				})
 			}
 
-			r, err := json.Marshal(candidates)
+			r, err := json.Marshal(legacyCandidates)
 			if err != nil {
 				return utils.NewToolResultErrorFromErr("failed to marshal duplicate candidates", err), nil, nil
 			}