feat(update-issue): add optional reason parameter that posts as a comment (#988)

## Summary

Adds an optional `reason` parameter to the `update_issue` tool. When
provided, the reason is posted as a comment on the issue's activity feed
via the Sentry notes API (`POST /issues/{id}/notes/`).

This enables AI agents (like Claude routines doing triage) to explain
their rationale before or alongside taking actions like archiving noisy
issues.

## Changes

- **`schema.ts`** — New `ParamReason` zod schema (trimmed string, min 1
char)
- **`update-issue.ts`** — Added `reason` to `inputSchema` (optional),
description examples/hints, centralized `tryPostReasonComment` helper
with try/catch and `formatReasonCommentLine` for consistent output
- **`client.ts`** — New `createIssueComment()` method on
`SentryApiService`
- **`mcp-server-mocks/index.ts`** — Mock handler for the notes endpoint
- **`update-issue.test.ts`** — 4 new tests: reason posting, omission,
no-op state, and comment failure graceful degradation

## Behavior

- After a successful status/assignment update → posts reason as a
comment, shows it in output
- When no state changes are needed (already in requested state) → still
posts the reason comment and shows it in output
- When reason is omitted → no comment is posted (backward compatible)
- If the comment API call fails → the update result is still returned;
output shows `**Comment not posted**: <error>` instead of throwing
- `idempotentHint` changed to `false` since the reason comment is
non-idempotent

Requested-By: David Cramer

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Junior <junior@sentry.io>

Author: sentry-junior[bot]

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

@@ -2364,6 +2364,28 @@ export class SentryApiService {
     return IssueSchema.parse(body);
   }
 
+  async createIssueComment(
+    {
+      organizationSlug,
+      issueId,
+      text,
+    }: {
+      organizationSlug: string;
+      issueId: string;
+      text: string;
+    },
+    opts?: RequestOptions,
+  ): Promise<void> {
+    await this.requestJSON(
+      `/organizations/${organizationSlug}/issues/${issueId}/notes/`,
+      {
+        method: "POST",
+        body: JSON.stringify({ text }),
+      },
+      opts,
+    );
+  }
+
   // TODO: Sentry is not yet exposing a reasonable API to fetch trace data
   // async getTrace({
   //   organizationSlug,

packages/mcp-core/src/schema.ts

@@ -204,6 +204,14 @@ export const ParamIgnoreUserWindowMinutes = z
     "Optional time window in minutes for ignoreUserCount. If omitted, Sentry counts all future affected users.",
   );
 
+export const ParamReason = z
+  .string()
+  .trim()
+  .min(1)
+  .describe(
+    "Optional reason for taking this action. When provided, it will be posted as a comment on the issue's activity feed.",
+  );
+
 export const ParamSentryGuide = z
   .enum(SENTRY_GUIDES)
   .describe(

packages/mcp-core/src/skillDefinitions.json

@@ -199,7 +199,7 @@
       },
       {
         "name": "update_issue",
-        "description": "Update a Sentry issue's status or assignment.\n\nUse this to resolve, reopen, assign, or ignore an issue.\n\n<examples>\n```\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='resolved')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', assignedTo='user:123456')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='forever')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='untilOccurrenceCount', ignoreCount=100, ignoreWindowMinutes=60)\n```\n</examples>\n\n<hints>\n- Provide `issueUrl` or `organizationSlug` + `issueId`.\n- At least one of `status` or `assignedTo` is required.\n- `assignedTo` format: `user:ID` or `team:ID_OR_SLUG`.\n- Use `whoami` to find your user ID for self-assignment.\n- Status values: `resolved`, `resolvedInNextRelease`, `unresolved`, `ignored`.\n- `status='ignored'` defaults to `ignoreMode='untilEscalating'`.\n- Ignore modes: `untilEscalating`, `forever`, `forDuration`, `untilOccurrenceCount`, `untilUserCount`.\n- Matching ignore inputs are `ignoreDurationMinutes`, `ignoreCount` + optional `ignoreWindowMinutes`, or `ignoreUserCount` + optional `ignoreUserWindowMinutes`.\n- To switch an already ignored issue between `untilEscalating`, `forever`, and condition-based ignore modes, first set `status='unresolved'`, then ignore it again with the new rule.\n</hints>",
+        "description": "Update a Sentry issue's status or assignment.\n\nUse this to resolve, reopen, assign, or ignore an issue.\n\n<examples>\n```\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='resolved')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', assignedTo='user:123456')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='forever')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='untilOccurrenceCount', ignoreCount=100, ignoreWindowMinutes=60)\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', reason='Ignoring because this is expected noise from the staging deploy')\n```\n</examples>\n\n<hints>\n- Provide `issueUrl` or `organizationSlug` + `issueId`.\n- At least one of `status` or `assignedTo` is required.\n- `assignedTo` format: `user:ID` or `team:ID_OR_SLUG`.\n- Use `whoami` to find your user ID for self-assignment.\n- Status values: `resolved`, `resolvedInNextRelease`, `unresolved`, `ignored`.\n- `status='ignored'` defaults to `ignoreMode='untilEscalating'`.\n- Ignore modes: `untilEscalating`, `forever`, `forDuration`, `untilOccurrenceCount`, `untilUserCount`.\n- Matching ignore inputs are `ignoreDurationMinutes`, `ignoreCount` + optional `ignoreWindowMinutes`, or `ignoreUserCount` + optional `ignoreUserWindowMinutes`.\n- To switch an already ignored issue between `untilEscalating`, `forever`, and condition-based ignore modes, first set `status='unresolved'`, then ignore it again with the new rule.\n- `reason` is optional. When provided, it will be posted as a comment on the issue's activity feed explaining why the action was taken.\n</hints>",
         "requiredScopes": ["event:write"]
       },
       {

packages/mcp-core/src/toolDefinitions.json

@@ -1098,7 +1098,7 @@
   },
   {
     "name": "update_issue",
-    "description": "Update a Sentry issue's status or assignment.\n\nUse this to resolve, reopen, assign, or ignore an issue.\n\n<examples>\n```\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='resolved')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', assignedTo='user:123456')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='forever')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='untilOccurrenceCount', ignoreCount=100, ignoreWindowMinutes=60)\n```\n</examples>\n\n<hints>\n- Provide `issueUrl` or `organizationSlug` + `issueId`.\n- At least one of `status` or `assignedTo` is required.\n- `assignedTo` format: `user:ID` or `team:ID_OR_SLUG`.\n- Use `whoami` to find your user ID for self-assignment.\n- Status values: `resolved`, `resolvedInNextRelease`, `unresolved`, `ignored`.\n- `status='ignored'` defaults to `ignoreMode='untilEscalating'`.\n- Ignore modes: `untilEscalating`, `forever`, `forDuration`, `untilOccurrenceCount`, `untilUserCount`.\n- Matching ignore inputs are `ignoreDurationMinutes`, `ignoreCount` + optional `ignoreWindowMinutes`, or `ignoreUserCount` + optional `ignoreUserWindowMinutes`.\n- To switch an already ignored issue between `untilEscalating`, `forever`, and condition-based ignore modes, first set `status='unresolved'`, then ignore it again with the new rule.\n</hints>",
+    "description": "Update a Sentry issue's status or assignment.\n\nUse this to resolve, reopen, assign, or ignore an issue.\n\n<examples>\n```\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='resolved')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', assignedTo='user:123456')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='forever')\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', ignoreMode='untilOccurrenceCount', ignoreCount=100, ignoreWindowMinutes=60)\nupdate_issue(organizationSlug='my-org', issueId='PROJECT-123', status='ignored', reason='Ignoring because this is expected noise from the staging deploy')\n```\n</examples>\n\n<hints>\n- Provide `issueUrl` or `organizationSlug` + `issueId`.\n- At least one of `status` or `assignedTo` is required.\n- `assignedTo` format: `user:ID` or `team:ID_OR_SLUG`.\n- Use `whoami` to find your user ID for self-assignment.\n- Status values: `resolved`, `resolvedInNextRelease`, `unresolved`, `ignored`.\n- `status='ignored'` defaults to `ignoreMode='untilEscalating'`.\n- Ignore modes: `untilEscalating`, `forever`, `forDuration`, `untilOccurrenceCount`, `untilUserCount`.\n- Matching ignore inputs are `ignoreDurationMinutes`, `ignoreCount` + optional `ignoreWindowMinutes`, or `ignoreUserCount` + optional `ignoreUserWindowMinutes`.\n- To switch an already ignored issue between `untilEscalating`, `forever`, and condition-based ignore modes, first set `status='unresolved'`, then ignore it again with the new rule.\n- `reason` is optional. When provided, it will be posted as a comment on the issue's activity feed explaining why the action was taken.\n</hints>",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1179,6 +1179,11 @@
           "exclusiveMinimum": 0,
           "maximum": 10080,
           "description": "Optional time window in minutes for ignoreUserCount. If omitted, Sentry counts all future affected users."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional reason for taking this action. When provided, it will be posted as a comment on the issue's activity feed."
         }
       },
       "additionalProperties": false,

packages/mcp-core/src/tools/update-issue.test.ts

@@ -794,4 +794,195 @@ describe("update_issue", () => {
       ),
     ).rejects.toThrow("`ignoreWindowMinutes` requires `ignoreCount`");
   });
+
+  it("posts reason as a comment when updating issue status", async () => {
+    let commentPosted: { text: string } | undefined;
+    const currentIssue = createIssue({
+      status: "unresolved",
+      statusDetails: {},
+    });
+    const updatedIssue = createIssue({
+      status: "resolved",
+      statusDetails: {},
+    });
+
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(currentIssue),
+      ),
+      http.put(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(updatedIssue),
+      ),
+      http.post(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/notes/",
+        async ({ request }) => {
+          commentPosted = (await request.json()) as { text: string };
+          return HttpResponse.json({
+            id: "12345",
+            text: commentPosted.text,
+            type: "note",
+            dateCreated: new Date().toISOString(),
+          });
+        },
+      ),
+    );
+
+    const result = await updateIssue.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        issueId: "CLOUDFLARE-MCP-41",
+        status: "resolved",
+        assignedTo: undefined,
+        issueUrl: undefined,
+        regionUrl: null,
+        reason: "Resolved because the root cause was fixed in PR #123",
+      },
+      serverContext,
+    );
+
+    expect(commentPosted).toEqual({
+      text: "Resolved because the root cause was fixed in PR #123",
+    });
+    expect(result).toContain(
+      '**Comment posted**: "Resolved because the root cause was fixed in PR #123"',
+    );
+  });
+
+  it("does not post a comment when reason is not provided", async () => {
+    let commentPosted = false;
+    const currentIssue = createIssue({
+      status: "unresolved",
+      statusDetails: {},
+    });
+    const updatedIssue = createIssue({
+      status: "resolved",
+      statusDetails: {},
+    });
+
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(currentIssue),
+      ),
+      http.put(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(updatedIssue),
+      ),
+      http.post(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/notes/",
+        () => {
+          commentPosted = true;
+          return HttpResponse.json({});
+        },
+      ),
+    );
+
+    await updateIssue.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        issueId: "CLOUDFLARE-MCP-41",
+        status: "resolved",
+        assignedTo: undefined,
+        issueUrl: undefined,
+        regionUrl: null,
+      },
+      serverContext,
+    );
+
+    expect(commentPosted).toBe(false);
+  });
+
+  it("posts reason as a comment even when no state changes are needed", async () => {
+    let commentPosted: { text: string } | undefined;
+    const currentIssue = createIssue({
+      status: "resolved",
+      statusDetails: {},
+    });
+
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(currentIssue),
+      ),
+      http.post(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/notes/",
+        async ({ request }) => {
+          commentPosted = (await request.json()) as { text: string };
+          return HttpResponse.json({
+            id: "12345",
+            text: commentPosted.text,
+            type: "note",
+            dateCreated: new Date().toISOString(),
+          });
+        },
+      ),
+    );
+
+    const result = await updateIssue.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        issueId: "CLOUDFLARE-MCP-41",
+        status: "resolved",
+        assignedTo: undefined,
+        issueUrl: undefined,
+        regionUrl: null,
+        reason: "Confirmed this is no longer an issue after deploy",
+      },
+      serverContext,
+    );
+
+    expect(commentPosted).toEqual({
+      text: "Confirmed this is no longer an issue after deploy",
+    });
+    expect(result).toContain("No changes were needed.");
+    expect(result).toContain(
+      '**Comment posted**: "Confirmed this is no longer an issue after deploy"',
+    );
+  });
+
+  it("does not throw when comment posting fails after a successful update", async () => {
+    const currentIssue = createIssue({
+      status: "unresolved",
+      statusDetails: {},
+    });
+    const updatedIssue = createIssue({
+      status: "resolved",
+      statusDetails: {},
+    });
+
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(currentIssue),
+      ),
+      http.put(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/",
+        () => HttpResponse.json(updatedIssue),
+      ),
+      http.post(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/notes/",
+        () => HttpResponse.json({ detail: "Rate limited" }, { status: 429 }),
+      ),
+    );
+
+    const result = await updateIssue.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        issueId: "CLOUDFLARE-MCP-41",
+        status: "resolved",
+        assignedTo: undefined,
+        issueUrl: undefined,
+        regionUrl: null,
+        reason: "Resolving because fix deployed",
+      },
+      serverContext,
+    );
+
+    // Update succeeded — output should show it
+    expect(result).toContain("**Status**: unresolved → **resolved**");
+    // Comment failure should be reported gracefully, not thrown
+    expect(result).toContain("**Comment not posted**");
+  });
 });