feat(mcp): declare all four behavior hints on every tool (#3395)

## Summary

MCP compatibility checks fail any tool that does not declare `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` as booleans. Each tool set only one hint before this change.

- Adds presets in `packages/api/src/mcp/tools/annotations.ts`:
  - `READ_ONLY_TOOL` for get/list/query tools.
  - `UPSERT_TOOL` for create-or-update tools. They are not idempotent: omitting `id` creates a new object on every call.
  - `IDEMPOTENT_DESTRUCTIVE_TOOL` for `delete_*` and `patch_dashboard`.
- `openWorldHint` is `false` on every tool, because tools only touch the team's own Mongo metadata and ClickHouse data.
- `RegisterToolFn` now requires all four hints, so a new tool without them fails to compile.
- Test: `packages/api/src/mcp/__tests__/toolAnnotations.test.ts`.

**Downstream (EE) impact:** the EE-only tools `clickstack_get_source_filter_values`, `clickstack_backtest_anomaly_alert`, and `clickstack_list_teams` will fail typecheck on the upstream merge until they get annotations.

### How to reproduce

**Starting point:** local full stack (`yarn dev`) with `npx @modelcontextprotocol/inspector` connected to the local MCP endpoint (see `MCP.md`).

**On `main`:**

1. Run `initialize`, then `tools/list`.
2. Each tool's `annotations` has only one hint set.

**On this branch:**

1. Run `initialize`, then `tools/list`.
2. Every tool's `annotations` has all four hints set as booleans.

### How to test on Vercel preview

N/A — non-UI change.

### References

- Related PRs: `agent/mcp-tool-descriptions` (independent; touches neighboring lines, but the two 3-way merge cleanly)

Author: brandon-pereira

.changeset/mcp-tool-annotations.md

@@ -0,0 +1,5 @@
+---
+'@hyperdx/api': patch
+---
+
+feat(mcp): declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint on every MCP tool

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

@@ -0,0 +1,26 @@
+import { McpContext } from '@/mcp/tools/types';
+
+import { createTestClient } from './mcpTestUtils';
+
+describe('MCP tool annotations', () => {
+  const context: McpContext = { teamId: 'team-id', userId: 'user-id' };
+
+  it('declares every behavior hint as a boolean on every tool', async () => {
+    const client = await createTestClient(context);
+    const { tools } = await client.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+
+    const missing = tools.flatMap(tool =>
+      Object.entries({
+        readOnlyHint: tool.annotations?.readOnlyHint,
+        destructiveHint: tool.annotations?.destructiveHint,
+        idempotentHint: tool.annotations?.idempotentHint,
+        openWorldHint: tool.annotations?.openWorldHint,
+      })
+        .filter(([, value]) => typeof value !== 'boolean')
+        .map(([hint]) => `${tool.name}.annotations.${hint}`),
+    );
+
+    expect(missing).toEqual([]);
+  });
+});

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

@@ -2,6 +2,7 @@ import mongoose from 'mongoose';
 import { z } from 'zod';
 
 import { deleteWebhook } from '@/controllers/webhook';
+import { IDEMPOTENT_DESTRUCTIVE_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import { mcpUserError } from '@/mcp/utils/errors';
 import { objectIdSchema } from '@/utils/zod';
@@ -16,7 +17,7 @@ export function registerDeleteWebhook({
     'clickstack_delete_webhook',
     {
       title: 'Delete Webhook',
-      annotations: { destructiveHint: true },
+      annotations: IDEMPOTENT_DESTRUCTIVE_TOOL,
       description:
         'Permanently delete a webhook by ID. Blocked while any alert still ' +
         'references it — reassign or delete those alerts first. Use ' +

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

@@ -6,6 +6,7 @@ import { z } from 'zod';
 import * as config from '@/config';
 import { getRecentAlertHistories } from '@/controllers/alertHistory';
 import { getAlertById } from '@/controllers/alerts';
+import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import { mcpUserError, validateObjectId } from '@/mcp/utils/errors';
 import Alert from '@/models/alert';
@@ -25,7 +26,7 @@ export function registerGetAlert({
     'clickstack_get_alert',
     {
       title: 'Get Alert(s)',
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY_TOOL,
       description:
         'Without an ID: list all alerts as a high-level summary ' +
         '(id, name, displayName, tags, state, source, interval). Optionally ' +

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 
+import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import Webhook from '@/models/webhook';
 
@@ -13,7 +14,7 @@ export function registerGetWebhook({
     'clickstack_get_webhook',
     {
       title: 'List Webhooks',
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY_TOOL,
       description:
         'List available webhook destinations (id, name, service type). ' +
         'Use the returned id as the webhookId when creating alerts with ' +

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

@@ -8,6 +8,7 @@ import {
   updateAlert,
   validateAlertInput,
 } from '@/controllers/alerts';
+import { UPSERT_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import {
   formatZodIssues,
@@ -42,7 +43,7 @@ export function registerSaveAlert({
     'clickstack_save_alert',
     {
       title: 'Create or Update Alert',
-      annotations: { destructiveHint: true },
+      annotations: 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,6 +3,7 @@ import mongoose from 'mongoose';
 import { z } from 'zod';
 
 import { createWebhook, updateWebhook } from '@/controllers/webhook';
+import { UPSERT_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import {
   mcpServerError,
@@ -97,7 +98,7 @@ export function registerSaveWebhook({
     'clickstack_save_webhook',
     {
       title: 'Create or Update Webhook',
-      annotations: { destructiveHint: true },
+      annotations: 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

@@ -0,0 +1,44 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * The four behavior hints every tool must declare. Platform compatibility
+ * checks reject tools that leave any of them unset.
+ */
+export type ToolBehaviorAnnotations = Required<
+  Pick<
+    ToolAnnotations,
+    'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'
+  >
+>;
+
+// Every tool reads or writes only the calling team's own ClickStack metadata
+// (MongoDB) and telemetry (ClickHouse), so none of them is open-world.
+
+export const READ_ONLY_TOOL: ToolBehaviorAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};
+
+/**
+ * Create-or-update tools: omitting `id` creates a new object on every call
+ * (not idempotent), and providing `id` overwrites the stored object.
+ */
+export const UPSERT_TOOL: ToolBehaviorAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false,
+};
+
+/**
+ * Updates or deletes an existing object by ID. Repeating the call with the
+ * same arguments leaves the same end state.
+ */
+export const IDEMPOTENT_DESTRUCTIVE_TOOL: ToolBehaviorAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,
+  openWorldHint: false,
+};

packages/api/src/mcp/tools/dashboards/deleteDashboard.ts

@@ -2,6 +2,7 @@ import mongoose from 'mongoose';
 import { z } from 'zod';
 
 import { deleteDashboard } from '@/controllers/dashboard';
+import { IDEMPOTENT_DESTRUCTIVE_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import { mcpUserError } from '@/mcp/utils/errors';
 import Dashboard from '@/models/dashboard';
@@ -17,7 +18,7 @@ export function registerDeleteDashboard({
     'clickstack_delete_dashboard',
     {
       title: 'Delete Dashboard',
-      annotations: { destructiveHint: true },
+      annotations: IDEMPOTENT_DESTRUCTIVE_TOOL,
       description:
         'Permanently delete a dashboard by ID. Also removes any alerts attached to its tiles. ' +
         'Use clickstack_get_dashboard (without an ID) to list available dashboard IDs.',

packages/api/src/mcp/tools/dashboards/getDashboard.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 
 import * as config from '@/config';
 import { getDashboards } from '@/controllers/dashboard';
+import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
 import type { ToolRegistrar } from '@/mcp/tools/types';
 import { mcpUserError, validateObjectId } from '@/mcp/utils/errors';
 import Dashboard from '@/models/dashboard';
@@ -21,7 +22,7 @@ export function registerGetDashboard({
     'clickstack_get_dashboard',
     {
       title: 'Get Dashboard(s)',
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY_TOOL,
       description:
         'Without an ID: list all dashboards (returns IDs, names, tags). ' +
         'With an ID: get full dashboard detail including all tiles and configuration.',