fix(mcp): mark save_webhook and save_alert as open-world

.changeset/mcp-open-world-alert-webhook.md

@@ -0,0 +1,7 @@
+---
+'@hyperdx/api': patch
+---
+
+fix: mark the MCP `clickstack_save_webhook` and `clickstack_save_alert` tools as open-world
+
+Saved webhooks and alerts send HTTP requests to third-party endpoints, so both tools now declare `openWorldHint: true`.

packages/api/src/mcp/__tests__/toolAnnotations.test.ts

@@ -24,6 +24,21 @@ describe('MCP tool annotations', () => {
     expect(missing).toEqual([]);
   });
 
+  it('marks only tools that configure outbound notifications as open-world', async () => {
+    const client = await createTestClient(context);
+    const { tools } = await client.listTools();
+
+    const openWorld = tools
+      .filter(tool => tool.annotations?.openWorldHint)
+      .map(tool => tool.name)
+      .sort();
+
+    expect(openWorld).toEqual([
+      'clickstack_save_alert',
+      'clickstack_save_webhook',
+    ]);
+  });
+
   it('mirrors the tool title into annotations.title', async () => {
     const client = await createTestClient(context);
     const { tools } = await client.listTools();

packages/api/src/mcp/tools/alerts/saveAlert.ts

@@ -8,7 +8,7 @@ import {
   updateAlert,
   validateAlertInput,
 } from '@/controllers/alerts';
-import { UPSERT_TOOL } from '@/mcp/tools/annotations';
+import { OPEN_WORLD_UPSERT_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import {
   formatZodIssues,
@@ -43,7 +43,7 @@ export function registerSaveAlert({
     'clickstack_save_alert',
     {
       title: 'Create or Update Alert',
-      annotations: UPSERT_TOOL,
+      annotations: OPEN_WORLD_UPSERT_TOOL,
       description:
         'Create a new alert (omit id) or update an existing one (provide id). ' +
         'Alerts monitor a saved search, a dashboard tile, or an inline chart ' +

packages/api/src/mcp/tools/alerts/saveWebhook.ts

@@ -3,7 +3,7 @@ import mongoose from 'mongoose';
 import { z } from 'zod';
 
 import { createWebhook, updateWebhook } from '@/controllers/webhook';
-import { UPSERT_TOOL } from '@/mcp/tools/annotations';
+import { OPEN_WORLD_UPSERT_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import {
   mcpServerError,
@@ -106,7 +106,7 @@ export function registerSaveWebhook({
     'clickstack_save_webhook',
     {
       title: 'Create or Update Webhook',
-      annotations: UPSERT_TOOL,
+      annotations: OPEN_WORLD_UPSERT_TOOL,
       description:
         'Create a new webhook (omit id) or update an existing one (provide ' +
         'id). Use the returned id as the webhookId when creating alerts with ' +

packages/api/src/mcp/tools/annotations.ts

@@ -11,8 +11,9 @@ export type ToolBehaviorAnnotations = Required<
   >
 >;
 
-// Every tool reads or writes only the calling team's own ClickStack metadata
-// (MongoDB) and telemetry (ClickHouse), so none of them is open-world.
+// Tools read or write only the calling team's own ClickStack metadata
+// (MongoDB) and telemetry (ClickHouse), so they are closed-world. The
+// exception is OPEN_WORLD_UPSERT_TOOL.
 
 export const READ_ONLY_TOOL: ToolBehaviorAnnotations = {
   readOnlyHint: true,
@@ -32,6 +33,15 @@ export const UPSERT_TOOL: ToolBehaviorAnnotations = {
   openWorldHint: false,
 };
 
+/**
+ * Upserts whose saved object makes ClickStack send HTTP requests to
+ * third-party endpoints (webhooks, and the alerts that notify them).
+ */
+export const OPEN_WORLD_UPSERT_TOOL: ToolBehaviorAnnotations = {
+  ...UPSERT_TOOL,
+  openWorldHint: true,
+};
+
 /**
  * Updates or deletes an existing object by ID. Repeating the call with the
  * same arguments leaves the same end state.