feat(search-issues): Support recommended sort

Add `recommended` (Sentry's prioritized ranking) to the search_issues tool
sort enum, the embedded search-issues agent, and the listIssues API client.
The issues API already accepts sort=recommended; the tools just didn't offer
it, so an agent could not ask for Sentry's default prioritized ranking.

Regenerated toolDefinitions.json is hand-synced to the schema change; CI
generate-definitions will confirm.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: roggenkemper

packages/mcp-core/src/api-client/client.ts

@@ -3008,7 +3008,7 @@ export class SentryApiService {
    * @param params.organizationSlug Organization identifier
    * @param params.projectSlug Project identifier (optional, scopes to specific project)
    * @param params.query Sentry search query (e.g., "is:unresolved browser:chrome")
-   * @param params.sortBy Sort order ("user", "freq", "date", "new")
+   * @param params.sortBy Sort order ("user", "freq", "date", "new", "recommended")
    * @param opts Request options
    * @returns Array of issues with metadata and statistics
    *
@@ -3042,7 +3042,7 @@ export class SentryApiService {
       organizationSlug: string;
       projectId?: string;
       query?: string | null;
-      sortBy?: "user" | "freq" | "date" | "new";
+      sortBy?: "user" | "freq" | "date" | "new" | "recommended";
       limit?: number;
       /**
        * Controls the search time window - which issues are included in results.

packages/mcp-core/src/internal/agents/openai-provider.integration.test.ts

@@ -95,7 +95,7 @@ describe("OpenAI Provider Integration", () => {
       // sort can be null or one of the valid values
       expect(
         result.sort === null ||
-          ["date", "freq", "new", "user"].includes(result.sort),
+          ["date", "freq", "new", "user", "recommended"].includes(result.sort),
       ).toBe(true);
     },
   );
@@ -121,7 +121,7 @@ describe("OpenAI Provider Integration", () => {
       // sort being null is valid and tests the nullable field handling
       expect(
         result.sort === null ||
-          ["date", "freq", "new", "user"].includes(result.sort),
+          ["date", "freq", "new", "user", "recommended"].includes(result.sort),
       ).toBe(true);
     },
   );

packages/mcp-core/src/toolDefinitions.json

@@ -2830,9 +2830,9 @@
         },
         "sort": {
           "default": "date",
-          "description": "Sort order: date (last seen), freq (frequency), new (first seen), user (user count)",
+          "description": "Sort order: date (last seen), freq (frequency), new (first seen), user (user count), recommended (Sentry's prioritized ranking)",
           "type": "string",
-          "enum": ["date", "freq", "new", "user"]
+          "enum": ["date", "freq", "new", "user", "recommended"]
         },
         "projectSlugOrId": {
           "default": null,

packages/mcp-core/src/tools/catalog/search-issues.test.ts

@@ -39,7 +39,7 @@ describe("search_issues", () => {
   // Helper to create AI agent response
   const mockAIResponse = (
     query = "",
-    sort: "date" | "freq" | "new" | "user" | null = "date",
+    sort: "date" | "freq" | "new" | "user" | "recommended" | null = "date",
     errorMessage?: string,
   ) => {
     const output = errorMessage
@@ -589,12 +589,9 @@ describe("search_issues", () => {
   });
 
   it("should handle all sort options", async () => {
-    const sortOptions: Array<"date" | "freq" | "new" | "user"> = [
-      "date",
-      "freq",
-      "new",
-      "user",
-    ];
+    const sortOptions: Array<
+      "date" | "freq" | "new" | "user" | "recommended"
+    > = ["date", "freq", "new", "user", "recommended"];
 
     for (const sortOption of sortOptions) {
       mockGenerateText.mockResolvedValue(mockAIResponse("", sortOption));

packages/mcp-core/src/tools/catalog/search-issues.ts

@@ -17,7 +17,7 @@ const ProjectSlugOrIdSchema = z.string().trim().superRefine(validateSlugOrId);
 
 function buildIssueSearchRepairPrompt(params: {
   query: string;
-  sort: "date" | "freq" | "new" | "user";
+  sort: "date" | "freq" | "new" | "user" | "recommended";
 }): string {
   return [
     "Fix this Sentry issue search request.",
@@ -80,10 +80,10 @@ export default defineTool({
       .default("is:unresolved")
       .describe("Natural language or Sentry issue search query syntax."),
     sort: z
-      .enum(["date", "freq", "new", "user"])
+      .enum(["date", "freq", "new", "user", "recommended"])
       .default("date")
       .describe(
-        "Sort order: date (last seen), freq (frequency), new (first seen), user (user count)",
+        "Sort order: date (last seen), freq (frequency), new (first seen), user (user count), recommended (Sentry's prioritized ranking)",
       ),
     projectSlugOrId: ProjectSlugOrIdSchema.nullable()
       .default(null)
@@ -127,7 +127,7 @@ export default defineTool({
     }
 
     let query: string;
-    let sort: "date" | "freq" | "new" | "user";
+    let sort: "date" | "freq" | "new" | "user" | "recommended";
     let explanation: string | undefined;
 
     let projectId: string | undefined;

packages/mcp-core/src/tools/support/search-issues/README.md

@@ -33,7 +33,7 @@ The AI agent has access to these shared agent tools from `../../agent-tools/`:
 - ✅ Error feedback loop for self-correction
 - ✅ 'Me' reference resolution via whoami tool
 - ✅ Field discovery with custom tags
-- ✅ Smart sort options (date, freq, new, user)
+- ✅ Smart sort options (date, freq, new, user, recommended)
 - ✅ Configurable result limits (1-100, default 10)
 - ✅ Project-specific and organization-wide searches
 

packages/mcp-core/src/tools/support/search-issues/agent.ts

@@ -11,7 +11,7 @@ import { systemPrompt } from "./config";
 export const searchIssuesAgentOutputSchema = z.object({
   query: z.string().describe("The Sentry issue search query"),
   sort: z
-    .enum(["date", "freq", "new", "user"])
+    .enum(["date", "freq", "new", "user", "recommended"])
     .nullable()
     .describe("How to sort the results"),
   explanation: z

packages/mcp-core/src/tools/support/search-issues/config.ts

@@ -69,8 +69,10 @@ SORTING RULES:
 - freq: Event frequency
 - new: First seen
 - user: User count
+- recommended: Sentry's prioritized ranking
 - If the user asks to sort/rank by users or impact, set sort to user.
 - If the user asks for most frequent/noisy issues, set sort to freq.
+- If the user asks for what to look at/prioritize/triage first, set sort to recommended.
 - Never put sort syntax inside query.
 
 ME REFERENCES: