vantage-peers-mcp 2.4.0 → 2.4.2

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/vantage-peers-mcp)](https://www.npmjs.com/package/vantage-peers-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/vantage-peers-mcp)](https://www.npmjs.com/package/vantage-peers-mcp)
 [![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue)](https://github.com/vantageos-agency/vantage-peers/blob/main/LICENSE)
-[![Tests: 82/82](https://img.shields.io/badge/MCP_tools-82_registered-green)]()
+[![Tests: 84/84](https://img.shields.io/badge/MCP_tools-84_registered-green)]()
 
 MCP server for [VantagePeers](https://vantagepeers.com) — shared memory, messaging, and task coordination for AI agent teams.
 
-82 tools across 18 categories: memory, profiles, tasks, missions, mission templates, messages, diary, briefing notes, search (RAG), issues, fix patterns, error monitoring, deployments, business units, components, mandates, recurring tasks, and session.
+84 tools across 18 categories: memory, profiles, tasks, missions, mission templates, messages, diary, briefing notes, search (RAG), issues, fix patterns, error monitoring, deployments, business units, components, mandates, recurring tasks, and session. All tools ship with ChatGPT Apps SDK annotations (`readOnlyHint`, `openWorldHint`, `destructiveHint`) for native UX in ChatGPT custom connectors.
 
 ## Quick start
 
@@ -74,7 +74,7 @@ VantagePeers ships a built-in OAuth 2.1 authorization server so Claude.ai web ca
 
 The server also reads `CONVEX_URL` from `.env.local` in the parent directory if not set via environment.
 
-## Tools (82)
+## Tools (84)
 
 ### Memory (6)
 `store_memory`, `recall`, `list_memories`, `soft_delete_memory`, `get_memory`, `store_episode`
@@ -400,6 +400,17 @@ All orchestrator names are open strings — any lowercase name is accepted. The
 
 ## Changelog
 
+### 2.4.1 — 2026-05-30 (Day 88)
+- fix(dcr): `oauthDcr:validateAccessToken` exposed as PUBLIC `query` (was `internalQuery`, unreachable via `ConvexHttpClient.query()` → Path 3 DCR returned 401 even with valid token) — issue #556 / PR #557.
+- fix(dcr): `WWW-Authenticate` header now emits `Bearer resource_metadata="..."` per MCP spec §Protected Resource Metadata Discovery (was `resource="..."` — broke Claude.ai PRM discovery bootstrap on 401) — PR #557.
+- feat(mcp): ChatGPT Apps SDK tool annotations on all 84 tools (`readOnlyHint`, `openWorldHint`, `destructiveHint`) — 34 read-only + 41 write + 9 destructive — PR #555.
+- security(dcr): DCR scope isolation — new `public-readonly` profile + cross-tenant assertion tests + `scopeProfile` forced to `client-generic` for auto-discovery flow (never `master`) — PR #554.
+- docs(cloud): dedicated `/docs/cloud/` section in vantage-peers-site for VantagePeers Cloud (multi-tenant, multi-clients MCP: Claude.ai, ChatGPT, Claude Code, Codex) — site PR #120.
+
+### 2.4.0 — 2026-05-29 (Day 86)
+- feat(m3): `iframeEmbedSessions` table + `__VP_TOOL_RESULT__` stream marker + ack-checklist primitive — PR #545.
+- feat(v0.0.2-auth): `credentials:issueBearerFromClerk` httpAction + audit log + iter 2 P1 fixes — PR #546.
+
 ### 2.3.0 — 2026-05-26
 - `list_tasks`, `list_missions`, `list_tasks_by_mission`, `list_briefing_notes` now accept `fields=lite` for compact payloads (less tokens).
 - Status filters now accept arrays and aliases: `status=["todo","in_progress"]`, `status="open"` (expands to non-terminal), `status="active"` (in_progress only on tasks; plan+execute on missions), `status="all"` (no filter).

package/dist/src/auth.js

@@ -119,8 +119,20 @@ export function checkNamespaceRead(ctx, namespace) {
         return null;
     if (isMasterScope(ctx))
         return null;
-    if (!namespace)
-        return null; // no namespace filter — list-across, which master-only in practice
+    if (!namespace) {
+        // Day 88 P0 fix: a list-across (namespace undefined) call from a
+        // non-master scope cannot be served safely — the underlying query
+        // returns rows across every tenant. Reject with an explicit message
+        // telling the caller to pass a namespace they own. Previously this
+        // returned null and leaked the whole memories/profiles/etc. table
+        // to any DCR-issued client.
+        const allowed = ctx.namespaceReadPrefixes.length > 0
+            ? ctx.namespaceReadPrefixes.join(", ")
+            : "(none — your client has no read scope)";
+        return ("Forbidden: this tool requires an explicit namespace argument when " +
+            `called with a non-master scope (current: ${ctx.scopeProfile}). ` +
+            `Pass namespace= one of: ${allowed}.`);
+    }
     if (checkNamespacePrefix(ctx.namespaceReadPrefixes, namespace))
         return null;
     return `Forbidden: namespace='${namespace}' is not readable by scope_profile=${ctx.scopeProfile}.`;
@@ -139,11 +151,13 @@ export function checkNamespaceWrite(ctx, namespace) {
 // ─────────────────────────────────────────────────────────────────────────────
 export function bearerAuthMiddleware() {
     return async (c, next) => {
-        // RFC 6750 §3 — point clients at the protected-resource metadata so
-        // Claude.ai's OAuth connector can bootstrap discovery from any 401.
+        // MCP spec §"Protected Resource Metadata Discovery Requirements" + RFC 6750 §3 —
+        // the param MUST be `resource_metadata=` (not `resource=`). Claude.ai's OAuth
+        // connector looks for `resource_metadata=` to bootstrap PRM discovery; with
+        // `resource=` the entire DCR chain breaks before any token is issued.
         const publicBaseUrl = process.env.PUBLIC_BASE_URL ??
             "https://vantage-peers-production.up.railway.app";
-        const wwwAuthHeader = `Bearer resource="${publicBaseUrl}/.well-known/oauth-protected-resource"`;
+        const wwwAuthHeader = `Bearer resource_metadata="${publicBaseUrl}/.well-known/oauth-protected-resource"`;
         const authHeader = c.req.header("Authorization");
         if (!authHeader?.startsWith("Bearer ")) {
             c.header("WWW-Authenticate", wwwAuthHeader);
@@ -215,6 +229,10 @@ export function bearerAuthMiddleware() {
         // ── (3) DCR OAuth token — check oauthTokens via oauthDcr:validateAccessToken
         // Uses raw token (not hashed) — the DCR table stores tokens in plaintext.
         // This path handles Claude.ai clients registered via POST /register.
+        // NOTE: validateAccessToken is exposed as a PUBLIC query (not internalQuery)
+        // because ConvexHttpClient.query() only resolves public functions. Making it
+        // internal silently breaks the DCR path (#556). Security: lookup is keyed
+        // on the high-entropy opaque token; returns null on miss with no PII echo.
         let dcrResult = null;
         try {
             dcrResult = (await internalClient().query(

package/dist/src/tools.js

@@ -153,7 +153,9 @@ const taskStatusValues = [
     "done",
 ];
 const taskStatusAliases = ["open", "active", "all"];
-export const taskStatusSchema = z.enum(taskStatusValues).describe("Task status");
+export const taskStatusSchema = z
+    .enum(taskStatusValues)
+    .describe("Task status");
 const missionStatusValues = [
     "brainstorm",
     "plan",
@@ -176,7 +178,7 @@ export const taskStatusFilterSchema = z
 ])
     .describe('Task status filter. Single status ("todo"|"in_progress"|"review"|"blocked"|"done"), ' +
     'alias ("open" = todo+in_progress+review+blocked, "active" = todo+in_progress, "all" = no filter), ' +
-    'or array of direct statuses (no aliases inside array).');
+    "or array of direct statuses (no aliases inside array).");
 export const missionStatusFilterSchema = z
     .union([
     z.enum([...missionStatusValues, ...missionStatusAliases]),
@@ -184,13 +186,13 @@ export const missionStatusFilterSchema = z
 ])
     .describe('Mission status filter. Single status ("brainstorm"|"plan"|"execute"|"validate"|"complete"), ' +
     'alias ("open" = brainstorm+plan+execute+validate, "active" = plan+execute, "all" = no filter), ' +
-    'or array of direct statuses (no aliases inside array).');
+    "or array of direct statuses (no aliases inside array).");
 // v2.3.2 — fields projection toggle. "lite" returns compact projection
 // (5-10× smaller payload), "full" (default) returns full doc.
 export const fieldsSchema = z
     .enum(["lite", "full"])
     .describe('Field projection — "lite" returns compact fields only ' +
-    '(typical 5-10× smaller payload for large list scans), ' +
+    "(typical 5-10× smaller payload for large list scans), " +
     '"full" (default) returns the full document.');
 // v2.3.3 — Unix timestamp ms filter for "updated since".
 // Pass `Date.now() - 24*60*60*1000` for "last 24h" pattern.
@@ -296,7 +298,8 @@ export function parseConvexError(rawMessage) {
     let code = "ServerError";
     let remainder = stripped;
     for (const candidate of knownCodes) {
-        if (stripped.startsWith(candidate + ":") || stripped.startsWith(candidate + " ")) {
+        if (stripped.startsWith(candidate + ":") ||
+            stripped.startsWith(candidate + " ")) {
             code = candidate;
             remainder = stripped.slice(candidate.length).replace(/^[:\s]+/, "");
             break;
@@ -305,10 +308,13 @@ export function parseConvexError(rawMessage) {
     // Extract "Path: .<fieldPath>" from the tail of the message
     // Convex appends this as the last sentence: "Path: .linkedMemoryIds[4]"
     let path = null;
-    const pathMatch = remainder.match(/\bPath:\s*([\w.\[\]"']+)\s*$/);
+    const pathMatch = remainder.match(/\bPath:\s*([\w.[\]"']+)\s*$/);
     if (pathMatch) {
         path = pathMatch[1];
-        remainder = remainder.slice(0, pathMatch.index).trim().replace(/\.\s*$/, "");
+        remainder = remainder
+            .slice(0, pathMatch.index)
+            .trim()
+            .replace(/\.\s*$/, "");
     }
     // Build a concise hint for common patterns
     let hint = null;
@@ -412,6 +418,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Optional expiry ISO timestamp e.g. '2026-06-01T00:00:00Z'"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Store memory",
     }, async ({ namespace, type, content, createdBy, relatesTo, ttl }) => {
         let contentBytes = 0;
         try {
@@ -461,6 +472,11 @@ export function registerTools(server, convex, oauthCtx) {
         memoryId: z
             .string()
             .describe("Convex document ID of the memory to soft-delete"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Delete memory (soft)",
     }, async ({ memoryId }) => {
         try {
             const denied = guardMasterOnly("soft_delete_memory");
@@ -485,8 +501,16 @@ export function registerTools(server, convex, oauthCtx) {
     // ── get_memory ──────────────────────────────────────────────────────────────
     server.tool("get_memory", "Fetch a single memory by its ID. Returns full memory content including relations and episode data.", {
         memoryId: z.string().describe("Memory document ID"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get memory",
     }, async ({ memoryId }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_memory");
+            if (_scopeDenied)
+                return _scopeDenied;
             const memory = await convex.query("memories:getMemory", {
                 memoryId,
             });
@@ -519,6 +543,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(5)
             .describe("Maximum number of results to return (default 5)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Recall memories",
     }, async ({ query, namespace, type, limit }) => {
         try {
             const nsDenied = guardRead(namespace);
@@ -559,6 +588,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(10)
             .describe("Max results"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Search memories (text)",
     }, async ({ query, namespace, type, limit }) => {
         try {
             const nsDenied = guardRead(namespace);
@@ -603,6 +637,11 @@ export function registerTools(server, convex, oauthCtx) {
             .max(1)
             .optional()
             .describe("Weight for text results in RRF (default: 0.5)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Search memories (hybrid)",
     }, async ({ query, namespace, type, limit, vectorWeight, textWeight }) => {
         try {
             const nsDenied = guardRead(namespace);
@@ -642,6 +681,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .describe("The lesson extracted — procedural memory, what to do differently"),
         severity: severitySchema,
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Store episode",
     }, async ({ namespace, createdBy, context, goal, action, outcome, insight, severity, }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -677,8 +721,16 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("get_profile", "Fetch an orchestrator profile (static identity + dynamic session state). " +
         "Returns null if the profile does not exist yet — call update_profile to create it.", {
         orchestratorId: z.string().describe("Orchestrator identifier"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get orchestrator profile",
     }, async ({ orchestratorId }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_profile");
+            if (_scopeDenied)
+                return _scopeDenied;
             const profile = await convex.query("profiles:getProfile", {
                 orchestratorId,
             });
@@ -724,6 +776,11 @@ export function registerTools(server, convex, oauthCtx) {
         })
             .optional()
             .describe("Mutable session state — updated each session"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update orchestrator profile",
     }, async ({ orchestratorId, name, static: staticFields, dynamic }) => {
         try {
             const fromDenied = guardFrom(orchestratorId);
@@ -766,6 +823,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(20)
             .describe("Maximum number of memories to return (default 20)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List memories",
     }, async ({ namespace, type, limit }) => {
         try {
             const nsDenied = guardRead(namespace);
@@ -822,6 +884,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Tenant identifier for multi-tenant isolation"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Send message",
     }, async ({ from, fromInstanceId, channel, content, sessionDay, tenantId, }) => {
         let contentBytes = 0;
         try {
@@ -876,8 +943,20 @@ export function registerTools(server, convex, oauthCtx) {
             .int()
             .optional()
             .describe("Unix timestamp (ms). If provided, only messages with _creationTime > since are returned. Use for incremental polling — pass the timestamp of your last check to get only new messages. Omit for full unread backlog."),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Check messages",
     }, async ({ recipient, recipientInstanceId, tenantId, since }) => {
         try {
+            // Non-master: force recipient to caller's own userId. Anything else
+            // would let the client read another tenant's inbox.
+            if (oauthCtx && !isMasterScope(oauthCtx)) {
+                if (recipient !== oauthCtx.userId) {
+                    return mcpError(`Forbidden: check_messages can only read messages for your own identity ('${oauthCtx.userId}'), not '${recipient}'.`);
+                }
+            }
             const messages = await convex.query("messages:checkNewMessages", {
                 recipient,
                 recipientInstanceId,
@@ -915,6 +994,11 @@ export function registerTools(server, convex, oauthCtx) {
         receiptIds: z
             .union([z.array(receiptIdSchema).min(1), receiptIdSchema])
             .describe("Receipt IDs to mark as read — array or single string"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Mark messages as read",
     }, async ({ receiptIds }) => {
         try {
             let receiptIdsArray;
@@ -957,6 +1041,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — must be the sender or system"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Delete message",
     }, async ({ messageId, callerOrchestrator }) => {
         try {
             if (callerOrchestrator) {
@@ -991,6 +1080,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe("Instance ID — e.g. 'pi-chromebook', 'pi-vps', 'tau-vps-1'"),
         summary: z.string().describe("1-2 sentence summary of current work"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Set instance summary",
     }, async ({ orchestratorId, instanceId, summary }) => {
         try {
             const fromDenied = guardFrom(orchestratorId);
@@ -1017,8 +1111,16 @@ export function registerTools(server, convex, oauthCtx) {
     });
     // ── list_peers ──────────────────────────────────────────────────────────────
     server.tool("list_peers", "List all orchestrator profiles with their current status and summary. " +
-        "Replaces claude-peers list_peers.", {}, async () => {
-        try {
+        "Replaces claude-peers list_peers.", {}, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List peers",
+    }, async () => {
+        try {
+            const _scopeDenied = guardMasterOnly("list_peers");
+            if (_scopeDenied)
+                return _scopeDenied;
             const profiles = await convex.query("profiles:listProfiles", {});
             const peers = profiles.map((p) => ({
                 id: p.orchestratorId,
@@ -1059,8 +1161,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(100)
             .describe("Max messages to return (default 100)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List messages",
     }, async ({ sessionDay, from, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_messages");
+            if (_scopeDenied)
+                return _scopeDenied;
             const messages = await convex.query("messages:listMessages", {
                 sessionDay,
                 from,
@@ -1092,8 +1202,16 @@ export function registerTools(server, convex, oauthCtx) {
         messageId: z
             .string()
             .describe("Convex document ID of the broadcast message"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List broadcast status",
     }, async ({ messageId }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_broadcast_status");
+            if (_scopeDenied)
+                return _scopeDenied;
             const status = await convex.query("messages:listBroadcastStatus", {
                 messageId,
             });
@@ -1144,6 +1262,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe("Optional due date as Unix timestamp (ms)"),
         createdBy: creatorSchema,
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create task",
     }, async ({ title, description, project, tags, assignedTo, assignedToInstance, priority, status, dependsOn, missionId, estimatedMinutes, dueDate, createdBy, }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -1206,8 +1329,23 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe("Filter by task creator (e.g. 'pi' to find Pi-dispatched tasks)"),
         updatedSince: updatedSinceSchema.optional(),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List tasks",
     }, async ({ assignedTo, assignedToInstance, status, project, limit, fields, createdBy, updatedSince, }) => {
         try {
+            // Non-master: must scope to own identity. If neither assignedTo
+            // nor createdBy matches the caller's userId, reject — otherwise
+            // the query would span the whole tenant table.
+            if (oauthCtx && !isMasterScope(oauthCtx)) {
+                const myId = oauthCtx.userId;
+                const scopedToSelf = assignedTo === myId || createdBy === myId;
+                if (!scopedToSelf) {
+                    return mcpError(`Forbidden: list_tasks requires assignedTo='${myId}' or createdBy='${myId}' for non-master scope (current: ${oauthCtx.scopeProfile}).`);
+                }
+            }
             const tasks = await convex.query("tasks:list", {
                 assignedTo,
                 assignedToInstance,
@@ -1276,6 +1414,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — if provided, must be creator or assignee"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update task",
     }, async ({ taskId, title, description, project, tags, assignedTo, priority, status, dependsOn, missionId, estimatedMinutes, actualMinutes, startedAt, completedAt, dueDate, callerOrchestrator, }) => {
         try {
             if (callerOrchestrator) {
@@ -1330,6 +1473,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — if provided, must be creator or assignee"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Complete task",
     }, async ({ taskId, completionNote, callerOrchestrator }) => {
         try {
             if (callerOrchestrator) {
@@ -1362,6 +1510,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — if provided, must be creator or assignee"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Start task",
     }, async ({ taskId, callerOrchestrator }) => {
         try {
             if (callerOrchestrator) {
@@ -1395,6 +1548,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Instance identifier, e.g. 'sigma-vps'"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Checkout task",
     }, async ({ taskId, callerOrchestrator, callerInstance }) => {
         try {
             const fromDenied = guardFrom(callerOrchestrator);
@@ -1424,6 +1582,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — must be creator or system"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Delete task",
     }, async ({ taskId, callerOrchestrator }) => {
         try {
             if (callerOrchestrator) {
@@ -1459,6 +1622,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — must be creator or assignee"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Block task",
     }, async ({ taskId, reason, blockedBy, callerOrchestrator }) => {
         try {
             if (callerOrchestrator) {
@@ -1502,6 +1670,11 @@ export function registerTools(server, convex, oauthCtx) {
         callerOrchestrator: creatorSchema
             .optional()
             .describe("Optional RBAC — must be creator or assignee"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Add task dependency",
     }, async ({ taskId, dependsOn, callerOrchestrator }) => {
         try {
             if (callerOrchestrator) {
@@ -1545,12 +1718,18 @@ export function registerTools(server, convex, oauthCtx) {
         fields: fieldsSchema
             .optional()
             .describe('Field projection ("lite"|"full")'),
-        createdBy: assigneeSchema
-            .optional()
-            .describe("Filter by task creator"),
+        createdBy: assigneeSchema.optional().describe("Filter by task creator"),
         updatedSince: updatedSinceSchema.optional(),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List tasks by mission",
     }, async ({ missionId, status, limit, fields, createdBy, updatedSince }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_tasks_by_mission");
+            if (_scopeDenied)
+                return _scopeDenied;
             const tasks = await convex.query("tasks:listByMission", {
                 missionId: missionId,
                 status,
@@ -1592,6 +1771,11 @@ export function registerTools(server, convex, oauthCtx) {
             .describe("Target completion date (Unix ms)"),
         progress: z.number().optional().describe("Progress percentage (0-100)"),
         createdBy: creatorSchema,
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create mission",
     }, async ({ name, description, project, status, priority, pilot, agents, brief, startDate, targetDate, progress, createdBy, }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -1646,8 +1830,20 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe('Field projection ("lite"|"full")'),
         updatedSince: updatedSinceSchema.optional(),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List missions",
     }, async ({ project, pilot, status, limit, fields, updatedSince }) => {
         try {
+            // Non-master: must pilot=<own-userId>. Otherwise the query spans
+            // every tenant's missions.
+            if (oauthCtx && !isMasterScope(oauthCtx)) {
+                if (pilot !== oauthCtx.userId) {
+                    return mcpError(`Forbidden: list_missions requires pilot='${oauthCtx.userId}' for non-master scope (current: ${oauthCtx.scopeProfile}).`);
+                }
+            }
             const missions = await convex.query("missions:list", {
                 project,
                 pilot,
@@ -1682,8 +1878,16 @@ export function registerTools(server, convex, oauthCtx) {
     // ── get_mission ─────────────────────────────────────────────────────────────
     server.tool("get_mission", "Fetch a single mission by ID. Returns full mission details including status, pilot, agents, progress, and dates.", {
         missionId: z.string().describe("Convex document ID of the mission"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get mission",
     }, async ({ missionId }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_mission");
+            if (_scopeDenied)
+                return _scopeDenied;
             const mission = await convex.query("missions:get", {
                 missionId: missionId,
             });
@@ -1717,6 +1921,11 @@ export function registerTools(server, convex, oauthCtx) {
         startDate: z.number().optional().describe("New start date (Unix ms)"),
         targetDate: z.number().optional().describe("New target date (Unix ms)"),
         progress: z.number().optional().describe("New progress (0-100)"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update mission",
     }, async ({ missionId, name, description, project, status, priority, pilot, agents, brief, startDate, targetDate, progress, }) => {
         try {
             if (pilot) {
@@ -1755,6 +1964,11 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("update_mission_status", "Change a mission's status. Shortcut for updating only the status field.", {
         missionId: z.string().describe("Convex document ID of the mission"),
         status: missionStatusSchema.describe("New status"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update mission status",
     }, async ({ missionId, status }) => {
         try {
             await convex.mutation("missions:updateStatus", {
@@ -1782,6 +1996,11 @@ export function registerTools(server, convex, oauthCtx) {
         content: z.string().describe("Full diary entry content"),
         highlights: flexArrayOptional.describe("Key highlights of the day"),
         blockers: flexArrayOptional.describe("Blockers encountered"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Write diary entry",
     }, async ({ date, orchestrator, content, highlights, blockers }) => {
         let contentBytes = 0;
         try {
@@ -1821,8 +2040,16 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("get_diary", "Fetch a diary entry for a specific date and orchestrator. Returns null if no entry exists.", {
         date: z.string().describe("ISO date string — e.g. '2026-03-25'"),
         orchestrator: creatorSchema.describe("Which orchestrator's diary to fetch"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get diary entry",
     }, async ({ date, orchestrator }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_diary");
+            if (_scopeDenied)
+                return _scopeDenied;
             const entry = await convex.query("diary:get", {
                 date,
                 orchestrator,
@@ -1864,8 +2091,19 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(20)
             .describe("Maximum entries to return (default 20)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List diary entries",
     }, async ({ orchestrator, limit }) => {
         try {
+            // Non-master: must scope to own orchestrator id.
+            if (oauthCtx && !isMasterScope(oauthCtx)) {
+                if (orchestrator !== oauthCtx.userId) {
+                    return mcpError(`Forbidden: list_diaries requires orchestrator='${oauthCtx.userId}' for non-master scope (current: ${oauthCtx.scopeProfile}).`);
+                }
+            }
             const entries = await convex.query("diary:list", {
                 orchestrator,
                 limit: limit ?? 20,
@@ -1906,6 +2144,11 @@ export function registerTools(server, convex, oauthCtx) {
             "Passing a briefingNotes ID will fail with ArgumentValidationError at path .linkedMemoryIds[N]. " +
             "If cross-linking briefings is needed, request the linkedBriefingIds feature instead."),
         createdBy: creatorSchema,
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create briefing note",
     }, async ({ title, topic, participants, content, decisions, linkedMemoryIds, createdBy, }) => {
         let contentBytes = 0;
         try {
@@ -1945,7 +2188,12 @@ export function registerTools(server, convex, oauthCtx) {
         }
     });
     // ── update_briefing_note ────────────────────────────────────────────────────
-    server.tool("update_briefing_note", updateBriefingNoteDescription, updateBriefingNoteSchema.shape, async ({ noteId, callerOrchestrator, title, topic, participants, content, decisions, linkedMemoryIds, }) => {
+    server.tool("update_briefing_note", updateBriefingNoteDescription, updateBriefingNoteSchema.shape, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update briefing note",
+    }, async ({ noteId, callerOrchestrator, title, topic, participants, content, decisions, linkedMemoryIds, }) => {
         let contentBytes = 0;
         try {
             if (content !== undefined) {
@@ -2002,8 +2250,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe('Field projection ("lite"|"full")'),
         updatedSince: updatedSinceSchema.optional(),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List briefing notes",
     }, async ({ topic, limit, fields, updatedSince }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_briefing_notes");
+            if (_scopeDenied)
+                return _scopeDenied;
             const notes = await convex.query("briefingNotes:list", {
                 topic,
                 limit,
@@ -2055,6 +2311,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe("Project this component belongs to"),
         createdBy: creatorSchema,
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Register component",
     }, async ({ name, type, team, content, version, project, createdBy }) => {
         let contentBytes = 0;
         try {
@@ -2105,8 +2366,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(100)
             .describe("Maximum components to return (default 100)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List components",
     }, async ({ type, team, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_components");
+            if (_scopeDenied)
+                return _scopeDenied;
             const components = await convex.query("components:list", {
                 type,
                 team,
@@ -2129,8 +2398,16 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("get_component", "Fetch a single component by name and type. Returns the full content.", {
         name: z.string().describe("Component name"),
         type: componentTypeSchema,
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get component",
     }, async ({ name, type }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_component");
+            if (_scopeDenied)
+                return _scopeDenied;
             const component = await convex.query("components:get", {
                 name,
                 type,
@@ -2156,6 +2433,11 @@ export function registerTools(server, convex, oauthCtx) {
         content: z.string().optional().describe("New content/source code"),
         version: z.string().optional().describe("New version string"),
         project: z.string().optional().describe("New project name"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update component",
     }, async ({ componentId, ...fields }) => {
         let contentBytes = 0;
         try {
@@ -2191,6 +2473,11 @@ export function registerTools(server, convex, oauthCtx) {
         componentId: z
             .string()
             .describe("Convex document ID of the component to delete"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Delete component",
     }, async ({ componentId }) => {
         try {
             const result = await convex.mutation("components:remove", {
@@ -2211,8 +2498,16 @@ export function registerTools(server, convex, oauthCtx) {
             .describe("Search term to match against component name or team"),
         type: componentTypeSchema.optional().describe("Filter by component type"),
         limit: z.number().int().optional().describe("Max results (default 50)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Search components",
     }, async ({ query, type, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("search_components");
+            if (_scopeDenied)
+                return _scopeDenied;
             const results = await convex.query("components:search", {
                 query,
                 type,
@@ -2243,6 +2538,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .describe("5-field cron: minute hour day-of-month month day-of-week"),
         createdBy: creatorSchema,
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create recurring task",
     }, async ({ title, description, assignedTo, priority, project, tags, cronExpression, createdBy, }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -2291,8 +2591,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Max results"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List recurring tasks",
     }, async ({ assignedTo, active, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_recurring_tasks");
+            if (_scopeDenied)
+                return _scopeDenied;
             const tasks = await convex.query("recurringTasks:list", {
                 assignedTo,
                 active,
@@ -2309,6 +2617,11 @@ export function registerTools(server, convex, oauthCtx) {
     // ── pause_recurring_task ────────────────────────────────────────────────────
     server.tool("pause_recurring_task", "Pause a recurring task — stops auto-creating tasks until resumed.", {
         taskId: z.string().describe("Recurring task ID"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Pause recurring task",
     }, async ({ taskId }) => {
         try {
             const result = await convex.mutation("recurringTasks:pause", {
@@ -2325,6 +2638,11 @@ export function registerTools(server, convex, oauthCtx) {
     // ── resume_recurring_task ───────────────────────────────────────────────────
     server.tool("resume_recurring_task", "Resume a paused recurring task — recalculates next run time.", {
         taskId: z.string().describe("Recurring task ID"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Resume recurring task",
     }, async ({ taskId }) => {
         try {
             const result = await convex.mutation("recurringTasks:resume", {
@@ -2341,6 +2659,11 @@ export function registerTools(server, convex, oauthCtx) {
     // ── delete_recurring_task ───────────────────────────────────────────────────
     server.tool("delete_recurring_task", "Permanently delete a recurring task template.", {
         taskId: z.string().describe("Recurring task ID"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Delete recurring task",
     }, async ({ taskId }) => {
         try {
             const result = await convex.mutation("recurringTasks:remove", {
@@ -2370,6 +2693,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("New cron expression (5-field)"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update recurring task",
     }, async ({ recurringTaskId, ...fields }) => {
         try {
             if (fields.assignedTo) {
@@ -2417,6 +2745,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Signed authorization document or reference"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create mandate",
     }, async ({ requestedBy, fulfilledBy, service, budget, spendingLimits, approvedCategories, mandateDocument, }) => {
         try {
             const fromDenied = guardFrom(requestedBy);
@@ -2453,6 +2786,11 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .describe("Convex document ID of the mandate to accept"),
         callerOrchestrator: creatorSchema.describe("Must be the fulfilledBy orchestrator or system"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Accept mandate",
     }, async ({ mandateId, callerOrchestrator }) => {
         try {
             const fromDenied = guardFrom(callerOrchestrator);
@@ -2488,6 +2826,11 @@ export function registerTools(server, convex, oauthCtx) {
             .array(z.string())
             .optional()
             .describe("Task IDs created to fulfill this mandate"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update mandate",
     }, async ({ mandateId, callerOrchestrator, status, tokensCost, linkedTaskIds, }) => {
         try {
             const fromDenied = guardFrom(callerOrchestrator);
@@ -2521,6 +2864,11 @@ export function registerTools(server, convex, oauthCtx) {
             .describe("Convex document ID of the mandate to settle"),
         callerOrchestrator: creatorSchema.describe("Must be the requestedBy orchestrator or system"),
         finalCost: z.number().describe("Final actual token cost to record"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Settle mandate",
     }, async ({ mandateId, callerOrchestrator, finalCost }) => {
         try {
             const fromDenied = guardFrom(callerOrchestrator);
@@ -2550,6 +2898,11 @@ export function registerTools(server, convex, oauthCtx) {
         proposedAmount: z
             .number()
             .describe("Proposed token spend amount to validate"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Validate mandate spending",
     }, async ({ mandateId, proposedAmount }) => {
         try {
             const result = await convex.query("mandates:validateSpending", {
@@ -2584,8 +2937,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum mandates to return (default 50)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List mandates",
     }, async ({ requestedBy, fulfilledBy, status, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_mandates");
+            if (_scopeDenied)
+                return _scopeDenied;
             const mandates = await convex.query("mandates:list", {
                 requestedBy,
                 fulfilledBy,
@@ -2633,6 +2994,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(10)
             .describe("Management fee percentage (default 10)"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create BU",
     }, async ({ name, description, purpose, domain, orchestratorId, status, businessModel, targetCustomers, services, pricing, revenueProjections, coreTeam, coreProcesses, dependencies, kpis, managementFee, }) => {
         try {
             const fromDenied = guardFrom(orchestratorId);
@@ -2693,6 +3059,11 @@ export function registerTools(server, convex, oauthCtx) {
         dependencies: flexArrayOptional.describe("New dependencies"),
         kpis: flexArrayOptional.describe("New KPIs"),
         managementFee: z.number().optional().describe("New management fee %"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update BU",
     }, async ({ buId, name, description, purpose, domain, orchestratorId, status, businessModel, targetCustomers, services, pricing, revenueProjections, coreTeam, coreProcesses, dependencies, kpis, managementFee, }) => {
         try {
             if (orchestratorId) {
@@ -2735,8 +3106,16 @@ export function registerTools(server, convex, oauthCtx) {
     // ── get_bu ──────────────────────────────────────────────────────────────────
     server.tool("get_bu", "Fetch a single business unit by its Convex document ID. Returns null if not found.", {
         buId: z.string().describe("Convex document ID of the business unit"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get BU",
     }, async ({ buId }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_bu");
+            if (_scopeDenied)
+                return _scopeDenied;
             const bu = await convex.query("businessUnits:get", {
                 buId: buId,
             });
@@ -2769,8 +3148,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum BUs to return (default 50)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List BUs",
     }, async ({ orchestratorId, status, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_bus");
+            if (_scopeDenied)
+                return _scopeDenied;
             const bus = await convex.query("businessUnits:list", {
                 orchestratorId,
                 status,
@@ -2794,6 +3181,11 @@ export function registerTools(server, convex, oauthCtx) {
         buId: z
             .string()
             .describe("Convex document ID of the business unit to delete"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Delete BU",
     }, async ({ buId }) => {
         try {
             const result = await convex.mutation("businessUnits:remove", {
@@ -2828,6 +3220,11 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(true)
             .describe("Whether this mapping is active (default true)"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Add repo mapping",
     }, async ({ repo, orchestrator, project, active }) => {
         try {
             const id = await convex.mutation("githubRepoMapping:add", {
@@ -2850,8 +3247,16 @@ export function registerTools(server, convex, oauthCtx) {
         }
     });
     // ── list_repo_mappings ──────────────────────────────────────────────────────
-    server.tool("list_repo_mappings", "List all GitHub repo → orchestrator mappings. Shows which repos are monitored and which orchestrator handles each.", {}, async () => {
-        try {
+    server.tool("list_repo_mappings", "List all GitHub repo → orchestrator mappings. Shows which repos are monitored and which orchestrator handles each.", {}, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List repo mappings",
+    }, async () => {
+        try {
+            const _scopeDenied = guardMasterOnly("list_repo_mappings");
+            if (_scopeDenied)
+                return _scopeDenied;
             const mappings = await convex.query("githubRepoMapping:list", {});
             return {
                 content: [
@@ -2871,6 +3276,11 @@ export function registerTools(server, convex, oauthCtx) {
         repo: z
             .string()
             .describe("Full repo name to remove — e.g. 'vantageos-agency/vantage-peers'"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Remove repo mapping",
     }, async ({ repo }) => {
         try {
             const result = await convex.mutation("githubRepoMapping:remove", {
@@ -2911,8 +3321,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum number of issues to return (default 50)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List issues",
     }, async ({ project, status, assignedTo, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_issues");
+            if (_scopeDenied)
+                return _scopeDenied;
             let results;
             if (assignedTo) {
                 results = await convex.query("issues:listByOrchestrator", {
@@ -2959,8 +3377,16 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .describe("Full repo name — e.g. 'myreeldream-ai/MyShortReel-beta'"),
         issueNumber: z.number().int().describe("GitHub issue number"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get issue",
     }, async ({ repo, issueNumber }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_issue");
+            if (_scopeDenied)
+                return _scopeDenied;
             const issue = await convex.query("issues:getByRepoNumber", {
                 repo,
                 issueNumber,
@@ -2987,6 +3413,11 @@ export function registerTools(server, convex, oauthCtx) {
         status: z
             .enum(["open", "in_progress", "fixed", "verified", "closed"])
             .describe("New status for the issue"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update issue status",
     }, async ({ repo, issueNumber, status }) => {
         try {
             await convex.mutation("issues:updateStatus", {
@@ -3017,6 +3448,11 @@ export function registerTools(server, convex, oauthCtx) {
         fixedBy: z
             .string()
             .describe("Who fixed it — orchestrator name or person"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Link commit to issue",
     }, async ({ repo, issueNumber, commitSha, fixedBy }) => {
         try {
             await convex.mutation("issues:linkCommit", {
@@ -3047,6 +3483,11 @@ export function registerTools(server, convex, oauthCtx) {
         verifiedBy: z
             .string()
             .describe("Who verified the fix — orchestrator name or person"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Verify issue",
     }, async ({ repo, issueNumber, verifiedBy }) => {
         try {
             await convex.mutation("issues:verify", {
@@ -3073,8 +3514,16 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Filter stats to a specific project — omit for all projects"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Issue statistics",
     }, async ({ project }) => {
         try {
+            const _scopeDenied = guardMasterOnly("issue_stats");
+            if (_scopeDenied)
+                return _scopeDenied;
             const stats = await convex.query("issues:getStats", {
                 project,
             });
@@ -3112,6 +3561,11 @@ export function registerTools(server, convex, oauthCtx) {
             .describe("The fix that worked — set later if not known yet"),
         files: flexArrayOptional.describe("Files involved in the fix"),
         linkedIssueIds: flexArrayOptional.describe("VantagePeers issue IDs linked to this pattern"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Create fix pattern",
     }, async ({ symptom, rootCause, tags, stack, sourceProject, createdBy, severity, validatedFix, files, linkedIssueIds, }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -3150,6 +3604,11 @@ export function registerTools(server, convex, oauthCtx) {
         why: z.string().describe("Why it worked or didn't — the reasoning"),
         createdBy: creatorSchema,
         commit: z.string().optional().describe("Git commit hash of this attempt"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Add fix attempt",
     }, async ({ patternId, description, worked, why, createdBy, commit }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -3180,6 +3639,11 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("validate_fix", "Set or update the validated fix on a pattern. Use after confirming a fix works.", {
         patternId: z.string().describe("ID of the fix pattern"),
         validatedFix: z.string().describe("Description of the validated fix"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Validate fix",
     }, async ({ patternId, validatedFix }) => {
         try {
             await convex.mutation("fixPatterns:validate", {
@@ -3209,8 +3673,16 @@ export function registerTools(server, convex, oauthCtx) {
             .int()
             .optional()
             .describe("Max results to return (default 10)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Search fix patterns",
     }, async ({ query, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("search_fix_patterns");
+            if (_scopeDenied)
+                return _scopeDenied;
             const results = await convex.action("search:searchFixPatterns", {
                 query,
                 limit,
@@ -3235,8 +3707,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .describe("Filter by source project — omit for all"),
         limit: z.number().int().optional().describe("Max results (default 50)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List fix patterns",
     }, async ({ project, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_fix_patterns");
+            if (_scopeDenied)
+                return _scopeDenied;
             if (project) {
                 const results = await convex.query("fixPatterns:listByProject", {
                     sourceProject: project,
@@ -3263,6 +3743,11 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("link_issue_to_pattern", "Link a VantagePeers issue to a fix pattern. Creates a bidirectional reference.", {
         patternId: z.string().describe("ID of the fix pattern"),
         issueId: z.string().describe("VantagePeers issue ID to link"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Link issue to fix pattern",
     }, async ({ patternId, issueId }) => {
         try {
             await convex.mutation("fixPatterns:linkIssue", {
@@ -3286,8 +3771,16 @@ export function registerTools(server, convex, oauthCtx) {
     server.tool("get_mission_template", "Fetch a mission template by name. Returns the template with all steps, or null if not found. " +
         "Use 'issue-resolution-v2' for the default Issue Resolution Protocol.", {
         name: z.string().describe("Template name — e.g. 'issue-resolution-v2'"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get mission template",
     }, async ({ name }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_mission_template");
+            if (_scopeDenied)
+                return _scopeDenied;
             const template = await convex.query("missionTemplates:getByName", { name });
             return {
                 content: [
@@ -3340,6 +3833,11 @@ export function registerTools(server, convex, oauthCtx) {
             .boolean()
             .optional()
             .describe("Mark as the default template for its type"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Update mission template",
     }, async ({ name, description, steps, createdBy, isDefault }) => {
         try {
             const fromDenied = guardFrom(createdBy);
@@ -3385,7 +3883,12 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Orchestrator making this call — used as createdBy on tasks. Defaults to 'system'."),
-    }, async ({ templateName, missionId, context, titlePrefix, callerOrchestrator }) => {
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Instantiate mission template",
+    }, async ({ templateName, missionId, context, titlePrefix, callerOrchestrator, }) => {
         try {
             const denied = guardMasterOnly("instantiate_template_into_mission");
             if (denied)
@@ -3429,6 +3932,11 @@ export function registerTools(server, convex, oauthCtx) {
         orchestrator: z
             .string()
             .describe("Orchestrator responsible for this deployment — e.g. 'sigma'"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Add deployment",
     }, async ({ name, deploymentUrl, deployKeyEnvVar, githubRepo, orchestrator, }) => {
         try {
             const id = await convex.mutation("errorMonitor:addDeployment", {
@@ -3456,6 +3964,11 @@ export function registerTools(server, convex, oauthCtx) {
         name: z
             .string()
             .describe("Name of the deployment to deactivate — e.g. 'your-deployment-123'"),
+    }, {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        title: "Remove deployment",
     }, async ({ name }) => {
         try {
             await convex.mutation("errorMonitor:removeDeployment", { name });
@@ -3487,8 +4000,16 @@ export function registerTools(server, convex, oauthCtx) {
             .optional()
             .default(50)
             .describe("Maximum number of errors to return (default 50)"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "List errors",
     }, async ({ deployment, limit }) => {
         try {
+            const _scopeDenied = guardMasterOnly("list_errors");
+            if (_scopeDenied)
+                return _scopeDenied;
             const errors = await convex.query("errorMonitor:listErrors", {
                 deployment,
                 limit: limit ?? 50,
@@ -3509,8 +4030,16 @@ export function registerTools(server, convex, oauthCtx) {
     // ── get_error ───────────────────────────────────────────────────────────────
     server.tool("get_error", "Fetch a single error log entry by its Convex document ID, including stack trace and issue linkage.", {
         errorId: z.string().describe("Convex document ID of the errorLogs entry"),
+    }, {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        title: "Get error",
     }, async ({ errorId }) => {
         try {
+            const _scopeDenied = guardMasterOnly("get_error");
+            if (_scopeDenied)
+                return _scopeDenied;
             const error = await convex.query("errorMonitor:getError", {
                 errorId: errorId,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantage-peers-mcp",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "MCP server for VantagePeers — shared memory, messaging, and task coordination for AI agent teams",
   "type": "module",
   "main": "./dist/server.js",