@productbrain/mcp 0.0.1-beta.46 → 0.0.1-beta.47

package/dist/{chunk-6O4EVIVI.js → chunk-FMEZXUP5.js}

@@ -4,6 +4,8 @@ import {
   checkEntryQuality,
   closeAgentSession,
   extractPreview,
+  failure,
+  failureResult,
   formatRubricCoaching,
   formatRubricVerdictSection,
   getAgentSessionId,
@@ -16,6 +18,8 @@ import {
   mcpCall,
   mcpMutation,
   mcpQuery,
+  notFoundResult,
+  parseOrFail,
   recordSessionActivity,
   registerSmartCaptureTools,
   requireActiveSession,
@@ -23,9 +27,14 @@ import {
   runWithToolContext,
   setSessionOriented,
   startAgentSession,
+  success,
+  successResult,
   trackWriteTool,
-  translateStaleToolNames
-} from "./chunk-5ZCY6NLZ.js";
+  translateStaleToolNames,
+  unknownAction,
+  validationResult,
+  withEnvelope
+} from "./chunk-FYFF4QKF.js";
 import {
   trackQualityCheck,
   trackQualityVerdict
@@ -94,7 +103,7 @@ function registerKnowledgeTools(server) {
       inputSchema: updateEntrySchema,
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async ({ entryId, name, status: rawStatus, workflowStatus: rawWorkflowStatus, data, order, canonicalKey, autoPublish, changeNote }) => {
+    withEnvelope(async ({ entryId, name, status: rawStatus, workflowStatus: rawWorkflowStatus, data, order, canonicalKey, autoPublish, changeNote }) => {
       requireWriteAccess();
       const PROMOTED_FIELDS = ["status", "workflowStatus", "name", "order", "canonicalKey"];
       const topLevelByField = { status: rawStatus, workflowStatus: rawWorkflowStatus, name, order, canonicalKey };
@@ -164,11 +173,16 @@ function registerKnowledgeTools(server) {
           responseLines.push(`\u26A0\uFE0F \`data.${field}\` detected \u2014 did you mean the top-level \`${field}\` parameter?`);
         }
       }
+      const summary = `Updated ${entryId} \u2014 ${versionMode}. Fields: ${fieldsProvided.join(", ") || "none"}.`;
+      const next = [
+        { tool: "entries", description: "View updated entry", parameters: { action: "get", entryId } },
+        { tool: "commit-entry", description: "Commit to Chain", parameters: { entryId } }
+      ];
       return {
         content: [{ type: "text", text: responseLines.join("\n") }],
-        structuredContent: { entryId: id, versionMode, fieldsProvided, confusedFields }
+        structuredContent: success(summary, { entryId: id, versionMode, fieldsProvided, confusedFields }, next)
       };
-    }
+    })
   );
   trackWriteTool(updateTool);
   server.registerTool(
@@ -179,10 +193,14 @@ function registerKnowledgeTools(server) {
       inputSchema: getHistorySchema,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async ({ entryId }) => {
+    withEnvelope(async ({ entryId }) => {
       const history = await mcpQuery("chain.listEntryHistory", { entryId });
       if (history.length === 0) {
-        return { content: [{ type: "text", text: `No history found for \`${entryId}\`.` }] };
+        return successResult(
+          `No history found for ${entryId}.`,
+          `No history events recorded for ${entryId}.`,
+          { entryId, eventCount: 0, events: [] }
+        );
       }
       const formatted = history.map((h) => {
         const date = new Date(h.timestamp).toISOString();
@@ -192,9 +210,13 @@ function registerKnowledgeTools(server) {
       return {
         content: [{ type: "text", text: `# History for \`${entryId}\` (${history.length} events)
 
-${formatted}` }]
+${formatted}` }],
+        structuredContent: success(
+          `Found ${history.length} history events for ${entryId}.`,
+          { entryId, eventCount: history.length, events: history }
+        )
       };
-    }
+    })
   );
   const commitTool = server.registerTool(
     "commit-entry",
@@ -204,14 +226,12 @@ ${formatted}` }]
       inputSchema: commitEntrySchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
-    async ({ entryId }) => {
+    withEnvelope(async ({ entryId }) => {
       requireWriteAccess();
-      const { runContradictionCheck } = await import("./smart-capture-QDF6MKRP.js");
+      const { runContradictionCheck } = await import("./smart-capture-XLBFE252.js");
       const entry = await mcpQuery("chain.getEntry", { entryId });
       if (!entry) {
-        return {
-          content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try search to find the right ID.` }]
-        };
+        return notFoundResult(entryId, `Entry '${entryId}' not found. Try search to find the right ID.`);
       }
       const descField = entry.data?.description ?? entry.data?.canonical ?? entry.data?.rationale ?? "";
       const warnings = await runContradictionCheck(entry.name, descField);
@@ -234,8 +254,9 @@ ${formatted}` }]
       const docId = result?._id ?? entry._id;
       await recordSessionActivity({ entryModified: docId });
       const wsCtx = await getWorkspaceContext();
+      const isProposal = result?.status === "proposal_created";
       let lines;
-      if (result?.status === "proposal_created") {
+      if (isProposal) {
         lines = [
           `# Proposal created: ${result.entryId ?? entryId}`,
           `**${result.name ?? entry.name}** \u2014 commit requires consent. A proposal was created instead of committing directly.`,
@@ -287,11 +308,29 @@ ${formatted}` }]
           }
         }
       }
+      const next = isProposal ? [
+        { tool: "entries", description: "View entry", parameters: { action: "get", entryId } }
+      ] : [
+        { tool: "graph", description: "Discover connections", parameters: { action: "suggest", entryId } },
+        { tool: "entries", description: "View committed entry", parameters: { action: "get", entryId } }
+      ];
+      const summary = isProposal ? `Proposal created for ${entryId} (${entry.name}). Awaiting consent.` : `Committed ${entryId} (${entry.name}) to the Chain.`;
       return {
         content: [{ type: "text", text: lines.join("\n") }],
-        structuredContent: coachingResult?.verdict ? { qualityVerdict: coachingResult.verdict, source: coachingResult.source ?? "heuristic" } : void 0
+        structuredContent: success(
+          summary,
+          {
+            entryId,
+            name: entry.name,
+            outcome: isProposal ? "proposal_created" : "committed",
+            qualityVerdict: coachingResult?.verdict ?? void 0,
+            source: coachingResult?.source ?? void 0,
+            contradictions: warnings.length
+          },
+          next
+        )
       };
-    }
+    })
   );
   trackWriteTool(commitTool);
 }
@@ -365,49 +404,41 @@ function registerEntriesTools(server) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
       _meta: { ui: { resourceUri: "ui://entries/entry-cards.html" } }
     },
-    async (args) => {
-      const parsed = entriesSchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(entriesSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, entryId, entryIds, collection, status, tag, label, query } = parsed.data;
       return runWithToolContext({ tool: "entries", action }, async () => {
         if (action === "get") {
           if (!entryId) {
-            return { content: [{ type: "text", text: "`entryId` is required when action is 'get'." }] };
+            return validationResult("entryId is required when action is 'get'.");
           }
           return handleGet(entryId);
         }
         if (action === "batch") {
           if (!entryIds || entryIds.length === 0) {
-            return { content: [{ type: "text", text: "`entryIds` is required when action is 'batch'." }] };
+            return validationResult("entryIds is required when action is 'batch'.");
           }
           return handleBatch(entryIds);
         }
         if (action === "search") {
           if (!query || query.length < 2) {
-            return { content: [{ type: "text", text: "`query` is required for search (min 2 characters)." }] };
+            return validationResult("query is required for search (min 2 characters).");
           }
           return handleSearch(server, query, collection, status);
         }
         if (action === "list") {
           return handleList(collection, status, tag, label);
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${ENTRIES_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, ENTRIES_ACTIONS);
       });
-    }
+    })
   );
 }
 async function handleGet(entryId) {
   const entry = await mcpQuery("chain.getEntry", { entryId });
   if (!entry) {
-    return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try search to find the right ID.` }] };
+    return notFoundResult(entryId, `Entry '${entryId}' not found. Try search to find the right ID.`);
   }
   const e = entry;
   const lines = [
@@ -447,7 +478,7 @@ async function handleGet(entryId) {
       lines.push(`- ${date}: ${h.event}${h.changedBy ? ` _(${h.changedBy})_` : ""}`);
     }
   }
-  const structuredContent = {
+  const entryData = {
     entryId: String(e.entryId ?? ""),
     name: String(e.name ?? ""),
     collection: String(e.canonicalKey ?? ""),
@@ -467,7 +498,14 @@ async function handleGet(entryId) {
   };
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent
+    structuredContent: success(
+      `Found ${entryId}: ${String(e.name)} [${String(e.canonicalKey ?? "")}].`,
+      entryData,
+      [
+        { tool: "graph", description: "Explore connections", parameters: { action: "suggest", entryId } },
+        { tool: "context", description: "Gather related context", parameters: { action: "gather", entryId } }
+      ]
+    )
   };
 }
 async function handleBatch(entryIds) {
@@ -530,9 +568,10 @@ async function handleBatch(entryIds) {
       ...entry.data && typeof entry.data === "object" ? { data: entry.data } : {}
     };
   });
+  const total = structuredEntries.length;
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: { entries: structuredEntries, total: structuredEntries.length }
+    structuredContent: success(`Fetched ${total} entries in batch.`, { entries: structuredEntries, total })
   };
 }
 async function handleList(collection, status, tag, label) {
@@ -550,7 +589,14 @@ async function handleList(collection, status, tag, label) {
     });
   }
   if (entries.length === 0) {
-    return { content: [{ type: "text", text: "No entries match the given filters." }] };
+    return {
+      content: [{ type: "text", text: "No entries match the given filters." }],
+      structuredContent: success(
+        "No entries match the given filters.",
+        { entries: [], total: 0 },
+        [{ tool: "collections", description: "List collections", parameters: { action: "list" } }]
+      )
+    };
   }
   const formatted = entries.map((e) => {
     const id = e.entryId ? `**${e.entryId}:** ` : "";
@@ -567,13 +613,14 @@ ${dataPreview}` : ""}`;
     status: String(e.status ?? ""),
     ...e.workflowStatus ? { workflowStatus: e.workflowStatus } : {}
   }));
+  const total = structuredEntries.length;
   return {
     content: [{ type: "text", text: `## List Result
 
 # Entries${scope} (${entries.length})
 
 ${formatted}` }],
-    structuredContent: { entries: structuredEntries, total: structuredEntries.length }
+    structuredContent: success(`Found ${total} entries${scope}.`, { entries: structuredEntries, total })
   };
 }
 async function handleSearch(server, query, collection, status) {
@@ -592,7 +639,12 @@ async function handleSearch(server, query, collection, status) {
       content: [{
         type: "text",
         text: `No results for "${query}"${scope}. Try a broader search or use \`collections action=list\` to see available data.`
-      }]
+      }],
+      structuredContent: success(
+        `No results for '${query}'${scope}.`,
+        { entries: [], total: 0, query },
+        [{ tool: "collections", description: "List collections", parameters: { action: "list" } }]
+      )
     };
   }
   const collMap = /* @__PURE__ */ new Map();
@@ -637,18 +689,19 @@ async function handleSearch(server, query, collection, status) {
     status: e.status,
     collectionName: e.collection
   }));
+  const total = structuredResults.length;
   return {
     content: [{ type: "text", text: `${header}
 
 ${formatted}
 
 ${footer}` }],
-    structuredContent: {
+    structuredContent: success(`Found ${total} entries matching '${query}'.`, {
       results: structuredResults,
       entries: entriesForView,
-      total: structuredResults.length,
+      total,
       query
-    }
+    })
   };
 }
 
@@ -696,12 +749,9 @@ function registerGraphTools(server) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
       _meta: { ui: { resourceUri: "ui://graph/constellation.html" } }
     },
-    async (args) => {
-      const parsed = graphSchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(graphSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, entryId, direction, limit, depth } = parsed.data;
       return runWithToolContext({ tool: "graph", action }, async () => {
         if (action === "find") {
@@ -710,24 +760,29 @@ function registerGraphTools(server) {
         if (action === "suggest") {
           return handleSuggest(entryId, limit ?? 10, depth ?? 2);
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${GRAPH_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, GRAPH_ACTIONS);
       });
-    }
+    })
   );
 }
 async function handleFind(entryId, direction) {
   const relations = await mcpQuery("chain.listEntryRelations", { entryId });
   if (relations.length === 0) {
-    return { content: [{ type: "text", text: `No relations found for \`${entryId}\`. Use relations action=create to create connections.` }] };
+    return {
+      content: [{ type: "text", text: `No relations found for \`${entryId}\`. Use relations action=create to create connections.` }],
+      structuredContent: success(
+        `No relations found for '${entryId}'.`,
+        { entryId, relations: [], nodes: [], edges: [], total: 0 },
+        [
+          { tool: "relations", description: "Create a relation", parameters: { action: "create", from: entryId } },
+          { tool: "graph", description: "Get suggestions", parameters: { action: "suggest", entryId } }
+        ]
+      )
+    };
   }
   const sourceEntry = await mcpQuery("chain.getEntry", { entryId });
   if (!sourceEntry) {
-    return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try entries action=search to find the right ID.` }] };
+    return notFoundResult(entryId, `Entry '${entryId}' not found. Try entries action=search to find the right ID.`);
   }
   const sourceInternalId = sourceEntry._id;
   const MAX_RELATIONS = 25;
@@ -801,13 +856,11 @@ async function handleFind(entryId, direction) {
   }));
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      entryId,
-      relations: structuredRelations,
-      nodes,
-      edges,
-      total: relations.length
-    }
+    structuredContent: success(
+      `Found ${relations.length} relations for ${entryId}.`,
+      { entryId, relations: structuredRelations, nodes, edges, total: relations.length },
+      [{ tool: "entries", description: "View entry details", parameters: { action: "get", entryId } }]
+    )
   };
 }
 async function handleSuggest(entryId, limit, depth) {
@@ -817,7 +870,13 @@ async function handleSuggest(entryId, limit, depth) {
     limit
   });
   if (!result?.suggestions || result.suggestions.length === 0) {
-    return { content: [{ type: "text", text: `No suggestions found for \`${entryId}\` \u2014 it may already be well-connected, or no similar entries exist.` }] };
+    return failureResult(
+      `No suggestions found for '${entryId}' \u2014 it may already be well-connected, or no similar entries exist.`,
+      "NOT_FOUND",
+      `No suggestions found for '${entryId}'.`,
+      "Entry may already be well-connected.",
+      [{ tool: "graph", description: "Check existing relations", parameters: { action: "find", entryId } }]
+    );
   }
   const resolved = result.resolvedEntry;
   const resolvedLabel = resolved ? `\`${resolved.entryId ?? resolved.name}\` (${resolved.name})` : `\`${entryId}\``;
@@ -885,13 +944,11 @@ async function handleSuggest(entryId, limit, depth) {
   }));
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      entryId: sourceId,
-      suggestions: structuredSuggestions,
-      nodes,
-      edges,
-      total: suggestions.length
-    }
+    structuredContent: success(
+      `Found ${suggestions.length} link suggestions for ${resolvedLabel}.`,
+      { entryId: sourceId, suggestions: structuredSuggestions, nodes, edges, total: suggestions.length },
+      [{ tool: "relations", description: "Create links", parameters: { action: "batch-create" } }]
+    )
   };
 }
 
@@ -921,40 +978,32 @@ function registerRelationsTools(server) {
       inputSchema: relationsSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async (args) => {
-      const parsed = relationsSchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(relationsSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, from, to, type, score, relations } = parsed.data;
       return runWithToolContext({ tool: "relations", action }, async () => {
         if (action === "create") {
           if (!from || !to || !type) {
-            return { content: [{ type: "text", text: "`from`, `to`, and `type` are required when action is 'create'." }] };
+            return validationResult("from, to, and type are required when action is 'create'.");
           }
           return handleCreate(from, to, type, score);
         }
         if (action === "batch-create") {
           if (!relations || relations.length === 0) {
-            return { content: [{ type: "text", text: "`relations` is required when action is 'batch-create'." }] };
+            return validationResult("relations is required when action is 'batch-create'.");
           }
           return handleBatchCreate(relations);
         }
         if (action === "dismiss") {
           if (!from || !to) {
-            return { content: [{ type: "text", text: "`from` and `to` are required when action is 'dismiss'." }] };
+            return validationResult("from and to are required when action is 'dismiss'.");
           }
           return handleDismiss(from, to, type ?? "related_to", score);
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${RELATIONS_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, RELATIONS_ACTIONS);
       });
-    }
+    })
   );
   trackWriteTool(tool);
 }
@@ -983,14 +1032,24 @@ ${result.message ?? "Governs relation requires async consent. A proposal was cre
 **Workspace:** ${wsCtx.workspaceSlug} (${wsCtx.workspaceId})
 
 The relation was **not applied** \u2014 it will be created when the proposal is approved.`
-      }]
+      }],
+      structuredContent: success(
+        `Proposal created for ${from} \u2192 ${to} (${type}). Awaiting consent.`,
+        { status: "proposal_created", from, to, type, proposalId: result.proposalId },
+        [{ tool: "entries", description: "Check proposal", parameters: { action: "get", entryId: result.proposalId } }]
+      )
     };
   }
   return {
     content: [{ type: "text", text: `# Relation Created
 
 **${from}** \u2014[${type}]\u2192 **${to}**
-**Workspace:** ${wsCtx.workspaceSlug} (${wsCtx.workspaceId})` }]
+**Workspace:** ${wsCtx.workspaceSlug} (${wsCtx.workspaceId})` }],
+    structuredContent: success(
+      `Created relation ${from} \u2192 ${to} (${type}).`,
+      { status: "created", from, to, type },
+      [{ tool: "graph", description: "See connections", parameters: { action: "find", entryId: from } }]
+    )
   };
 }
 async function handleBatchCreate(relations) {
@@ -1043,17 +1102,25 @@ async function handleBatchCreate(relations) {
       lines.push(`- **${r.from}** \u2192 **${r.to}** (${r.type}): _${r.error}_`);
     }
   }
-  return { content: [{ type: "text", text: lines.join("\n") }] };
+  const next = failed.length === 0 ? [{ tool: "graph", description: "Check connections", parameters: { action: "find", entryId: relations[0].from } }] : [];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: success(
+      `Batch: ${created.length} created, ${proposals.length} proposals, ${failed.length} failed of ${relations.length}.`,
+      { created: created.length, proposals: proposals.length, failed: failed.length, total: relations.length, results },
+      next.length ? next : void 0
+    )
+  };
 }
 async function handleDismiss(from, to, type, score) {
   requireWriteAccess();
   const fromEntry = await mcpQuery("chain.getEntry", { entryId: from });
   if (!fromEntry) {
-    return { content: [{ type: "text", text: `Entry \`${from}\` not found.` }] };
+    return notFoundResult(from);
   }
   const toEntry = await mcpQuery("chain.getEntry", { entryId: to });
   if (!toEntry) {
-    return { content: [{ type: "text", text: `Entry \`${to}\` not found.` }] };
+    return notFoundResult(to);
   }
   await mcpMutation("chain.dismissSuggestion", {
     fromEntryId: fromEntry._id,
@@ -1061,12 +1128,11 @@ async function handleDismiss(from, to, type, score) {
     recommendedType: type,
     score: score ?? 0
   });
-  return {
-    content: [{
-      type: "text",
-      text: `Dismissed suggestion: ${from} \u2192 ${to} (${type}). Feedback recorded for scoring improvements.`
-    }]
-  };
+  return successResult(
+    `Dismissed suggestion: ${from} \u2192 ${to} (${type}). Feedback recorded for scoring improvements.`,
+    `Dismissed suggestion ${from} \u2192 ${to} (${type}). Feedback recorded.`,
+    { from, to, type }
+  );
 }
 
 // src/tools/context.ts
@@ -1099,12 +1165,9 @@ function registerContextTools(server) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
       _meta: { ui: { resourceUri: "ui://graph/constellation.html" } }
     },
-    async (args) => {
-      const parsed = contextSchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(contextSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, entryId, mapEntryId, task, mode, maxHops, maxResults } = parsed.data;
       return runWithToolContext({ tool: "context", action }, async () => {
         if (action === "gather") {
@@ -1115,23 +1178,18 @@ function registerContextTools(server) {
         }
         if (action === "build") {
           if (!entryId) {
-            return { content: [{ type: "text", text: "`entryId` is required when action is 'build'." }] };
+            return validationResult("entryId is required when action is 'build'.");
           }
           return handleBuild(server, entryId, maxHops ?? 2);
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${CONTEXT_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, CONTEXT_ACTIONS);
       });
-    }
+    })
   );
 }
 async function handleGather(server, entryId, task, mode, maxHops, maxResults) {
   if (!entryId && !task) {
-    return { content: [{ type: "text", text: "Provide either `entryId` (graph traversal) or `task` (auto-load context for a task)." }] };
+    return validationResult("Provide either entryId (graph traversal) or task (auto-load context).");
   }
   if (entryId && mode === "graph") {
     await server.sendLoggingMessage({
@@ -1144,7 +1202,7 @@ async function handleGather(server, entryId, task, mode, maxHops, maxResults) {
       maxHops
     });
     if (!result2?.root) {
-      return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try search to find the right ID.` }] };
+      return notFoundResult(entryId, `Entry '${entryId}' not found. Try search to find the right ID.`);
     }
     if (result2.context.length === 0) {
       return {
@@ -1155,7 +1213,12 @@ async function handleGather(server, entryId, task, mode, maxHops, maxResults) {
 _No relations found._ This entry is not yet connected to the knowledge graph.
 
 Use \`graph action=suggest\` to discover potential connections.`
-        }]
+        }],
+        structuredContent: success(
+          `No relations found for ${result2.root.entryId}. Entry not yet connected.`,
+          { root: result2.root, context: [], totalFound: 0 },
+          [{ tool: "graph", description: "Discover connections", parameters: { action: "suggest", entryId: result2.root.entryId } }]
+        )
       };
     }
     const byCollection2 = /* @__PURE__ */ new Map();
@@ -1201,7 +1264,10 @@ Use \`graph action=suggest\` to discover potential connections.`
     }));
     return {
       content: [{ type: "text", text: lines2.join("\n") }],
-      structuredContent: { nodes: nodes2, edges: edges2 }
+      structuredContent: success(
+        `Gathered ${result2.totalFound} related entries for ${result2.root.entryId} (${result2.hopsTraversed} hops, graph mode).`,
+        { nodes: nodes2, edges: edges2, root: result2.root, totalFound: result2.totalFound }
+      )
     };
   }
   if (task && !entryId) {
@@ -1226,7 +1292,13 @@ Use \`graph action=suggest\` to discover potential connections.`
 No context found for this task. The chain may not cover this area yet.
 
 _Consider capturing domain knowledge discovered during this task via \`capture\`._`
-        }]
+        }],
+        structuredContent: failure(
+          "NOT_FOUND",
+          "No context found for this task.",
+          "The chain may not cover this area. Capture domain knowledge via capture.",
+          [{ tool: "capture", description: "Capture knowledge", parameters: {} }]
+        )
       };
     }
     const byCollection2 = /* @__PURE__ */ new Map();
@@ -1262,7 +1334,10 @@ _Consider capturing domain knowledge discovered during this task via \`capture\`
     }));
     return {
       content: [{ type: "text", text: lines2.join("\n") }],
-      structuredContent: { entries: taskEntries }
+      structuredContent: success(
+        `Loaded ${result2.totalFound} entries for task (${result2.confidence} confidence).`,
+        { entries: taskEntries, totalFound: result2.totalFound, confidence: result2.confidence }
+      )
     };
   }
   await server.sendLoggingMessage({
@@ -1272,7 +1347,7 @@ _Consider capturing domain knowledge discovered during this task via \`capture\`
   });
   const result = await mcpQuery("chain.gatherContext", { entryId, maxHops });
   if (!result?.root) {
-    return { content: [{ type: "text", text: `Entry \`${entryId}\` not found. Try search to find the right ID.` }] };
+    return notFoundResult(entryId, `Entry '${entryId}' not found. Try search to find the right ID.`);
   }
   if (result.related.length === 0) {
     return {
@@ -1283,7 +1358,12 @@ _Consider capturing domain knowledge discovered during this task via \`capture\`
 _No relations found._ This entry is not yet connected to the knowledge graph.
 
 Use \`graph action=suggest\` to discover potential connections, or \`relations action=create\` to link manually.`
-      }]
+      }],
+      structuredContent: success(
+        `No relations found for ${result.root.entryId}. Entry not yet connected.`,
+        { root: result.root, related: [], totalRelations: 0 },
+        [{ tool: "graph", description: "Discover connections", parameters: { action: "suggest", entryId: result.root.entryId } }]
+      )
     };
   }
   const byCollection = /* @__PURE__ */ new Map();
@@ -1323,7 +1403,10 @@ Use \`graph action=suggest\` to discover potential connections, or \`relations a
   }));
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: { nodes, edges }
+    structuredContent: success(
+      `Gathered ${result.totalRelations} related entries for ${result.root.entryId} (${result.hopsTraversed} hops).`,
+      { nodes, edges, root: result.root, totalRelations: result.totalRelations }
+    )
   };
 }
 async function handleJourneyGather(server, mapEntryId, maxHops, maxResults) {
@@ -1338,7 +1421,11 @@ async function handleJourneyGather(server, mapEntryId, maxHops, maxResults) {
     maxResults
   });
   if (!result) {
-    return { content: [{ type: "text", text: `Journey map \`${mapEntryId}\` not found or has no slot data. Verify the map entry ID.` }] };
+    return notFoundResult(
+      mapEntryId,
+      `Journey map '${mapEntryId}' not found or has no slot data. Verify the map entry ID.`,
+      "Verify the map entry ID is correct."
+    );
   }
   if (result.stages.length === 0 || result.seedCount === 0) {
     return {
@@ -1349,7 +1436,11 @@ async function handleJourneyGather(server, mapEntryId, maxHops, maxResults) {
 _No ingredients found in this journey map._
 
 Add journey steps via MCP: \`map-slot action=add mapEntryId="${mapEntryId}" slotId="..." ingredientEntryId="..."\``
-      }]
+      }],
+      structuredContent: success(
+        `Journey map ${result.map.name} has no ingredients.`,
+        { map: result.map, stages: result.stages, context: [] }
+      )
     };
   }
   const lines = [
@@ -1389,15 +1480,18 @@ Add journey steps via MCP: \`map-slot action=add mapEntryId="${mapEntryId}" slot
   lines.push(`_Use \`entries action=get\` for full details. Link governance to steps: \`relations action=create\`._`);
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      map: result.map,
-      stages: result.stages,
-      context: result.context.map((e) => ({
-        entryId: e.entryId ?? "",
-        name: e.name,
-        collectionName: e.collectionName
-      }))
-    }
+    structuredContent: success(
+      `Journey context for ${result.map.name}: ${result.totalFound} related entries across ${result.stages.length} stages.`,
+      {
+        map: result.map,
+        stages: result.stages,
+        context: result.context.map((e) => ({
+          entryId: e.entryId ?? "",
+          name: e.name,
+          collectionName: e.collectionName
+        }))
+      }
+    )
   };
 }
 async function handleBuild(server, entryId, maxHops) {
@@ -1467,7 +1561,13 @@ async function handleBuild(server, entryId, maxHops) {
     lines.push("");
     lines.push("_Context was truncated (limits: 50 related, 20 rules, 30 glossary). Use entries action=get for full details._");
   }
-  return { content: [{ type: "text", text: annotateStaleNames(lines.join("\n")) }] };
+  return {
+    content: [{ type: "text", text: annotateStaleNames(lines.join("\n")) }],
+    structuredContent: success(
+      `Build context for ${entry.name}: ${relatedCount} related, ${businessRules.length} rules, ${glossaryTerms.length} terms.`,
+      { entry, relatedByCollection, businessRulesCount: businessRules.length, glossaryTermsCount: glossaryTerms.length, contextTruncated }
+    )
+  };
 }
 
 // src/tools/collections.ts
@@ -1502,12 +1602,9 @@ function registerCollectionsTools(server) {
       inputSchema: collectionsSchema,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     },
-    async (args) => {
-      const parsed = collectionsSchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(collectionsSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, slug, name, description, purpose, icon, navGroup, fields } = parsed.data;
       return runWithToolContext({ tool: "collections", action }, async () => {
         if (action === "list") {
@@ -1515,39 +1612,34 @@ function registerCollectionsTools(server) {
         }
         if (action === "create") {
           if (!slug || !name || !fields || fields.length === 0) {
-            return {
-              content: [{
-                type: "text",
-                text: "`slug`, `name`, and `fields` are required when action is 'create'."
-              }]
-            };
+            return validationResult("slug, name, and fields are required when action is 'create'.");
           }
           return handleCreate2(slug, name, description, purpose, icon, navGroup ?? "collections", fields);
         }
         if (action === "update") {
           if (!slug) {
-            return { content: [{ type: "text", text: "`slug` is required when action is 'update'." }] };
+            return validationResult("slug is required when action is 'update'.");
           }
           if (!name && !description && !purpose && !icon && !navGroup && !fields) {
-            return { content: [{ type: "text", text: "Provide at least one field to update (name, description, purpose, icon, navGroup, or fields)." }] };
+            return validationResult("Provide at least one field to update (name, description, purpose, icon, navGroup, or fields).");
           }
           return handleUpdate(slug, name, description, purpose, icon, navGroup, fields);
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${COLLECTIONS_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, COLLECTIONS_ACTIONS);
       });
-    }
+    })
   );
   trackWriteTool(tool);
 }
 async function handleList2() {
   const collections = await mcpQuery("chain.listCollections");
   if (collections.length === 0) {
-    return { content: [{ type: "text", text: "No collections found in this workspace." }] };
+    return successResult(
+      "No collections found in this workspace.",
+      "No collections found yet.",
+      { collections: [], total: 0 },
+      [{ tool: "collections", description: "Create collection", parameters: { action: "create" } }]
+    );
   }
   const formatted = collections.map((c) => {
     const fieldList = c.fields.map((f) => `  - \`${f.key}\` (${f.type}${f.required ? ", required" : ""}${f.searchable ? ", searchable" : ""})`).join("\n");
@@ -1565,7 +1657,19 @@ ${fieldList}`;
   return {
     content: [{ type: "text", text: `# Knowledge Collections (${collections.length})
 
-${formatted}` }]
+${formatted}` }],
+    structuredContent: success(
+      `Found ${collections.length} collections.`,
+      {
+        collections: collections.map((c) => ({
+          slug: c.slug,
+          name: c.name,
+          description: c.description,
+          fieldCount: c.fields.length
+        })),
+        total: collections.length
+      }
+    )
   };
 }
 async function handleCreate2(slug, name, description, purpose, icon, navGroup, fields) {
@@ -1596,17 +1700,23 @@ async function handleCreate2(slug, name, description, purpose, icon, navGroup, f
 ${fieldList}
 
 You can now capture entries: \`capture collection="${slug}" name="..." description="..."\``
-      }]
+      }],
+      structuredContent: success(
+        `Created collection '${name}' (${slug}) with ${fields.length} fields.`,
+        { slug, name, description, purpose, navGroup, fieldCount: fields.length },
+        [{ tool: "capture", description: "Capture an entry", parameters: { collection: slug } }]
+      )
     };
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     if (msg.includes("already exists")) {
-      return {
-        content: [{
-          type: "text",
-          text: `Collection \`${slug}\` already exists. Use \`collections action=update slug="${slug}"\` to modify it, or choose a different slug.`
-        }]
-      };
+      return failureResult(
+        `Collection '${slug}' already exists. Use collections action=update to modify it, or choose a different slug.`,
+        "DUPLICATE",
+        `Collection '${slug}' already exists.`,
+        "Use collections action=update to modify it.",
+        [{ tool: "collections", description: "Update collection", parameters: { action: "update", slug } }]
+      );
     }
     throw error;
   }
@@ -1631,7 +1741,11 @@ async function handleUpdate(slug, name, description, purpose, icon, navGroup, fi
 Changed: ${changes || "no changes"}.
 
 Use \`collections action=list\` to verify the result.`
-    }]
+    }],
+    structuredContent: success(
+      `Updated collection '${slug}'. Changed: ${changes || "no changes"}.`,
+      { slug, changes }
+    )
   };
 }
 
@@ -1657,11 +1771,16 @@ function registerLabelTools(server) {
       inputSchema: labelsSchema,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     },
-    async ({ action, slug, name, color, description, parentSlug, isGroup, order, entryId }) => {
+    withEnvelope(async ({ action, slug, name, color, description, parentSlug, isGroup, order, entryId }) => {
       if (action === "list") {
         const labels = await mcpQuery("chain.listLabels");
         if (labels.length === 0) {
-          return { content: [{ type: "text", text: "No labels defined in this workspace yet." }] };
+          return successResult(
+            "No labels defined in this workspace yet.",
+            "No labels defined yet.",
+            { labels: [], total: 0 },
+            [{ tool: "labels", description: "Create a label", parameters: { action: "create" } }]
+          );
         }
         const groups = labels.filter((l) => l.isGroup);
         const ungrouped = labels.filter((l) => !l.isGroup && !l.parentId);
@@ -1683,54 +1802,74 @@ function registerLabelTools(server) {
             lines.push(`- \`${label.slug}\` ${label.name}${c}${label.description ? ` \u2014 _${label.description}_` : ""}`);
           }
         }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          structuredContent: success(
+            `Found ${labels.length} labels in ${groups.length} groups.`,
+            { labels, total: labels.length }
+          )
+        };
       }
       if (!slug) {
-        return { content: [{ type: "text", text: "A `slug` is required for this action." }] };
+        return validationResult("A slug is required for this action.");
       }
       if (action === "create") {
         if (!name) {
-          return { content: [{ type: "text", text: "Cannot create a label without a name." }] };
+          return validationResult("Cannot create a label without a name.");
         }
         let parentId;
         if (parentSlug) {
           const labels = await mcpQuery("chain.listLabels");
           const parent = labels.find((l) => l.slug === parentSlug);
           if (!parent) {
-            return { content: [{ type: "text", text: `Parent label \`${parentSlug}\` not found. Use \`labels action=list\` to see available groups.` }] };
+            return failureResult(
+              `Parent label '${parentSlug}' not found. Use labels action=list to see available groups.`,
+              "NOT_FOUND",
+              `Parent label '${parentSlug}' not found.`,
+              "Use labels action=list to see available groups.",
+              [{ tool: "labels", description: "List labels", parameters: { action: "list" } }]
+            );
           }
           parentId = parent._id;
         }
         await mcpMutation("chain.createLabel", { slug, name, color, description, parentId, isGroup, order });
-        return { content: [{ type: "text", text: `# Label Created
-
-**${name}** (\`${slug}\`)` }] };
+        return successResult(
+          `Label '${name}' (${slug}) created.`,
+          `Created label '${name}' (${slug}).`,
+          { slug, name, color, parentSlug },
+          [{ tool: "labels", description: "List labels", parameters: { action: "list" } }]
+        );
       }
       if (action === "update") {
         await mcpMutation("chain.updateLabel", { slug, name, color, description, isGroup, order });
-        return { content: [{ type: "text", text: `# Label Updated
-
-\`${slug}\` has been updated.` }] };
+        return successResult(
+          `Label '${slug}' updated.`,
+          `Updated label '${slug}'.`,
+          { slug },
+          [{ tool: "labels", description: "List labels", parameters: { action: "list" } }]
+        );
       }
       if (action === "delete") {
         await mcpMutation("chain.deleteLabel", { slug });
-        return { content: [{ type: "text", text: `# Label Deleted
-
-\`${slug}\` removed from all entries and deleted.` }] };
+        return successResult(
+          `Label '${slug}' removed from all entries and deleted.`,
+          `Deleted label '${slug}'.`,
+          { slug }
+        );
       }
       if (action === "apply" || action === "remove") {
         if (!entryId) {
-          return { content: [{ type: "text", text: "An `entryId` is required for apply/remove actions." }] };
+          return validationResult("An entryId is required for apply/remove actions.");
         }
         if (action === "apply") {
           await mcpMutation("chain.applyLabel", { entryId, labelSlug: slug });
-          return { content: [{ type: "text", text: `Label \`${slug}\` applied to **${entryId}**.` }] };
+          return successResult(`Label '${slug}' applied to ${entryId}.`, `Applied label '${slug}' to ${entryId}.`, { slug, entryId });
         }
         await mcpMutation("chain.removeLabel", { entryId, labelSlug: slug });
-        return { content: [{ type: "text", text: `Label \`${slug}\` removed from **${entryId}**.` }] };
+        return successResult(`Label '${slug}' removed from ${entryId}.`, `Removed label '${slug}' from ${entryId}.`, { slug, entryId });
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return validationResult("Unknown action.");
+    })
   );
   trackWriteTool(tool);
 }
@@ -1792,17 +1931,17 @@ async function suggestLinksForEntries(entries) {
 async function runWrapupReview() {
   const sessionId = getAgentSessionId();
   if (!sessionId) {
-    return { text: "No active agent session. Call `session action=start` first.", data: null, suggestions: [] };
+    return { text: "No active agent session. Call `session action=start` first.", data: null, suggestions: [], failureCode: "SESSION_REQUIRED" };
   }
   if (getApiKeyScope() === "read") {
-    return { text: "Read-only session \u2014 nothing to review.", data: null, suggestions: [] };
+    return { text: "Read-only session \u2014 nothing to review.", data: null, suggestions: [], failureCode: "READONLY_SCOPE" };
   }
   const data = await mcpCall("agent.getSessionWrapup", { sessionId });
   if (data.wrapupCompletedAt) {
-    return { text: "Wrapup already completed this session.", data, suggestions: [] };
+    return { text: "Wrapup already completed this session.", data, suggestions: [], failureCode: "ALREADY_COMPLETED" };
   }
   if (data.drafts.length === 0 && data.committed.length === 0) {
-    return { text: "Empty session \u2014 no entries to review.", data, suggestions: [] };
+    return { text: "Empty session \u2014 no entries to review.", data, suggestions: [], failureCode: "NOT_FOUND" };
   }
   const lines = [];
   lines.push(
@@ -1922,50 +2061,62 @@ function registerWrapupTools(server) {
   let lastReviewData = null;
   let lastReviewSuggestions = [];
   const wrapupHandler = async ({ action }) => {
-    try {
-      if (action === "commit-all") {
-        const sessionId = getAgentSessionId();
-        if (!sessionId) {
-          return { content: [{ type: "text", text: "No active agent session." }] };
-        }
-        const data2 = lastReviewData ?? await mcpCall("agent.getSessionWrapup", { sessionId });
-        if (data2.drafts.length === 0) {
-          return { content: [{ type: "text", text: "No uncommitted drafts to commit." }] };
-        }
-        const result = await runWrapupCommitAll(data2, lastReviewSuggestions);
-        lastReviewData = null;
-        lastReviewSuggestions = [];
-        return { content: [{ type: "text", text: result }] };
+    if (action === "commit-all") {
+      const sessionId = getAgentSessionId();
+      if (!sessionId) {
+        return failureResult(
+          "No active agent session.",
+          "SESSION_REQUIRED",
+          "No active agent session.",
+          "Start a session first.",
+          [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
+        );
+      }
+      const data2 = lastReviewData ?? await mcpCall("agent.getSessionWrapup", { sessionId });
+      if (data2.drafts.length === 0) {
+        return failureResult("No uncommitted drafts to commit.", "NOT_FOUND", "No uncommitted drafts to commit.", "Nothing to commit.");
       }
-      const { text, data, suggestions } = await runWrapupReview();
-      lastReviewData = data;
-      lastReviewSuggestions = suggestions;
-      const fullText = data && (data.drafts.length > 0 || data.committed.length > 0) ? `## Session Wrapup
+      const result = await runWrapupCommitAll(data2, lastReviewSuggestions);
+      lastReviewData = null;
+      lastReviewSuggestions = [];
+      return successResult(result, "Wrapup complete. Committed drafts and created links.", { committed: true });
+    }
+    const { text, data, suggestions, failureCode } = await runWrapupReview();
+    lastReviewData = data;
+    lastReviewSuggestions = suggestions;
+    const fullText = data && (data.drafts.length > 0 || data.committed.length > 0) ? `## Session Wrapup
 
 ${text}` : text;
-      return { content: [{ type: "text", text: fullText }] };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: [{ type: "text", text: `Wrapup failed: ${msg}` }], isError: true };
-    }
+    if (failureCode) {
+      return failureResult(fullText, failureCode, text);
+    }
+    const next = data.drafts.length > 0 ? [{ tool: "session-wrapup", description: "Commit all drafts", parameters: { action: "commit-all" } }] : void 0;
+    return successResult(
+      fullText,
+      `Session review: ${data.drafts.length} uncommitted, ${data.committed.length} committed, ${suggestions.length} link suggestions.`,
+      {
+        drafts: data.drafts.length,
+        committed: data.committed.length,
+        uncommitted: data.summary.uncommitted,
+        suggestedLinks: suggestions.length
+      },
+      next
+    );
   };
   const tool = server.registerTool("session-wrapup", {
     title: "Session Wrapup",
     description: WRAPUP_TOOL_DESCRIPTION + " Also known as: wrapup, finish.",
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     inputSchema: wrapupSchema
-  }, async (args) => {
-    const parsed = wrapupSchema.safeParse(args);
-    if (!parsed.success) {
-      const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-      return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-    }
+  }, withEnvelope(async (args) => {
+    const parsed = parseOrFail(wrapupSchema, args);
+    if (!parsed.ok) return parsed.result;
     const act = parsed.data.action ?? "review";
     return runWithToolContext(
       { tool: "session-wrapup", action: act },
       () => wrapupHandler({ action: act })
     );
-  });
+  }));
   trackWriteTool(tool);
 }
 
@@ -1985,12 +2136,9 @@ function registerSessionTools(server) {
       inputSchema: sessionSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async (args) => {
-      const parsed = sessionSchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(sessionSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action } = parsed.data;
       return runWithToolContext({ tool: "session", action }, async () => {
         if (action === "start") {
@@ -2002,141 +2150,159 @@ function registerSessionTools(server) {
         if (action === "status") {
           return handleStatus();
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${SESSION_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, SESSION_ACTIONS);
       });
-    }
+    })
   );
 }
 async function handleStart() {
-  try {
-    const result = await startAgentSession();
-    const lines = [];
-    if (result.superseded) {
-      lines.push(
-        `Previous session superseded. Session ${result.superseded.previousSessionId} (started ${result.superseded.startedAt}, initiated by ${result.superseded.initiatedBy}) was closed.`,
-        ""
-      );
-    }
+  const result = await startAgentSession();
+  const lines = [];
+  if (result.superseded) {
     lines.push(
-      `Session ${result.sessionId} active. Initiated by ${result.initiatedBy}. Workspace ${result.workspaceName}. Scope: ${result.toolsScope}. Write tools available after orient.`
+      `Previous session superseded. Session ${result.superseded.previousSessionId} (started ${result.superseded.startedAt}, initiated by ${result.superseded.initiatedBy}) was closed.`,
+      ""
     );
-    return { content: [{ type: "text", text: lines.join("\n") }] };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: "text", text: `Failed to start agent session: ${msg}` }],
-      isError: true
-    };
   }
+  lines.push(
+    `Session ${result.sessionId} active. Initiated by ${result.initiatedBy}. Workspace ${result.workspaceName}. Scope: ${result.toolsScope}. Write tools available after orient.`
+  );
+  const summary = `Session ${result.sessionId} active. Workspace ${result.workspaceName}. Write tools available after orient.`;
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: success(summary, {
+      sessionId: result.sessionId,
+      initiatedBy: result.initiatedBy,
+      workspaceName: result.workspaceName,
+      toolsScope: result.toolsScope,
+      superseded: !!result.superseded
+    }, [{ tool: "orient", description: "Orient session", parameters: {} }])
+  };
 }
 async function handleClose() {
-  try {
-    const sessionId = getAgentSessionId();
-    if (!sessionId) {
-      return {
-        content: [{ type: "text", text: "No active agent session to close." }]
-      };
-    }
-    const session = await mcpCall("agent.getSession", {
-      sessionId
-    });
-    let wrapupNudge = "";
-    if (session && !session.wrapupCompletedAt) {
-      try {
-        const { text, data } = await runWrapupReview();
-        if (data && data.drafts.length > 0) {
-          wrapupNudge = [
-            "## Session Wrapup",
-            "",
-            text,
-            "",
-            `> **${data.drafts.length} uncommitted draft(s) remain.** Run \`session-wrapup\` with action \`commit-all\` before closing next time.`,
-            "",
-            "---",
-            ""
-          ].join("\n");
-        }
-      } catch {
+  const sessionId = getAgentSessionId();
+  if (!sessionId) {
+    return failureResult(
+      "No active agent session to close.",
+      "SESSION_REQUIRED",
+      "No active agent session to close.",
+      "Start a session first.",
+      [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
+    );
+  }
+  const session = await mcpCall("agent.getSession", {
+    sessionId
+  });
+  let wrapupNudge = "";
+  if (session && !session.wrapupCompletedAt) {
+    try {
+      const { text, data } = await runWrapupReview();
+      if (data && data.drafts.length > 0) {
+        wrapupNudge = [
+          "## Session Wrapup",
+          "",
+          text,
+          "",
+          `> **${data.drafts.length} uncommitted draft(s) remain.** Run \`session-wrapup\` with action \`commit-all\` before closing next time.`,
+          "",
+          "---",
+          ""
+        ].join("\n");
       }
+    } catch {
     }
-    await closeAgentSession();
-    const lines = [
-      `Session ${sessionId} closed.`,
-      ""
-    ];
-    if (session) {
-      const created = session.entriesCreated?.length ?? 0;
-      const modified = session.entriesModified?.length ?? 0;
-      const relations = session.relationsCreated ?? 0;
-      const gates = session.gateFailures ?? 0;
-      const warnings = session.contradictionWarnings ?? 0;
-      lines.push(
-        `| Metric | Count |`,
-        `|--------|-------|`,
-        `| Entries created | ${created} |`,
-        `| Entries modified | ${modified} |`,
-        `| Relations created | ${relations} |`,
-        `| Gate failures | ${gates} |`,
-        `| Contradiction warnings | ${warnings} |`
-      );
-    }
-    lines.push("", "Write tools are now blocked. Session data saved for future orientation.");
-    const fullResponse = wrapupNudge + lines.join("\n");
-    return { content: [{ type: "text", text: fullResponse }] };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: "text", text: `Failed to close agent session: ${msg}` }],
-      isError: true
-    };
   }
-}
-async function handleStatus() {
-  try {
-    const sessionId = getAgentSessionId();
-    if (!sessionId) {
-      return {
-        content: [{ type: "text", text: "No active agent session. Call `session action=start` to begin." }]
-      };
-    }
-    const session = await mcpCall("agent.getSession", {
-      sessionId
-    });
-    if (!session) {
-      return {
-        content: [{ type: "text", text: "Session ID cached but not found in Convex. Call `session action=start` to create a new session." }]
-      };
-    }
-    const oriented = isSessionOriented();
-    const created = session.entriesCreated?.length ?? 0;
-    const modified = session.entriesModified?.length ?? 0;
-    const lines = [
-      `Session ${sessionId} ${session.status}.`,
-      `Initiated by ${session.initiatedBy}.`,
-      `Scope: ${session.toolsScope}.`,
-      `Oriented: ${oriented ? "yes" : "no"}.`,
-      "",
-      `| Metric | Value |`,
+  await closeAgentSession();
+  const lines = [
+    `Session ${sessionId} closed.`,
+    ""
+  ];
+  const created = session?.entriesCreated?.length ?? 0;
+  const modified = session?.entriesModified?.length ?? 0;
+  const relations = session?.relationsCreated ?? 0;
+  const gates = session?.gateFailures ?? 0;
+  const warnings = session?.contradictionWarnings ?? 0;
+  if (session) {
+    lines.push(
+      `| Metric | Count |`,
       `|--------|-------|`,
       `| Entries created | ${created} |`,
       `| Entries modified | ${modified} |`,
-      `| Relations created | ${session.relationsCreated ?? 0} |`,
-      `| Started | ${new Date(session.startedAt).toISOString()} |`,
-      `| Expires | ${new Date(session.expiresAt).toISOString()} |`
-    ];
-    return { content: [{ type: "text", text: lines.join("\n") }] };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: "text", text: `Failed to get session status: ${msg}` }],
-      isError: true
-    };
+      `| Relations created | ${relations} |`,
+      `| Gate failures | ${gates} |`,
+      `| Contradiction warnings | ${warnings} |`
+    );
+  }
+  lines.push("", "Write tools are now blocked. Session data saved for future orientation.");
+  const fullResponse = wrapupNudge + lines.join("\n");
+  const summary = `Session ${sessionId} closed. ${created} created, ${modified} modified.`;
+  return {
+    content: [{ type: "text", text: fullResponse }],
+    structuredContent: success(summary, {
+      sessionId,
+      entriesCreated: created,
+      entriesModified: modified,
+      relationsCreated: relations,
+      gateFailures: gates,
+      contradictionWarnings: warnings,
+      wrapupNudge: wrapupNudge.length > 0
+    })
+  };
+}
+async function handleStatus() {
+  const sessionId = getAgentSessionId();
+  if (!sessionId) {
+    return failureResult(
+      "No active agent session. Call session action=start to begin.",
+      "SESSION_REQUIRED",
+      "No active agent session.",
+      "Call session action=start to begin.",
+      [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
+    );
   }
+  const session = await mcpCall("agent.getSession", {
+    sessionId
+  });
+  if (!session) {
+    return failureResult(
+      "Session not found in Convex. Call session action=start to create a new session.",
+      "NOT_FOUND",
+      "Session not found in Convex.",
+      "Call session action=start to create a new session.",
+      [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
+    );
+  }
+  const oriented = isSessionOriented();
+  const created = session.entriesCreated?.length ?? 0;
+  const modified = session.entriesModified?.length ?? 0;
+  const lines = [
+    `Session ${sessionId} ${session.status}.`,
+    `Initiated by ${session.initiatedBy}.`,
+    `Scope: ${session.toolsScope}.`,
+    `Oriented: ${oriented ? "yes" : "no"}.`,
+    "",
+    `| Metric | Value |`,
+    `|--------|-------|`,
+    `| Entries created | ${created} |`,
+    `| Entries modified | ${modified} |`,
+    `| Relations created | ${session.relationsCreated ?? 0} |`,
+    `| Started | ${new Date(session.startedAt).toISOString()} |`,
+    `| Expires | ${new Date(session.expiresAt).toISOString()} |`
+  ];
+  const summary = `Session ${sessionId} ${session.status}. ${created} created, ${modified} modified.`;
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: success(summary, {
+      sessionId,
+      status: session.status,
+      initiatedBy: session.initiatedBy,
+      toolsScope: session.toolsScope,
+      oriented,
+      entriesCreated: created,
+      entriesModified: modified,
+      relationsCreated: session.relationsCreated ?? 0
+    })
+  };
 }
 
 // src/tools/quality.ts
@@ -2176,12 +2342,9 @@ function registerQualityTools(server) {
       inputSchema: qualitySchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
-    async (args) => {
-      const parsed = qualitySchema.safeParse(args);
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(qualitySchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, entryId, context } = parsed.data;
       return runWithToolContext({ tool: "quality", action }, async () => {
         if (action === "check") {
@@ -2190,14 +2353,9 @@ function registerQualityTools(server) {
         if (action === "re-evaluate") {
           return handleReEvaluate(entryId, context ?? "review");
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${QUALITY_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, QUALITY_ACTIONS);
       });
-    }
+    })
   );
   trackWriteTool(qualityTool);
 }
@@ -2247,17 +2405,23 @@ ${linkHints}`;
   }
   return {
     content: [{ type: "text", text: result.text }],
-    structuredContent: {
-      entryId,
-      score: result.quality.score,
-      maxScore: result.quality.maxScore,
-      criteria: result.quality.checks.map((c) => ({
-        name: c.label,
-        score: c.passed ? 1 : 0,
-        maxScore: 1,
-        met: c.passed
-      }))
-    }
+    structuredContent: success(
+      `Quality check for ${entryId}: ${result.quality.score}/${result.quality.maxScore}.`,
+      {
+        entryId,
+        score: result.quality.score,
+        maxScore: result.quality.maxScore,
+        criteria: result.quality.checks.map((c) => ({
+          name: c.label,
+          score: c.passed ? 1 : 0,
+          maxScore: 1,
+          met: c.passed
+        }))
+      },
+      [
+        { tool: "graph", description: "Suggest connections", parameters: { action: "suggest", entryId } }
+      ]
+    )
   };
 }
 async function handleReEvaluate(entryId, context) {
@@ -2268,10 +2432,13 @@ async function handleReEvaluate(entryId, context) {
     context
   });
   if (!result) {
-    return {
-      content: [{ type: "text", text: `Entry \`${entryId}\` not found or has no rubric.` }],
-      structuredContent: { entryId, context, score: 0, maxScore: 0, improved: false }
-    };
+    return failureResult(
+      `Entry '${entryId}' not found or has no rubric.`,
+      "NOT_FOUND",
+      `Entry '${entryId}' not found or has no rubric.`,
+      "Use entries action=search to find the correct ID.",
+      [{ tool: "entries", description: "Search entries", parameters: { action: "search", query: entryId } }]
+    );
   }
   const llmScheduled = result.verdict.tier !== "passive";
   const lines = [`Re-evaluated \`${entryId}\` in \`${context}\` context.`];
@@ -2300,13 +2467,16 @@ async function handleReEvaluate(entryId, context) {
   const reEvalMaxScore = criteria.length;
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      entryId,
-      context,
-      score: reEvalScore,
-      maxScore: reEvalMaxScore,
-      improved: result.verdict.passed ?? false
-    }
+    structuredContent: success(
+      `Re-evaluated ${entryId} in ${context} context. Score: ${reEvalScore}/${reEvalMaxScore}.`,
+      {
+        entryId,
+        context,
+        score: reEvalScore,
+        maxScore: reEvalMaxScore,
+        improved: result.verdict.passed ?? false
+      }
+    )
   };
 }
 
@@ -2714,12 +2884,9 @@ function registerWorkflowTools(server) {
       inputSchema: workflowsSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async (args) => {
-      const parsed = workflowsSchema.safeParse(args ?? {});
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(workflowsSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, workflowId, roundId, output, isFinal, summaryName, summaryDescription } = parsed.data;
       return runWithToolContext({ tool: "workflows", action }, async () => {
         if (action === "list") {
@@ -2727,35 +2894,26 @@ function registerWorkflowTools(server) {
         }
         if (action === "checkpoint") {
           if (!workflowId || !roundId || output === void 0) {
-            return {
-              content: [{
-                type: "text",
-                text: "`workflowId`, `roundId`, and `output` are required when action is 'checkpoint'."
-              }]
-            };
+            return validationResult(
+              "workflowId, roundId, and output are required when action is 'checkpoint'."
+            );
           }
           return handleCheckpoint(workflowId, roundId, output, isFinal, summaryName, summaryDescription);
         }
-        return {
-          content: [{
-            type: "text",
-            text: `Unknown action '${action}'. Valid actions: ${WORKFLOWS_ACTIONS.join(", ")}.`
-          }]
-        };
+        return unknownAction(action, WORKFLOWS_ACTIONS);
       });
-    }
+    })
   );
   trackWriteTool(workflowsTool);
 }
 async function handleList3() {
   const workflows = listWorkflows();
   if (workflows.length === 0) {
-    return {
-      content: [{
-        type: "text",
-        text: "No workflows registered yet. Check back after the workflow definitions are configured."
-      }]
-    };
+    return successResult(
+      "No workflows registered yet. Check back after the workflow definitions are configured.",
+      "No workflows registered yet.",
+      { workflows: [], total: 0 }
+    );
   }
   const cards = workflows.map(formatWorkflowCard).join("\n\n---\n\n");
   return {
@@ -2768,7 +2926,19 @@ ${workflows.length} workflow(s) available. Use the \`run-workflow\` prompt to la
 ---
 
 ${cards}`
-    }]
+    }],
+    structuredContent: success(
+      `Found ${workflows.length} workflow(s).`,
+      {
+        workflows: workflows.map((w) => ({
+          id: w.id,
+          name: w.name,
+          rounds: w.rounds.length,
+          outputCollection: w.kbOutputCollection
+        })),
+        total: workflows.length
+      }
+    )
   };
 }
 async function handleCheckpoint(workflowId, roundId, output, isFinal, summaryName, summaryDescription) {
@@ -2780,18 +2950,31 @@ async function handleCheckpoint(workflowId, roundId, output, isFinal, summaryNam
         text: `Workflow "${workflowId}" not found. Available: ${listWorkflows().map((w) => w.id).join(", ")}.
 
 This checkpoint was NOT saved. Continue the conversation \u2014 the facilitator has the context.`
-      }]
+      }],
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Workflow '${workflowId}' not found.`,
+        "Use workflows action=list to see available workflows.",
+        [{ tool: "workflows", description: "List workflows", parameters: { action: "list" } }]
+      )
     };
   }
   const round = wf.rounds.find((r) => r.id === roundId);
   if (!round) {
+    const availableRounds = wf.rounds.map((r) => r.id).join(", ");
     return {
       content: [{
         type: "text",
-        text: `Round "${roundId}" not found in workflow "${workflowId}". Available rounds: ${wf.rounds.map((r) => r.id).join(", ")}.
+        text: `Round "${roundId}" not found in workflow "${workflowId}". Available rounds: ${availableRounds}.
 
 This checkpoint was NOT saved. The conversation context is preserved \u2014 continue facilitating.`
-      }]
+      }],
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Round '${roundId}' not found in workflow '${workflowId}'.`,
+        `Available rounds: ${availableRounds}`,
+        [{ tool: "workflows", description: "List workflows", parameters: { action: "list" } }]
+      )
     };
   }
   const lines = [
@@ -2822,6 +3005,31 @@ This checkpoint was NOT saved. The conversation context is preserved \u2014 cont
         `The summary is captured as a draft. Use \`commit-entry entryId="${result.entryId}"\` to promote it to the Chain.`,
         `Use \`graph action=suggest entryId="${result.entryId}"\` to discover connections.`
       );
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: success(
+          `Draft '${summaryName}' created (${result.entryId}) for workflow ${workflowId}.`,
+          {
+            entryId: result.entryId,
+            workflowId,
+            roundId,
+            collection: wf.kbOutputCollection,
+            isFinal: true
+          },
+          [
+            {
+              tool: "commit-entry",
+              description: "Promote draft to Chain",
+              parameters: { entryId: result.entryId }
+            },
+            {
+              tool: "graph",
+              description: "Discover connections",
+              parameters: { action: "suggest", entryId: result.entryId }
+            }
+          ]
+        )
+      };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       lines.push(
@@ -2833,6 +3041,15 @@ This checkpoint was NOT saved. The conversation context is preserved \u2014 cont
         `- Name: ${summaryName}`,
         `- Description: (copy from the conversation summary above)`
       );
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: failure(
+          "BACKEND_ERROR",
+          `Chain commit failed: ${msg}.`,
+          "Capture manually with the capture tool.",
+          [{ tool: "capture", description: "Capture manually", parameters: {} }]
+        )
+      };
     }
   } else {
     lines.push(
@@ -2840,8 +3057,10 @@ This checkpoint was NOT saved. The conversation context is preserved \u2014 cont
       `Output: ${output.substring(0, 200)}${output.length > 200 ? "..." : ""}`
     );
     const currentIdx = wf.rounds.findIndex((r) => r.id === roundId);
+    let nextRound;
     if (currentIdx < wf.rounds.length - 1) {
       const next = wf.rounds[currentIdx + 1];
+      nextRound = { id: next.id, num: next.num, label: next.label };
       lines.push(
         "",
         `**Next**: Round ${next.num} \u2014 ${next.label}`,
@@ -2853,8 +3072,21 @@ This checkpoint was NOT saved. The conversation context is preserved \u2014 cont
         `**All rounds complete.** Call this tool again with \`isFinal: true\` to commit to the Chain.`
       );
     }
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      structuredContent: success(
+        `Round ${round.num} (${round.label}) output recorded for workflow ${workflowId}.`,
+        {
+          workflowId,
+          roundId,
+          roundNum: round.num,
+          roundLabel: round.label,
+          isFinal: false,
+          nextRound
+        }
+      )
+    };
   }
-  return { content: [{ type: "text", text: lines.join("\n") }] };
 }
 
 // src/tools/facilitate.ts
@@ -3810,13 +4042,11 @@ function registerFacilitateTools(server) {
         openWorldHint: false
       }
     },
-    async (args) => {
+    withEnvelope(async (args) => {
       const parsed = facilitateSchema.safeParse(args);
       if (!parsed.success) {
         const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return {
-          content: [{ type: "text", text: `Invalid arguments: ${issues}` }]
-        };
+        return validationResult(`Invalid arguments: ${issues}`);
       }
       const { action } = parsed.data;
       return runWithToolContext({ tool: "facilitate", action }, async () => {
@@ -3832,15 +4062,10 @@ function registerFacilitateTools(server) {
           case "commit-constellation":
             return handleCommitConstellation(parsed.data);
           default:
-            return {
-              content: [{
-                type: "text",
-                text: `Unknown action '${action}'. Valid: ${FACILITATE_ACTIONS.join(", ")}.`
-              }]
-            };
+            return validationResult(`Unknown action '${action}'. Valid: ${FACILITATE_ACTIONS.join(", ")}.`);
         }
       });
-    }
+    })
   );
 }
 function buildStudioUrl(workspaceSlug, entryId) {
@@ -4178,7 +4403,11 @@ async function handleStart2(args) {
   ].filter(Boolean).join("\n");
   return {
     content: [{ type: "text", text: output }],
-    structuredContent: response
+    structuredContent: success(
+      `Shaping session started for "${betName}". Phase: context.`,
+      response,
+      [{ tool: "facilitate", description: "Describe the problem", parameters: { action: "respond", betName, dimension: "problem_clarity" } }]
+    )
   };
 }
 async function processCaptures(opts) {
@@ -4566,9 +4795,14 @@ function assembleResponse(opts) {
     sessionDrafts.length > 0 ? `**Session drafts (${sessionDrafts.length}):** ${sessionDrafts.map((d) => `\`${d.entryId}\` ${d.name}`).join(", ")}` : "",
     captureErrors.length > 0 ? `**Warnings:** ${captureErrors.map((e) => e.detail).join("; ")}` : ""
   ];
+  const summaryText = `${PHASE_LABELS[phase]} \u2014 ${DIMENSION_LABELS[activeDimension]}: ${scorecard[activeDimension]}/10.${coaching.captureReady ? " Capture ready." : ""}`;
   return {
     content: [{ type: "text", text: summaryParts.filter(Boolean).join("\n") }],
-    structuredContent: response
+    structuredContent: success(
+      summaryText,
+      response,
+      [{ tool: "facilitate", description: "Continue shaping", parameters: { action: "respond", betEntryId, dimension: nextDimension } }]
+    )
   };
 }
 async function handleRespond(args) {
@@ -4577,9 +4811,7 @@ async function handleRespond(args) {
   const source = argSource ?? "user";
   const captureItems = rawCapture ? Array.isArray(rawCapture) ? rawCapture : [rawCapture] : [];
   if (!userInput) {
-    return {
-      content: [{ type: "text", text: "`userInput` is required for respond action." }]
-    };
+    return validationResult("`userInput` is required for respond action.");
   }
   let betId = argBetId;
   if (!betId) {
@@ -4614,7 +4846,7 @@ async function handleRespond(args) {
       const msg = err instanceof Error ? err.message : String(err);
       return {
         content: [{ type: "text", text: `Failed to create bet entry: ${msg}` }],
-        isError: true
+        structuredContent: failure("BACKEND_ERROR", `Failed to create bet entry: ${msg}`, "Check workspace access and try again.")
       };
     }
   }
@@ -4625,7 +4857,13 @@ async function handleRespond(args) {
   ]);
   if (!betEntry) {
     return {
-      content: [{ type: "text", text: `Bet \`${betId}\` not found. Use start to create a session.` }]
+      content: [{ type: "text", text: `Bet \`${betId}\` not found. Use start to create a session.` }],
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Bet '${betId}' not found.`,
+        "Use facilitate action=start to begin a new session.",
+        [{ tool: "facilitate", description: "Start session", parameters: { action: "start" } }]
+      )
     };
   }
   const betData = betEntry.data ?? {};
@@ -4687,14 +4925,18 @@ async function handleRespond(args) {
 async function handleScore(args) {
   const betId = args.betEntryId;
   if (!betId) {
-    return {
-      content: [{ type: "text", text: "`betEntryId` is required for score action." }]
-    };
+    return validationResult("`betEntryId` is required for score action.");
   }
   const betEntry = await loadBetEntry(betId);
   if (!betEntry) {
     return {
-      content: [{ type: "text", text: `Bet \`${betId}\` not found.` }]
+      content: [{ type: "text", text: `Bet \`${betId}\` not found.` }],
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Bet '${betId}' not found.`,
+        "Use facilitate action=start to begin a session.",
+        [{ tool: "facilitate", description: "Start session", parameters: { action: "start" } }]
+      )
     };
   }
   const constellation = await loadConstellationState(betId, betEntry._id);
@@ -4764,31 +5006,38 @@ async function handleScore(args) {
   }
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      scorecard,
-      phase,
-      phaseLabel: PHASE_LABELS[phase],
-      completedDimensions: completed,
-      nextDimension: active,
-      sessionDrafts,
-      captureReady,
-      constellationDrafts,
-      commitBlockers: commitBlockers.length > 0 ? commitBlockers : void 0,
-      scorecardCriteria
-    }
+    structuredContent: success(
+      `Scorecard for ${betEntry.name}: ${completed.length}/${dims.length} complete. Phase: ${PHASE_LABELS[phase]}.${captureReady ? " Capture ready." : ""}`,
+      {
+        scorecard,
+        phase,
+        phaseLabel: PHASE_LABELS[phase],
+        completedDimensions: completed,
+        nextDimension: active,
+        sessionDrafts,
+        captureReady,
+        constellationDrafts,
+        commitBlockers: commitBlockers.length > 0 ? commitBlockers : void 0,
+        scorecardCriteria
+      }
+    )
   };
 }
 async function handleResume(args) {
   const betId = args.betEntryId;
   if (!betId) {
-    return {
-      content: [{ type: "text", text: "`betEntryId` is required for resume action." }]
-    };
+    return validationResult("`betEntryId` is required for resume action.");
   }
   const betEntry = await loadBetEntry(betId);
   if (!betEntry) {
     return {
-      content: [{ type: "text", text: `Bet \`${betId}\` not found. Cannot resume.` }]
+      content: [{ type: "text", text: `Bet \`${betId}\` not found. Cannot resume.` }],
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Bet '${betId}' not found.`,
+        "Use facilitate action=start to begin a new session.",
+        [{ tool: "facilitate", description: "Start session", parameters: { action: "start" } }]
+      )
     };
   }
   const constellation = await loadConstellationState(betId, betEntry._id);
@@ -4875,21 +5124,29 @@ ${directive}` : ""
   ].filter(Boolean).join("\n");
   return {
     content: [{ type: "text", text: output }],
-    structuredContent: response
+    structuredContent: success(
+      `Resumed session for "${betEntry.name}". Phase: ${PHASE_LABELS[phase]}. Next: ${DIMENSION_LABELS[active]}.`,
+      response,
+      [{ tool: "facilitate", description: `Continue with ${DIMENSION_LABELS[active]}`, parameters: { action: "respond", betEntryId: betId, dimension: active } }]
+    )
   };
 }
 async function handleCommitConstellation(args) {
   requireWriteAccess();
   const betId = args.betEntryId;
   if (!betId) {
-    return {
-      content: [{ type: "text", text: "`betEntryId` is required for commit-constellation action." }]
-    };
+    return validationResult("`betEntryId` is required for commit-constellation action.");
   }
   const betEntry = await loadBetEntry(betId);
   if (!betEntry) {
     return {
-      content: [{ type: "text", text: `Bet \`${betId}\` not found.` }]
+      content: [{ type: "text", text: `Bet \`${betId}\` not found.` }],
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Bet '${betId}' not found.`,
+        "Use facilitate action=start to begin a session.",
+        [{ tool: "facilitate", description: "Start session", parameters: { action: "start" } }]
+      )
     };
   }
   const betData = betEntry.data ?? {};
@@ -4934,21 +5191,23 @@ async function handleCommitConstellation(args) {
           "No entries were committed."
         ].join("\n")
       }],
-      structuredContent: {
-        operationId,
-        blockers: commitBlockerItems,
-        committedIds: [],
-        alreadyCommittedIds: [],
-        proposedIds: [],
-        failedIds: [],
-        conflictIds: [],
-        totalRelations: relations.length
-      }
+      structuredContent: failure(
+        "VALIDATION_ERROR",
+        `${commitBlockerItems.length} blocker(s) found. Fix before committing.`,
+        commitBlockerItems.map((b) => `${b.blocker} \u2192 ${b.fix}`).join("; "),
+        void 0,
+        {
+          operationId,
+          blockers: commitBlockerItems,
+          committedIds: [],
+          totalRelations: relations.length
+        }
+      )
     };
   }
   let contradictionWarnings = [];
   try {
-    const { runContradictionCheck } = await import("./smart-capture-QDF6MKRP.js");
+    const { runContradictionCheck } = await import("./smart-capture-XLBFE252.js");
     const descField = betData.problem ?? betData.description ?? "";
     contradictionWarnings = await runContradictionCheck(
       betEntry.name ?? betId,
@@ -4980,7 +5239,12 @@ async function handleCommitConstellation(args) {
 
 No constellation entries were committed.`
       }],
-      isError: true
+      structuredContent: failure(
+        "BACKEND_ERROR",
+        `Bet commit failed: ${msg}`,
+        "Retry or check for commit blockers.",
+        [{ tool: "facilitate", description: "Check scorecard", parameters: { action: "score", betEntryId: betId } }]
+      )
     };
   }
   result = {
@@ -5043,9 +5307,13 @@ No constellation entries were committed.`
       lines.push(`- \`${f.entryId}\` ${f.name}: ${f.error}`);
     }
   }
+  const summaryText = result.proposalCreated ? `Proposal created for ${betId}. ${result.committedIds.length} entries committed.` : `Published ${result.committedIds.length} entries for ${betId}. ${result.totalRelations} connections preserved.${hasIssues ? ` ${result.failedIds.length} failed, ${result.conflictIds.length} conflicts.` : ""}`;
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: { ...result, contradictionWarnings }
+    structuredContent: success(
+      summaryText,
+      { ...result, contradictionWarnings }
+    )
   };
 }
 
@@ -5209,15 +5477,14 @@ function registerVerifyTools(server) {
       inputSchema: verifySchema,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     },
-    async ({ collection, mode }) => {
+    withEnvelope(async ({ collection, mode }) => {
       const projectRoot = resolveProjectRoot();
       if (!projectRoot) {
-        return {
-          content: [{
-            type: "text",
-            text: "# Verification Failed\n\nCannot find project root (looked for `convex/schema.ts` in cwd and parent directory).\n\nSet `WORKSPACE_PATH` in `.env.mcp` to the absolute path of the Product Brain project root."
-          }]
-        };
+        return failureResult(
+          "# Verification Failed\n\nCannot find project root (looked for `convex/schema.ts` in cwd and parent directory).\n\nSet `WORKSPACE_PATH` in `.env.mcp` to the absolute path of the Product Brain project root.",
+          "VALIDATION_ERROR",
+          "Cannot find project root. Set WORKSPACE_PATH in .env.mcp."
+        );
       }
       const schema = parseConvexSchema(resolve(projectRoot, "convex/schema.ts"));
       await server.sendLoggingMessage({
@@ -5227,9 +5494,13 @@ function registerVerifyTools(server) {
       });
       const scopedEntries = await mcpQuery("chain.listEntries", { collectionSlug: collection });
       if (scopedEntries.length === 0) {
-        return {
-          content: [{ type: "text", text: `No entries found in \`${collection}\`. Nothing to verify.` }]
-        };
+        return failureResult(
+          `No entries found in '${collection}'. Nothing to verify.`,
+          "NOT_FOUND",
+          `No entries found in '${collection}'. Nothing to verify.`,
+          "Capture entries first, then verify.",
+          [{ tool: "capture", description: "Capture an entry", parameters: {} }]
+        );
       }
       await server.sendLoggingMessage({
         level: "info",
@@ -5323,6 +5594,14 @@ function registerVerifyTools(server) {
           fixes.push(entry.entryId);
         }
       }
+      const verified = mappingChecks.filter((c) => c.result === "verified").length;
+      const drifted = mappingChecks.filter((c) => c.result === "drifted").length;
+      const unverifiable = mappingChecks.filter((c) => c.result === "unverifiable").length;
+      const refsValid = refChecks.filter((c) => c.found).length;
+      const refsBroken = refChecks.filter((c) => !c.found).length;
+      const totalChecks = mappingChecks.length + refChecks.length;
+      const totalPassed = verified + refsValid;
+      const trustScore = totalChecks > 0 ? Math.round(totalPassed / totalChecks * 100) : 100;
       const report = formatTrustReport(
         collection,
         scopedEntries.length,
@@ -5333,8 +5612,27 @@ function registerVerifyTools(server) {
         schema.size,
         projectRoot
       );
-      return { content: [{ type: "text", text: report }] };
-    }
+      return {
+        content: [{ type: "text", text: report }],
+        structuredContent: success(
+          `Trust report for ${collection}: ${totalPassed}/${totalChecks} checks passed (${trustScore}%).`,
+          {
+            collection,
+            entryCount: scopedEntries.length,
+            trustScore,
+            totalChecks,
+            totalPassed,
+            verified,
+            drifted,
+            unverifiable,
+            refsValid,
+            refsBroken,
+            fixesApplied: fixes.length,
+            mode
+          }
+        )
+      };
+    })
   );
   trackWriteTool(verifyTool);
 }
@@ -5815,7 +6113,7 @@ function registerStartTools(server) {
       inputSchema: startSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
-    async ({ preset }) => {
+    withEnvelope(async ({ preset }) => {
       const errors = [];
       const agentSessionId = getAgentSessionId();
       let wsCtx = null;
@@ -5825,13 +6123,14 @@ function registerStartTools(server) {
         errors.push(`Workspace: ${e.message}`);
       }
       if (!wsCtx) {
+        const text = "# Could not connect to Product Brain\n\n" + (errors.length > 0 ? errors.map((e) => `- ${e}`).join("\n") : "Check your API key and CONVEX_SITE_URL.");
         return {
-          content: [
-            {
-              type: "text",
-              text: "# Could not connect to Product Brain\n\n" + (errors.length > 0 ? errors.map((e) => `- ${e}`).join("\n") : "Check your API key and CONVEX_SITE_URL.")
-            }
-          ]
+          content: [{ type: "text", text }],
+          structuredContent: failure(
+            "BACKEND_UNAVAILABLE",
+            "Could not connect to Product Brain.",
+            "Check your API key and CONVEX_SITE_URL."
+          )
         };
       }
       let stage = null;
@@ -5851,15 +6150,14 @@ function registerStartTools(server) {
       }
       if (stage === "blank") {
         const { oriented, orientationStatus } = await tryMarkOriented(agentSessionId);
-        const blankResult = buildBlankResponse(wsCtx);
+        const blankResult = buildBlankResponse(wsCtx, {
+          oriented,
+          orientationStatus,
+          ...agentSessionId ? { sessionId: agentSessionId } : {}
+        });
         return {
           content: [{ type: "text", text: blankResult.text }],
-          structuredContent: {
-            ...blankResult.structuredContent,
-            oriented,
-            orientationStatus,
-            ...agentSessionId ? { sessionId: agentSessionId } : {}
-          }
+          structuredContent: blankResult.structuredContent
         };
       }
       if (stage === "seeded") {
@@ -5880,10 +6178,10 @@ function registerStartTools(server) {
         content: [{ type: "text", text: orientResult.text }],
         structuredContent: orientResult.structuredContent
       };
-    }
+    })
   );
 }
-function buildBlankResponse(wsCtx) {
+function buildBlankResponse(wsCtx, sessionCtx) {
   const instructions = getInterviewInstructions(wsCtx.workspaceName);
   const text = [
     `# Welcome to ${wsCtx.workspaceName}`,
@@ -5947,7 +6245,14 @@ function buildBlankResponse(wsCtx) {
   ].join("\n");
   return {
     text,
-    structuredContent: { stage: "blank" }
+    structuredContent: success(
+      `Workspace is blank. Choose: tell me about your product, scan codebase, or use a preset.`,
+      { stage: "blank", ...sessionCtx },
+      [
+        { tool: "capture", description: "Capture product knowledge", parameters: {} },
+        { tool: "start", description: "Seed with a preset", parameters: { preset: "software-product" } }
+      ]
+    )
   };
 }
 async function buildSeededResponse(wsCtx, readiness, agentSessionId) {
@@ -5974,17 +6279,22 @@ async function buildSeededResponse(wsCtx, readiness, agentSessionId) {
     lines.push("No gaps detected \u2014 your workspace is filling up nicely. What would you like to work on?");
   }
   const { oriented, orientationStatus } = await tryMarkOriented(agentSessionId);
+  const next = gaps.length > 0 ? [{ tool: "capture", description: `Fill gap: ${gaps[0].label}`, parameters: {} }] : [];
   return {
     text: lines.join("\n"),
-    structuredContent: {
-      stage,
-      readinessScore: score ?? null,
-      totalGaps: gaps.length,
-      topGapLabels: gaps.slice(0, 3).map((g) => g.label),
-      oriented,
-      orientationStatus,
-      ...agentSessionId ? { sessionId: agentSessionId } : {}
-    }
+    structuredContent: success(
+      gaps.length > 0 ? `Workspace seeded. ${gaps.length} gap${gaps.length === 1 ? "" : "s"} to fill. Top: ${gaps[0].label}.` : `Workspace seeded. No gaps detected.`,
+      {
+        stage,
+        readinessScore: score ?? null,
+        totalGaps: gaps.length,
+        topGapLabels: gaps.slice(0, 3).map((g) => g.label),
+        oriented,
+        orientationStatus,
+        ...agentSessionId ? { sessionId: agentSessionId } : {}
+      },
+      next.length > 0 ? next : void 0
+    )
   };
 }
 async function seedPreset(wsCtx, presetId, agentSessionId) {
@@ -5994,7 +6304,12 @@ async function seedPreset(wsCtx, presetId, agentSessionId) {
       text: `Preset "${presetId}" not found.
 
 Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`,
-      structuredContent: { stage: "blank", error: "preset_not_found", preset: presetId }
+      structuredContent: failure(
+        "NOT_FOUND",
+        `Preset '${presetId}' not found.`,
+        `Available presets: ${listPresets().map((p) => p.id).join(", ")}.`,
+        [{ tool: "start", description: "Start with a preset", parameters: { preset: "software-product" } }]
+      )
     };
   }
   const seeded = [];
@@ -6039,15 +6354,19 @@ Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`,
   );
   return {
     text: lines.join("\n"),
-    structuredContent: {
-      stage: "blank",
-      preset: presetId,
-      seededCollections: seeded,
-      skippedCollections: skipped,
-      oriented,
-      orientationStatus,
-      ...agentSessionId ? { sessionId: agentSessionId } : {}
-    }
+    structuredContent: success(
+      `Seeded '${preset.name}' preset with ${seeded.length} collection${seeded.length === 1 ? "" : "s"}.`,
+      {
+        stage: "blank",
+        preset: presetId,
+        seededCollections: seeded,
+        skippedCollections: skipped,
+        oriented,
+        orientationStatus,
+        ...agentSessionId ? { sessionId: agentSessionId } : {}
+      },
+      [{ tool: "capture", description: "Capture your first entry", parameters: {} }]
+    )
   };
 }
 function computeWorkspaceAge(createdAt) {
@@ -6255,17 +6574,33 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
     lines.push("");
   }
   const { oriented, orientationStatus } = await tryMarkOriented(agentSessionId);
+  const stageLabel = stage ?? "active";
+  const gapCount = readiness?.gaps?.length ?? 0;
+  const summaryParts = [`Product Brain ready. Stage: ${stageLabel}.`];
+  if (gapCount > 0) summaryParts.push(`${gapCount} gap${gapCount === 1 ? "" : "s"}.`);
+  if (openTensions.length > 0) summaryParts.push(`${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}.`);
+  const next = [];
+  if (gapCount > 0) {
+    next.push({ tool: "capture", description: "Fill a gap", parameters: {} });
+  }
+  if (openTensions.length > 0) {
+    next.push({ tool: "entries", description: "View open tensions", parameters: { action: "list", collection: "tensions" } });
+  }
   return {
     text: lines.join("\n"),
-    structuredContent: {
-      stage,
-      readinessScore: readiness?.score ?? null,
-      totalGaps: readiness?.gaps?.length ?? 0,
-      openTensions: openTensions.length,
-      oriented,
-      orientationStatus,
-      ...agentSessionId ? { sessionId: agentSessionId } : {}
-    }
+    structuredContent: success(
+      summaryParts.join(" "),
+      {
+        stage,
+        readinessScore: readiness?.score ?? null,
+        totalGaps: gapCount,
+        openTensions: openTensions.length,
+        oriented,
+        orientationStatus,
+        ...agentSessionId ? { sessionId: agentSessionId } : {}
+      },
+      next.length > 0 ? next : void 0
+    )
   };
 }
 
@@ -6283,21 +6618,19 @@ function registerUsageTools(server) {
       inputSchema: usageSummarySchema,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async ({ periodDays }) => {
+    withEnvelope(async ({ periodDays }) => {
       const ws = await getWorkspaceContext();
       const sessionId = getAgentSessionId();
       const summary = await mcpQuery("usage.getWorkspaceSummary", {
         periodDays: periodDays ?? 30
       });
       if (!summary) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "No usage data available yet. LLM tracking may not be active or no calls have been made in this period."
-            }
-          ]
-        };
+        return failureResult(
+          "No usage data available yet. LLM tracking may not be active or no calls have been made in this period.",
+          "NOT_FOUND",
+          "No usage data available yet.",
+          "LLM tracking may not be active or no calls have been made in this period."
+        );
       }
       const lines = [
         `## Usage Summary \u2014 ${ws.workspaceName}`,
@@ -6328,9 +6661,21 @@ function registerUsageTools(server) {
             type: "text",
             text: lines.join("\n")
           }
-        ]
+        ],
+        structuredContent: success(
+          `Usage for ${ws.workspaceName}: $${summary.totalCostUsd.toFixed(4)} over ${summary.periodDays} days, ${summary.totalRequests} requests.`,
+          {
+            periodDays: summary.periodDays,
+            totalTokens: summary.totalTokens,
+            totalCostUsd: summary.totalCostUsd,
+            totalRequests: summary.totalRequests,
+            cacheHitRate: summary.cacheHitRate,
+            modelBreakdown: summary.modelBreakdown,
+            featureBreakdown: summary.featureBreakdown
+          }
+        )
       };
-    }
+    })
   );
 }
 
@@ -6389,9 +6734,11 @@ function registerGitChainTools(server) {
       inputSchema: chainSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ action, chainEntryId, title, chainTypeId, description, linkId, content, status, author }) => {
+    withEnvelope(async ({ action, chainEntryId, title, chainTypeId, description, linkId, content, status, author }) => {
       if (action === "create") {
-        if (!title) return { content: [{ type: "text", text: "A `title` is required to create a process." }] };
+        if (!title) {
+          return validationResult("A `title` is required to create a process.");
+        }
         const result = await mcpMutation(
           "gitchain.createChain",
           { title, chainTypeId, description, author }
@@ -6407,14 +6754,29 @@ function registerGitChainTools(server) {
 - **Status:** draft
 
 Use \`chain action=edit chainEntryId="${result.entryId}" linkId="problem" content="..."\` to start filling in links.`
-          }]
+          }],
+          structuredContent: success(
+            `Created process '${title}' (${result.entryId}), type: ${chainTypeId}.`,
+            { entryId: result.entryId, title, chainTypeId, status: "draft" },
+            [{ tool: "chain", description: "Edit a link", parameters: { action: "edit", chainEntryId: result.entryId, linkId: "problem" } }]
+          )
         };
       }
       if (action === "get") {
-        if (!chainEntryId) return { content: [{ type: "text", text: "A `chainEntryId` is required." }] };
+        if (!chainEntryId) {
+          return validationResult("A `chainEntryId` is required.");
+        }
         const chain = await mcpQuery("gitchain.getChain", { chainEntryId });
         if (!chain) {
-          return { content: [{ type: "text", text: `Process "${chainEntryId}" not found.` }] };
+          return {
+            content: [{ type: "text", text: `Process "${chainEntryId}" not found.` }],
+            structuredContent: failure(
+              "NOT_FOUND",
+              `Process "${chainEntryId}" not found.`,
+              "Use chain action=list to find available processes.",
+              [{ tool: "chain", description: "List processes", parameters: { action: "list" } }]
+            )
+          };
         }
         const scoreSection = chain.scores ? `
 ## Coherence: ${chain.coherenceScore}%
@@ -6437,28 +6799,48 @@ Use \`chain action=edit chainEntryId="${result.entryId}" linkId="problem" conten
 ## Links
 
 ` + linkSummary(chain.links)
-          }]
+          }],
+          structuredContent: success(
+            `${chain.name}: ${chain.filledCount}/${chain.totalCount} links, coherence ${chain.coherenceScore}%, v${chain.currentVersion}.`,
+            { entryId: chain.entryId, name: chain.name, status: chain.status, filledCount: chain.filledCount, totalCount: chain.totalCount, coherenceScore: chain.coherenceScore, currentVersion: chain.currentVersion }
+          )
         };
       }
       if (action === "list") {
-        const chains = await mcpQuery("gitchain.listChains", {
-          chainTypeId,
-          status
-        });
+        const chains = await mcpQuery("gitchain.listChains", { chainTypeId, status });
         if (chains.length === 0) {
-          return { content: [{ type: "text", text: "No processes found. Use `chain action=create` to create one." }] };
+          return {
+            content: [{ type: "text", text: "No processes found. Use `chain action=create` to create one." }],
+            structuredContent: success(
+              "No processes found.",
+              { chains: [], total: 0 },
+              [{ tool: "chain", description: "Create a process", parameters: { action: "create" } }]
+            )
+          };
         }
         const formatted = chains.map(
           (c) => `- **\`${c.entryId}\`** ${c.name} \u2014 ${c.chainTypeId} \xB7 ${c.filledCount}/${c.totalCount} links \xB7 coherence: ${c.coherenceScore}% \xB7 status: ${c.status}`
         ).join("\n");
-        return { content: [{ type: "text", text: `# Chains (${chains.length})
+        return {
+          content: [{ type: "text", text: `# Chains (${chains.length})
 
-${formatted}` }] };
+${formatted}` }],
+          structuredContent: success(
+            `Found ${chains.length} process(es).`,
+            { total: chains.length }
+          )
+        };
       }
       if (action === "edit") {
-        if (!chainEntryId) return { content: [{ type: "text", text: "A `chainEntryId` is required." }] };
-        if (!linkId) return { content: [{ type: "text", text: "A `linkId` is required (e.g. problem, insight, choice, action, outcome)." }] };
-        if (!content) return { content: [{ type: "text", text: "The `content` for the link is required." }] };
+        if (!chainEntryId) {
+          return validationResult("A `chainEntryId` is required.");
+        }
+        if (!linkId) {
+          return validationResult("A `linkId` is required (e.g. problem, insight, choice, action, outcome).");
+        }
+        if (!content) {
+          return validationResult("The `content` for the link is required.");
+        }
         const result = await mcpMutation("gitchain.editLink", { chainEntryId, linkId, content, author });
         return {
           content: [{
@@ -6471,11 +6853,16 @@ ${formatted}` }] };
 - **Content length:** ${content.length} chars
 
 Use \`chain action=get\` to see the full chain with updated scores.`
-          }]
+          }],
+          structuredContent: success(
+            `Updated link "${result.linkId}" on ${result.entryId}. Status: ${result.status}.`,
+            { entryId: result.entryId, linkId: result.linkId, status: result.status, contentLength: content.length },
+            [{ tool: "chain", description: "View full chain", parameters: { action: "get", chainEntryId } }]
+          )
         };
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return unknownAction(action, ["create", "get", "list", "edit"]);
+    })
   );
   trackWriteTool(chainTool);
   const chainVersionTool = server.registerTool(
@@ -6486,9 +6873,11 @@ Use \`chain action=get\` to see the full chain with updated scores.`
       inputSchema: chainVersionSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ action, chainEntryId, commitMessage, versionA, versionB, toVersion, author }) => {
+    withEnvelope(async ({ action, chainEntryId, commitMessage, versionA, versionB, toVersion, author }) => {
       if (action === "commit") {
-        if (!commitMessage) return { content: [{ type: "text", text: "A `commitMessage` is required." }] };
+        if (!commitMessage) {
+          return validationResult("A `commitMessage` is required.");
+        }
         const result = await mcpMutation("gitchain.commitChain", { chainEntryId, commitMessage, author });
         const warning = result.commitLintWarning ? `
 
@@ -6504,13 +6893,24 @@ Use \`chain action=get\` to see the full chain with updated scores.`
 - **Coherence:** ${result.coherenceScore}%
 - **Links modified:** ${result.linksModified.length > 0 ? result.linksModified.join(", ") : "none"}
 ` + warning
-          }]
+          }],
+          structuredContent: success(
+            `Committed v${result.version} on ${result.entryId}. Coherence: ${result.coherenceScore}%.`,
+            { entryId: result.entryId, version: result.version, coherenceScore: result.coherenceScore, linksModified: result.linksModified, lintWarning: result.commitLintWarning }
+          )
         };
       }
       if (action === "list") {
         const commits = await mcpQuery("gitchain.listCommits", { chainEntryId });
         if (commits.length === 0) {
-          return { content: [{ type: "text", text: `No commits found for chain "${chainEntryId}". Use \`chain-version action=commit\` to create the first snapshot.` }] };
+          return {
+            content: [{ type: "text", text: `No commits found for chain "${chainEntryId}". Use \`chain-version action=commit\` to create the first snapshot.` }],
+            structuredContent: success(
+              `No commits for ${chainEntryId}.`,
+              { chainEntryId, commits: [], total: 0 },
+              [{ tool: "chain-version", description: "Commit chain", parameters: { action: "commit", chainEntryId } }]
+            )
+          };
         }
         const formatted = commits.map((c) => {
           const date = new Date(c.createdAt).toISOString().replace("T", " ").substring(0, 19);
@@ -6518,13 +6918,19 @@ Use \`chain action=get\` to see the full chain with updated scores.`
           const links = c.linksModified?.length > 0 ? ` [${c.linksModified.join(", ")}]` : "";
           return `- **v${c.version}** ${date} by ${c.author} \u2014 ${msg}${links} (${c.versionStatus})`;
         }).join("\n");
-        return { content: [{ type: "text", text: `# Commits for ${chainEntryId} (${commits.length})
+        return {
+          content: [{ type: "text", text: `# Commits for ${chainEntryId} (${commits.length})
 
-${formatted}` }] };
+${formatted}` }],
+          structuredContent: success(
+            `${commits.length} commit(s) for ${chainEntryId}.`,
+            { chainEntryId, total: commits.length }
+          )
+        };
       }
       if (action === "diff") {
         if (versionA == null || versionB == null) {
-          return { content: [{ type: "text", text: "Both `versionA` and `versionB` are required for diff." }] };
+          return validationResult("Both `versionA` and `versionB` are required for diff.");
         }
         const diff = await mcpMutation("gitchain.diffVersions", { chainEntryId, versionA, versionB });
         let text = `# Diff: v${versionA} \u2192 v${versionB}
@@ -6549,10 +6955,18 @@ ${formatted}` }] };
             text += "\n";
           }
         }
-        return { content: [{ type: "text", text }] };
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: success(
+            `Diff v${versionA} \u2192 v${versionB}: coherence ${diff.coherenceBefore}% \u2192 ${diff.coherenceAfter}%, ${diff.linksChanged.length} link(s) changed.`,
+            { chainEntryId: diff.chainEntryId, versionA, versionB, coherenceBefore: diff.coherenceBefore, coherenceAfter: diff.coherenceAfter, coherenceDelta: diff.coherenceDelta, linksChanged: diff.linksChanged }
+          )
+        };
       }
       if (action === "revert") {
-        if (toVersion == null) return { content: [{ type: "text", text: "A `toVersion` is required for revert." }] };
+        if (toVersion == null) {
+          return validationResult("A `toVersion` is required for revert.");
+        }
         const result = await mcpMutation("gitchain.revertChain", { chainEntryId, toVersion, author });
         return {
           content: [{
@@ -6565,24 +6979,40 @@ ${formatted}` }] };
 - **Links affected:** ${result.linksModified.length > 0 ? result.linksModified.join(", ") : "none"}
 
 History is preserved \u2014 this created a new version, not a destructive reset.`
-          }]
+          }],
+          structuredContent: success(
+            `Reverted ${result.entryId} to v${result.revertedTo}. New version: v${result.newVersion}.`,
+            { entryId: result.entryId, revertedTo: result.revertedTo, newVersion: result.newVersion, linksModified: result.linksModified }
+          )
         };
       }
       if (action === "history") {
         const history = await mcpQuery("gitchain.getHistory", { chainEntryId });
         if (history.length === 0) {
-          return { content: [{ type: "text", text: `No history found for chain "${chainEntryId}".` }] };
+          return {
+            content: [{ type: "text", text: `No history found for chain "${chainEntryId}".` }],
+            structuredContent: success(
+              `No history for ${chainEntryId}.`,
+              { chainEntryId, events: [], total: 0 }
+            )
+          };
         }
         const formatted = history.sort((a, b) => b.timestamp - a.timestamp).map((h) => {
           const date = new Date(h.timestamp).toISOString().replace("T", " ").substring(0, 19);
           return `- **${date}** [${h.event}] by ${h.changedBy ?? "unknown"} \u2014 ${h.note ?? ""}`;
         }).join("\n");
-        return { content: [{ type: "text", text: `# History for ${chainEntryId} (${history.length} events)
+        return {
+          content: [{ type: "text", text: `# History for ${chainEntryId} (${history.length} events)
 
-${formatted}` }] };
+${formatted}` }],
+          structuredContent: success(
+            `${history.length} history event(s) for ${chainEntryId}.`,
+            { chainEntryId, total: history.length }
+          )
+        };
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return unknownAction(action, ["commit", "list", "diff", "revert", "history"]);
+    })
   );
   trackWriteTool(chainVersionTool);
   const chainBranchTool = server.registerTool(
@@ -6593,7 +7023,7 @@ ${formatted}` }] };
       inputSchema: chainBranchSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ action, chainEntryId, branchName, strategy, author }) => {
+    withEnvelope(async ({ action, chainEntryId, branchName, strategy, author }) => {
       if (action === "create") {
         const result = await mcpMutation("gitchain.createBranch", { chainEntryId, name: branchName, author });
         return {
@@ -6606,21 +7036,41 @@ ${formatted}` }] };
 - **Chain:** \`${chainEntryId}\`
 
 Edit links and commit on this branch, then use \`chain-branch action=merge\` to land changes.`
-          }]
+          }],
+          structuredContent: success(
+            `Created branch "${result.name}" based on v${result.baseVersion}.`,
+            { branchId: result.branchId, name: result.name, baseVersion: result.baseVersion, chainEntryId },
+            [{ tool: "chain-branch", description: "Merge branch", parameters: { action: "merge", chainEntryId, branchName: result.name } }]
+          )
         };
       }
       if (action === "list") {
         const branches = await mcpMutation("gitchain.listBranches", { chainEntryId });
         if (branches.length === 0) {
-          return { content: [{ type: "text", text: `No branches found for chain "${chainEntryId}".` }] };
+          return {
+            content: [{ type: "text", text: `No branches found for chain "${chainEntryId}".` }],
+            structuredContent: success(
+              `No branches for ${chainEntryId}.`,
+              { chainEntryId, branches: [], total: 0 },
+              [{ tool: "chain-branch", description: "Create a branch", parameters: { action: "create", chainEntryId } }]
+            )
+          };
         }
         const formatted = branches.map((b) => `- **${b.name}** (${b.status}) \u2014 based on v${b.baseVersion}, by ${b.createdBy}`).join("\n");
-        return { content: [{ type: "text", text: `# Branches for ${chainEntryId} (${branches.length})
+        return {
+          content: [{ type: "text", text: `# Branches for ${chainEntryId} (${branches.length})
 
-${formatted}` }] };
+${formatted}` }],
+          structuredContent: success(
+            `${branches.length} branch(es) for ${chainEntryId}.`,
+            { chainEntryId, total: branches.length }
+          )
+        };
       }
       if (action === "merge") {
-        if (!branchName) return { content: [{ type: "text", text: "A `branchName` is required for merge." }] };
+        if (!branchName) {
+          return validationResult("A `branchName` is required for merge.");
+        }
         const result = await mcpMutation("gitchain.mergeBranch", { chainEntryId, branchName, strategy, author });
         return {
           content: [{
@@ -6633,11 +7083,17 @@ ${formatted}` }] };
 - **Strategy:** ${result.strategy}
 
 Main is now at v${result.version}. The branch has been closed.`
-          }]
+          }],
+          structuredContent: success(
+            `Merged branch "${result.branchName}" into ${result.entryId} at v${result.version}.`,
+            { entryId: result.entryId, branchName: result.branchName, version: result.version, strategy: result.strategy }
+          )
         };
       }
       if (action === "conflicts") {
-        if (!branchName) return { content: [{ type: "text", text: "A `branchName` is required for conflict check." }] };
+        if (!branchName) {
+          return validationResult("A `branchName` is required for conflict check.");
+        }
         const result = await mcpMutation("gitchain.checkConflicts", { chainEntryId, branchName });
         if (!result.hasConflicts) {
           return {
@@ -6646,7 +7102,12 @@ Main is now at v${result.version}. The branch has been closed.`
               text: `# No Conflicts
 
 Branch "${branchName}" on \`${chainEntryId}\` has no conflicts. Safe to merge.`
-            }]
+            }],
+            structuredContent: success(
+              `No conflicts on branch "${branchName}". Safe to merge.`,
+              { chainEntryId, branchName, hasConflicts: false },
+              [{ tool: "chain-branch", description: "Merge branch", parameters: { action: "merge", chainEntryId, branchName } }]
+            )
           };
         }
         const conflictLines = result.conflicts.map(
@@ -6662,11 +7123,16 @@ Branch "${branchName}" conflicts with other branches on these links:
 ` + conflictLines + `
 
 Resolve conflicts before merging.`
-          }]
+          }],
+          structuredContent: failure(
+            "CONFLICT",
+            `Branch "${branchName}" has ${result.conflicts.length} conflict(s).`,
+            "Resolve conflicts on the conflicting links before merging."
+          )
         };
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return unknownAction(action, ["create", "list", "merge", "conflicts"]);
+    })
   );
   trackWriteTool(chainBranchTool);
   const chainReviewTool = server.registerTool(
@@ -6677,7 +7143,7 @@ Resolve conflicts before merging.`
       inputSchema: chainReviewSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
-    async ({ action, chainEntryId, commitMessage, versionNumber, linkId, body, commentId, author }) => {
+    withEnvelope(async ({ action, chainEntryId, commitMessage, versionNumber, linkId, body, commentId, author }) => {
       if (action === "gate") {
         const gate = await mcpQuery("gitchain.runGate", { chainEntryId, commitMessage });
         const checkLines = gate.checks.map((c) => `- ${c.pass ? "PASS" : "FAIL"} **${c.name}**: ${c.detail}`).join("\n");
@@ -6693,12 +7159,20 @@ Resolve conflicts before merging.`
 ## Checks
 
 ${checkLines}`
-          }]
+          }],
+          structuredContent: success(
+            `Gate ${icon}: ${gate.score}% (threshold ${gate.threshold}%).`,
+            { pass: gate.pass, score: gate.score, threshold: gate.threshold, checks: gate.checks }
+          )
         };
       }
       if (action === "comment") {
-        if (!versionNumber) return { content: [{ type: "text", text: "A `versionNumber` is required." }] };
-        if (!body) return { content: [{ type: "text", text: "A `body` is required." }] };
+        if (!versionNumber) {
+          return validationResult("A `versionNumber` is required.");
+        }
+        if (!body) {
+          return validationResult("A `body` is required.");
+        }
         const result = await mcpMutation("gitchain.addComment", {
           chainEntryId,
           versionNumber,
@@ -6715,13 +7189,19 @@ ${checkLines}`
 - **Version:** v${result.versionNumber}
 ` + (result.linkId ? `- **Link:** ${result.linkId}
 ` : "") + `- **Body:** ${body.substring(0, 200)}`
-          }]
+          }],
+          structuredContent: success(
+            `Comment added on ${result.chainEntryId} v${result.versionNumber}${result.linkId ? ` [${result.linkId}]` : ""}.`,
+            { chainEntryId: result.chainEntryId, versionNumber: result.versionNumber, linkId: result.linkId }
+          )
         };
       }
       if (action === "resolve-comment") {
-        if (!commentId) return { content: [{ type: "text", text: "A `commentId` is required." }] };
+        if (!commentId) {
+          return validationResult("A `commentId` is required.");
+        }
         await mcpMutation("gitchain.resolveComment", { commentId });
-        return { content: [{ type: "text", text: `Comment resolved.` }] };
+        return successResult("Comment resolved.", `Comment ${commentId} resolved.`, { commentId, resolved: true });
       }
       if (action === "list-comments") {
         const comments = await mcpMutation("gitchain.listComments", {
@@ -6729,7 +7209,13 @@ ${checkLines}`
           versionNumber
         });
         if (comments.length === 0) {
-          return { content: [{ type: "text", text: `No comments found for chain "${chainEntryId}"${versionNumber ? ` v${versionNumber}` : ""}.` }] };
+          return {
+            content: [{ type: "text", text: `No comments found for chain "${chainEntryId}"${versionNumber ? ` v${versionNumber}` : ""}.` }],
+            structuredContent: success(
+              `No comments for ${chainEntryId}${versionNumber ? ` v${versionNumber}` : ""}.`,
+              { chainEntryId, comments: [], total: 0, unresolved: 0 }
+            )
+          };
         }
         const formatted = comments.map((c) => {
           const date = new Date(c.createdAt).toISOString().replace("T", " ").substring(0, 19);
@@ -6744,11 +7230,15 @@ ${checkLines}`
             text: `# Comments for ${chainEntryId} (${comments.length}, ${unresolvedCount} unresolved)
 
 ${formatted}`
-          }]
+          }],
+          structuredContent: success(
+            `${comments.length} comment(s) for ${chainEntryId}, ${unresolvedCount} unresolved.`,
+            { chainEntryId, total: comments.length, unresolved: unresolvedCount }
+          )
         };
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return unknownAction(action, ["gate", "comment", "resolve-comment", "list-comments"]);
+    })
   );
   trackWriteTool(chainReviewTool);
 }
@@ -6808,7 +7298,7 @@ function registerMapTools(server) {
       inputSchema: createAudienceMapSetSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ audienceEntryId }) => {
+    withEnvelope(async ({ audienceEntryId }) => {
       const result = await mcpMutation(
         "maps.createAudienceMapSet",
         { audienceEntryId }
@@ -6832,9 +7322,18 @@ ${lines.join("\n")}
 
 Use map-slot to add ingredients. View at /empathy, /narrowing, and /jobs.`
           }
-        ]
+        ],
+        structuredContent: success(
+          `Created ${result.maps.length} audience maps for ${result.audienceEntryId}.`,
+          { audienceEntryId: result.audienceEntryId, maps: result.maps },
+          result.maps.map((m) => ({
+            tool: "map-slot",
+            description: `Add ingredients to ${m.templateId}`,
+            parameters: { action: "add", mapEntryId: m.mapEntryId }
+          }))
+        )
       };
-    }
+    })
   );
   trackWriteTool(createAudienceMapSetTool);
   const mapTool = server.registerTool(
@@ -6845,14 +7344,10 @@ Use map-slot to add ingredients. View at /empathy, /narrowing, and /jobs.`
       inputSchema: mapSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ action, mapEntryId, title, templateId, description, slotIds, status }) => {
+    withEnvelope(async ({ action, mapEntryId, title, templateId, description, slotIds, status }) => {
       if (action === "create") {
         if (!title) {
-          return {
-            content: [
-              { type: "text", text: "A `title` is required to create a map." }
-            ]
-          };
+          return validationResult("A `title` is required to create a map.");
         }
         const result = await mcpMutation(
           "maps.createMap",
@@ -6873,19 +7368,28 @@ Use map-slot to add ingredients. View at /empathy, /narrowing, and /jobs.`
 
 Use \`map-slot action=add mapEntryId="${result.entryId}" slotId="problem" ingredientEntryId="..."\` to start filling slots.`
             }
-          ]
+          ],
+          structuredContent: success(
+            `Created map '${title}' (${result.entryId}) using ${templateId} template.`,
+            { entryId: result.entryId, title, templateId, status: "draft" },
+            [{ tool: "map-slot", description: "Add ingredient to slot", parameters: { action: "add", mapEntryId: result.entryId } }]
+          )
         };
       }
       if (action === "get") {
         if (!mapEntryId) {
-          return {
-            content: [{ type: "text", text: "A `mapEntryId` is required." }]
-          };
+          return validationResult("A `mapEntryId` is required.");
         }
         const map = await mcpQuery("maps.getMap", { mapEntryId });
         if (!map) {
           return {
-            content: [{ type: "text", text: `Map "${mapEntryId}" not found.` }]
+            content: [{ type: "text", text: `Map "${mapEntryId}" not found.` }],
+            structuredContent: failure(
+              "NOT_FOUND",
+              `Map "${mapEntryId}" not found.`,
+              "Use map action=list to find available maps.",
+              [{ tool: "map", description: "List maps", parameters: { action: "list" } }]
+            )
           };
         }
         return {
@@ -6904,7 +7408,12 @@ Use \`map-slot action=add mapEntryId="${result.entryId}" slotId="problem" ingred
 
 ` + slotSummary(map.slots)
             }
-          ]
+          ],
+          structuredContent: success(
+            `${map.name}: ${map.completionScore}% complete (${map.filledSlots}/${map.totalSlots} slots), v${map.currentVersion}.`,
+            { entryId: map.entryId, name: map.name, templateName: map.templateName, status: map.status, completionScore: map.completionScore, filledSlots: map.filledSlots, totalSlots: map.totalSlots, currentVersion: map.currentVersion },
+            [{ tool: "map-slot", description: "Manage slot ingredients", parameters: { action: "list", mapEntryId } }]
+          )
         };
       }
       if (action === "list") {
@@ -6914,32 +7423,29 @@ Use \`map-slot action=add mapEntryId="${result.entryId}" slotId="problem" ingred
         });
         if (!maps || maps.length === 0) {
           return {
-            content: [
-              {
-                type: "text",
-                text: 'No maps found. Create one with `map action=create title="My Canvas"`.'
-              }
-            ]
+            content: [{ type: "text", text: 'No maps found. Create one with `map action=create title="My Canvas"`.' }],
+            structuredContent: success(
+              "No maps found.",
+              { maps: [], total: 0 },
+              [{ tool: "map", description: "Create a map", parameters: { action: "create" } }]
+            )
           };
         }
         const lines = maps.map(
           (m) => `- **${m.name}** (\`${m.entryId}\`) \u2014 ${m.templateId}, ${m.completionScore}% complete, v${m.currentVersion}`
         );
         return {
-          content: [
-            {
-              type: "text",
-              text: `# Maps (${maps.length})
+          content: [{ type: "text", text: `# Maps (${maps.length})
 
-${lines.join("\n")}`
-            }
-          ]
+${lines.join("\n")}` }],
+          structuredContent: success(
+            `Found ${maps.length} map(s).`,
+            { maps: maps.map((m) => ({ entryId: m.entryId, name: m.name, templateId: m.templateId, completionScore: m.completionScore })), total: maps.length }
+          )
         };
       }
-      return {
-        content: [{ type: "text", text: `Unknown action: ${action}` }]
-      };
-    }
+      return unknownAction(action, ["create", "get", "list"]);
+    })
   );
   trackWriteTool(mapTool);
   const mapSlotTool = server.registerTool(
@@ -6950,7 +7456,7 @@ ${lines.join("\n")}`
       inputSchema: mapSlotSchema,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     },
-    async ({
+    withEnvelope(async ({
       action,
       mapEntryId,
       slotId,
@@ -6963,116 +7469,88 @@ ${lines.join("\n")}`
         const map = await mcpQuery("maps.getMap", { mapEntryId });
         if (!map) {
           return {
-            content: [{ type: "text", text: `Map "${mapEntryId}" not found.` }]
+            content: [{ type: "text", text: `Map "${mapEntryId}" not found.` }],
+            structuredContent: failure(
+              "NOT_FOUND",
+              `Map "${mapEntryId}" not found.`,
+              "Use map action=list to find available maps.",
+              [{ tool: "map", description: "List maps", parameters: { action: "list" } }]
+            )
           };
         }
         if (slotId && map.slots[slotId]) {
+          const refs = map.slots[slotId];
           return {
             content: [
               {
                 type: "text",
                 text: `# Slot: ${slotId}
 
-` + (map.slots[slotId].length === 0 ? "(empty)" : map.slots[slotId].map(
+` + (refs.length === 0 ? "(empty)" : refs.map(
                   (r) => `- **${r.ingredientName ?? r.entryId}** (\`${r.entryId}\`)${r.pinnedVersion ? ` v${r.pinnedVersion}` : ""}`
                 ).join("\n"))
               }
-            ]
+            ],
+            structuredContent: success(
+              refs.length === 0 ? `Slot "${slotId}" is empty.` : `Slot "${slotId}": ${refs.length} ingredient(s).`,
+              { mapEntryId, slotId, ingredients: refs, count: refs.length }
+            )
           };
         }
         return {
-          content: [
-            { type: "text", text: `## All Slots
+          content: [{ type: "text", text: `## All Slots
 
-${slotSummary(map.slots)}` }
-          ]
+${slotSummary(map.slots)}` }],
+          structuredContent: success(
+            `${map.name}: ${Object.keys(map.slots).length} slots.`,
+            { mapEntryId, slotCount: Object.keys(map.slots).length }
+          )
         };
       }
       if (action === "add") {
         if (!slotId || !ingredientEntryId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Both `slotId` and `ingredientEntryId` are required for add."
-              }
-            ]
-          };
+          return validationResult("Both `slotId` and `ingredientEntryId` are required for add.");
         }
-        await mcpMutation("maps.addToSlot", {
-          mapEntryId,
-          slotId,
-          ingredientEntryId,
-          label,
-          author
-        });
+        await mcpMutation("maps.addToSlot", { mapEntryId, slotId, ingredientEntryId, label, author });
         return {
-          content: [
-            {
-              type: "text",
-              text: `Added \`${ingredientEntryId}\` to slot "${slotId}" on map \`${mapEntryId}\`.`
-            }
-          ]
+          content: [{ type: "text", text: `Added \`${ingredientEntryId}\` to slot "${slotId}" on map \`${mapEntryId}\`.` }],
+          structuredContent: success(
+            `Added ${ingredientEntryId} to slot "${slotId}".`,
+            { mapEntryId, slotId, ingredientEntryId },
+            [{ tool: "map", description: "View updated map", parameters: { action: "get", mapEntryId } }]
+          )
         };
       }
       if (action === "remove") {
         if (!slotId || !ingredientEntryId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Both `slotId` and `ingredientEntryId` are required for remove."
-              }
-            ]
-          };
+          return validationResult("Both `slotId` and `ingredientEntryId` are required for remove.");
         }
-        await mcpMutation("maps.removeFromSlot", {
-          mapEntryId,
-          slotId,
-          ingredientEntryId,
-          author
-        });
+        await mcpMutation("maps.removeFromSlot", { mapEntryId, slotId, ingredientEntryId, author });
         return {
-          content: [
-            {
-              type: "text",
-              text: `Removed \`${ingredientEntryId}\` from slot "${slotId}" on map \`${mapEntryId}\`.`
-            }
-          ]
+          content: [{ type: "text", text: `Removed \`${ingredientEntryId}\` from slot "${slotId}" on map \`${mapEntryId}\`.` }],
+          structuredContent: success(
+            `Removed ${ingredientEntryId} from slot "${slotId}".`,
+            { mapEntryId, slotId, ingredientEntryId },
+            [{ tool: "map", description: "View updated map", parameters: { action: "get", mapEntryId } }]
+          )
         };
       }
       if (action === "replace") {
         if (!slotId || !ingredientEntryId || !newIngredientEntryId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "`slotId`, `ingredientEntryId`, and `newIngredientEntryId` are required for replace."
-              }
-            ]
-          };
+          return validationResult("`slotId`, `ingredientEntryId`, and `newIngredientEntryId` are required for replace.");
         }
-        await mcpMutation("maps.replaceInSlot", {
-          mapEntryId,
-          slotId,
-          oldIngredientEntryId: ingredientEntryId,
-          newIngredientEntryId,
-          label,
-          author
-        });
+        await mcpMutation("maps.replaceInSlot", { mapEntryId, slotId, oldIngredientEntryId: ingredientEntryId, newIngredientEntryId, label, author });
         return {
-          content: [
-            {
-              type: "text",
-              text: `Replaced \`${ingredientEntryId}\` with \`${newIngredientEntryId}\` in slot "${slotId}".`
-            }
-          ]
+          content: [{ type: "text", text: `Replaced \`${ingredientEntryId}\` with \`${newIngredientEntryId}\` in slot "${slotId}".` }],
+          structuredContent: success(
+            `Replaced ${ingredientEntryId} with ${newIngredientEntryId} in slot "${slotId}".`,
+            { mapEntryId, slotId, removed: ingredientEntryId, added: newIngredientEntryId },
+            [{ tool: "map", description: "View updated map", parameters: { action: "get", mapEntryId } }]
+          )
         };
       }
-      return {
-        content: [{ type: "text", text: `Unknown action: ${action}` }]
-      };
-    }
+      return unknownAction(action, ["add", "remove", "replace", "list"]);
+    })
   );
   trackWriteTool(mapSlotTool);
   const mapVersionTool = server.registerTool(
@@ -7083,7 +7561,7 @@ ${slotSummary(map.slots)}` }
       inputSchema: mapVersionSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ action, mapEntryId, commitMessage, author }) => {
+    withEnvelope(async ({ action, mapEntryId, commitMessage, author }) => {
       if (action === "commit") {
         const result = await mcpMutation("maps.commitMap", {
           mapEntryId,
@@ -7102,21 +7580,23 @@ ${slotSummary(map.slots)}` }
 
 All ingredient references have been pinned at their current versions.`
             }
-          ]
+          ],
+          structuredContent: success(
+            `Committed map ${mapEntryId} at v${result.version} (${result.completionScore}% complete).`,
+            { mapEntryId, version: result.version, completionScore: result.completionScore, slotsModified: result.slotsModified }
+          )
         };
       }
       if (action === "list" || action === "history") {
-        const commits = await mcpQuery("maps.listMapCommits", {
-          mapEntryId
-        });
+        const commits = await mcpQuery("maps.listMapCommits", { mapEntryId });
         if (!commits || commits.length === 0) {
           return {
-            content: [
-              {
-                type: "text",
-                text: `No commits yet for map \`${mapEntryId}\`. Use \`map-version action=commit\` to create the first snapshot.`
-              }
-            ]
+            content: [{ type: "text", text: `No commits yet for map \`${mapEntryId}\`. Use \`map-version action=commit\` to create the first snapshot.` }],
+            structuredContent: success(
+              `No commits yet for ${mapEntryId}.`,
+              { mapEntryId, commits: [], total: 0 },
+              [{ tool: "map-version", description: "Commit the map", parameters: { action: "commit", mapEntryId } }]
+            )
           };
         }
         const lines = commits.map(
@@ -7124,20 +7604,17 @@ All ingredient references have been pinned at their current versions.`
   Slots changed: ${c.slotsModified.join(", ")}` : "")
         );
         return {
-          content: [
-            {
-              type: "text",
-              text: `# Map History: \`${mapEntryId}\` (${commits.length} commits)
+          content: [{ type: "text", text: `# Map History: \`${mapEntryId}\` (${commits.length} commits)
 
-${lines.join("\n")}`
-            }
-          ]
+${lines.join("\n")}` }],
+          structuredContent: success(
+            `${commits.length} commit(s) for ${mapEntryId}.`,
+            { mapEntryId, total: commits.length }
+          )
         };
       }
-      return {
-        content: [{ type: "text", text: `Unknown action: ${action}` }]
-      };
-    }
+      return unknownAction(action, ["commit", "list", "history"]);
+    })
   );
   trackWriteTool(mapVersionTool);
   server.registerTool(
@@ -7148,22 +7625,25 @@ ${lines.join("\n")}`
       inputSchema: mapSuggestSchema,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async ({ mapEntryId, slotId, query }) => {
+    withEnvelope(async ({ mapEntryId, slotId, query }) => {
       const map = await mcpQuery("maps.getMap", { mapEntryId });
       if (!map) {
         return {
-          content: [{ type: "text", text: `Map "${mapEntryId}" not found.` }]
+          content: [{ type: "text", text: `Map "${mapEntryId}" not found.` }],
+          structuredContent: failure(
+            "NOT_FOUND",
+            `Map "${mapEntryId}" not found.`,
+            "Use map action=list to find available maps.",
+            [{ tool: "map", description: "List maps", parameters: { action: "list" } }]
+          )
         };
       }
       const emptySlots = slotId ? [slotId].filter((id) => (map.slots[id]?.length ?? 0) === 0) : Object.entries(map.slots).filter(([, refs]) => refs.length === 0).map(([id]) => id);
       if (emptySlots.length === 0) {
+        const msg = slotId ? `Slot "${slotId}" already has ingredients.` : "All slots have ingredients. Nothing to suggest.";
         return {
-          content: [
-            {
-              type: "text",
-              text: slotId ? `Slot "${slotId}" already has ingredients.` : "All slots have ingredients. Nothing to suggest."
-            }
-          ]
+          content: [{ type: "text", text: msg }],
+          structuredContent: success(msg, { mapEntryId, emptySlots: 0 })
         };
       }
       const slotDefs = map.slotDefs ?? [];
@@ -7202,9 +7682,14 @@ _No matching entries found. Create ingredients first._`
 
 Use \`map-slot action=add mapEntryId="${mapEntryId}" slotId="..." ingredientEntryId="..."\` to add ingredients.`
           }
-        ]
+        ],
+        structuredContent: success(
+          `Suggestions for ${emptySlots.length} empty slot(s) on "${map.name}".`,
+          { mapEntryId, emptySlots: emptySlots.length },
+          [{ tool: "map-slot", description: "Add ingredient", parameters: { action: "add", mapEntryId } }]
+        )
       };
-    }
+    })
   );
 }
 
@@ -7386,7 +7871,7 @@ function registerArchitectureTools(server) {
       inputSchema: architectureSchema,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async ({ action, template, layer, flow }) => {
+    withEnvelope(async ({ action, template, layer, flow }) => {
       await ensureCollection();
       const all = await listArchEntries();
       if (action === "show") {
@@ -7402,7 +7887,13 @@ function registerArchitectureTools(server) {
             content: [{
               type: "text",
               text: "# Architecture Explorer\n\nNo architecture data found. Use `architecture-admin action=seed` to populate the default architecture."
-            }]
+            }],
+            structuredContent: failure(
+              "NOT_FOUND",
+              "No architecture data found.",
+              "Seed the default architecture first.",
+              [{ tool: "architecture-admin", description: "Seed architecture", parameters: { action: "seed" } }]
+            )
           };
         }
         const textLayers = layers.map((l) => formatLayerText(l, nodes)).join("\n\n");
@@ -7417,18 +7908,31 @@ ${textLayers}${textFlows}`;
           content: [
             { type: "text", text },
             { type: "resource", resource: { uri: `ui://product-os/architecture`, mimeType: "text/html", text: html } }
-          ]
+          ],
+          structuredContent: success(
+            `Showing ${templateName}: ${layers.length} layers, ${nodes.length} nodes, ${flows.length} flows.`,
+            { templateName, layerCount: layers.length, nodeCount: nodes.length, flowCount: flows.length }
+          )
         };
       }
       if (action === "explore") {
-        if (!layer) return { content: [{ type: "text", text: "A `layer` is required for explore." }] };
+        if (!layer) {
+          return validationResult("A `layer` is required for explore.");
+        }
         const layers = byTag(all, "layer");
         const target = layers.find(
           (l) => l.name.toLowerCase() === layer.toLowerCase() || l.entryId === layer
         );
         if (!target) {
           const available = layers.map((l) => `\`${l.name}\``).join(", ");
-          return { content: [{ type: "text", text: `Layer "${layer}" not found. Available layers: ${available}` }] };
+          return {
+            content: [{ type: "text", text: `Layer "${layer}" not found. Available layers: ${available}` }],
+            structuredContent: failure(
+              "NOT_FOUND",
+              `Layer "${layer}" not found.`,
+              `Available layers: ${available}`
+            )
+          };
         }
         const nodes = byTag(all, "node").filter((n) => n.data?.layerRef === target.entryId);
         const flows = byTag(all, "flow").filter(
@@ -7459,18 +7963,31 @@ ${target.data?.description ?? ""}${depRule}${layerRationale}
 **${nodes.length} components**
 
 ${nodeDetail}${flowLines}`
-          }]
+          }],
+          structuredContent: success(
+            `${target.name} layer: ${nodes.length} components, ${flows.length} connected flows.`,
+            { layerName: target.name, entryId: target.entryId, nodeCount: nodes.length, flowCount: flows.length }
+          )
         };
       }
       if (action === "flow") {
-        if (!flow) return { content: [{ type: "text", text: "A `flow` name or entry ID is required." }] };
+        if (!flow) {
+          return validationResult("A `flow` name or entry ID is required.");
+        }
         const flows = byTag(all, "flow");
         const target = flows.find(
           (f) => f.name.toLowerCase() === flow.toLowerCase() || f.entryId === flow
         );
         if (!target) {
           const available = flows.map((f) => `\`${f.name}\``).join(", ");
-          return { content: [{ type: "text", text: `Flow "${flow}" not found. Available flows: ${available}` }] };
+          return {
+            content: [{ type: "text", text: `Flow "${flow}" not found. Available flows: ${available}` }],
+            structuredContent: failure(
+              "NOT_FOUND",
+              `Flow "${flow}" not found.`,
+              `Available flows: ${available}`
+            )
+          };
         }
         const nodes = byTag(all, "node");
         const source = nodes.find((n) => n.entryId === target.data?.sourceNode);
@@ -7490,10 +8007,16 @@ ${nodeDetail}${flowLines}`
           lines.push("", `### Target: ${dest.name}`, String(dest.data?.description ?? ""));
           if (dest.data?.filePaths) lines.push(`Files: \`${dest.data.filePaths}\``);
         }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          structuredContent: success(
+            `${target.name}: ${source?.name ?? "?"} \u2192 ${dest?.name ?? "?"}.`,
+            { flowName: target.name, entryId: target.entryId, source: source?.name, target: dest?.name }
+          )
+        };
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return unknownAction(action, ["show", "explore", "flow"]);
+    })
   );
   const archAdminTool = server.registerTool(
     "architecture-admin",
@@ -7503,7 +8026,7 @@ ${nodeDetail}${flowLines}`
       inputSchema: architectureAdminSchema,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     },
-    async ({ action }) => {
+    withEnvelope(async ({ action }) => {
       if (action === "seed") {
         await ensureCollection();
         const existing = await listArchEntries();
@@ -7554,7 +8077,12 @@ ${nodeDetail}${flowLines}`
 **Unchanged:** ${unchanged}
 
 Use \`architecture action=show\` to view the map.`
-          }]
+          }],
+          structuredContent: success(
+            `Architecture seeded: ${created} created, ${updated} updated, ${unchanged} unchanged.`,
+            { created, updated, unchanged },
+            [{ tool: "architecture", description: "View the map", parameters: { action: "show" } }]
+          )
         };
       }
       if (action === "check") {
@@ -7564,7 +8092,12 @@ Use \`architecture action=show\` to view the map.`
             content: [{
               type: "text",
               text: "# Scan Failed\n\nCannot find project root (looked for `convex/schema.ts` in cwd and parent). Set `WORKSPACE_PATH` env var to the absolute path of the Product OS project root."
-            }]
+            }],
+            structuredContent: failure(
+              "VALIDATION_ERROR",
+              "Cannot find project root.",
+              "Set WORKSPACE_PATH env var to the absolute path of the Product OS project root."
+            )
           };
         }
         await ensureCollection();
@@ -7572,10 +8105,21 @@ Use \`architecture action=show\` to view the map.`
         const layers = byTag(all, "layer");
         const nodes = byTag(all, "node");
         const result = scanDependencies(projectRoot, layers, nodes);
-        return { content: [{ type: "text", text: formatScanReport(result) }] };
+        return {
+          content: [{ type: "text", text: formatScanReport(result) }],
+          structuredContent: success(
+            result.violations.length === 0 ? `Health check passed: 0 violations across ${result.filesScanned} files.` : `Health check found ${result.violations.length} violation(s) across ${result.filesScanned} files.`,
+            {
+              violations: result.violations.length,
+              filesScanned: result.filesScanned,
+              importsChecked: result.importsChecked,
+              unmappedImports: result.unmappedImports
+            }
+          )
+        };
       }
-      return { content: [{ type: "text", text: "Unknown action." }] };
-    }
+      return unknownAction(action, ["seed", "check"]);
+    })
   );
   trackWriteTool(archAdminTool);
 }
@@ -7937,15 +8481,19 @@ async function handleHealthCheck() {
       lines.push(`- ${err}`);
     }
   }
+  const healthData = {
+    healthy,
+    collections: collections.length,
+    entries: totalEntries,
+    latencyMs: durationMs,
+    workspace: workspaceId ?? "unresolved"
+  };
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      healthy,
-      collections: collections.length,
-      entries: totalEntries,
-      latencyMs: durationMs,
-      workspace: workspaceId ?? "unresolved"
-    }
+    structuredContent: success(
+      healthy ? `Healthy. ${collections.length} collections, ${totalEntries} entries, ${durationMs}ms.` : `Degraded. ${errors.length} error(s).`,
+      healthData
+    )
   };
 }
 async function handleWhoami() {
@@ -7962,13 +8510,10 @@ async function handleWhoami() {
   ];
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      workspaceId: ctx.workspaceId,
-      workspaceName: ctx.workspaceName,
-      scope,
-      sessionId,
-      oriented
-    }
+    structuredContent: success(
+      `Session: ${ctx.workspaceName} (${scope}). ${oriented ? "Oriented." : "Not oriented."}`,
+      { workspaceId: ctx.workspaceId, workspaceName: ctx.workspaceName, scope, sessionId, oriented }
+    )
   };
 }
 var STAGE_LABELS = {
@@ -8021,31 +8566,32 @@ async function handleWorkspaceStatus() {
       lines.push(`- [x] ${check.label} (${check.current}/${check.required})`);
     }
   }
+  const statusData = {
+    stage,
+    scoringVersion,
+    readinessScore: score,
+    activeEntries: stats.activeCount,
+    totalRelations: stats.totalRelations,
+    orphanedEntries: stats.orphanedCount,
+    gaps: gaps.map((g) => ({
+      id: g.id,
+      label: g.label,
+      guidance: g.capabilityGuidance ?? g.guidance
+    }))
+  };
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: {
-      stage,
-      scoringVersion,
-      readinessScore: score,
-      activeEntries: stats.activeCount,
-      totalRelations: stats.totalRelations,
-      orphanedEntries: stats.orphanedCount,
-      gaps: gaps.map((g) => ({
-        id: g.id,
-        label: g.label,
-        guidance: g.capabilityGuidance ?? g.guidance
-      }))
-    }
+    structuredContent: success(
+      `Brain: ${stageLabel} (${score}%). ${stats.activeCount} active entries, ${gaps.length} gap(s).`,
+      statusData
+    )
   };
 }
 async function handleAudit(limit) {
   const log = getAuditLog();
   const recent = log.slice(-limit);
   if (recent.length === 0) {
-    return {
-      content: [{ type: "text", text: "No calls recorded yet this session." }],
-      structuredContent: { totalCalls: 0, calls: [] }
-    };
+    return successResult("No calls recorded yet this session.", "No calls recorded yet this session.", { totalCalls: 0, calls: [] });
   }
   const summary = buildSessionSummary(log);
   const logLines = [`# Audit Log (last ${recent.length} of ${log.length} total)
@@ -8056,21 +8602,25 @@ async function handleAudit(limit) {
     const toolPart = entry.toolContext ? ` [${entry.toolContext.tool}${entry.toolContext.action ? ` action=${entry.toolContext.action}` : ""}]` : "";
     logLines.push(`${icon} \`${entry.fn}\`${toolPart} ${entry.durationMs}ms ${entry.status}${errPart}`);
   }
+  const auditData = {
+    totalCalls: log.length,
+    calls: recent.map((entry) => ({
+      tool: entry.fn,
+      ...entry.toolContext?.action && { action: entry.toolContext.action },
+      timestamp: entry.ts,
+      ...entry.durationMs != null && { durationMs: entry.durationMs }
+    }))
+  };
   return {
     content: [{ type: "text", text: `${summary}
 
 ---
 
 ${logLines.join("\n")}` }],
-    structuredContent: {
-      totalCalls: log.length,
-      calls: recent.map((entry) => ({
-        tool: entry.fn,
-        ...entry.toolContext?.action && { action: entry.toolContext.action },
-        timestamp: entry.ts,
-        ...entry.durationMs != null && { durationMs: entry.durationMs }
-      }))
-    }
+    structuredContent: success(
+      `Audit: ${log.length} total calls, showing last ${recent.length}.`,
+      auditData
+    )
   };
 }
 var HEALTH_ACTIONS = ["check", "whoami", "status", "audit", "self-test"];
@@ -8199,7 +8749,10 @@ function handleSelfTest() {
   }
   return {
     content: [{ type: "text", text: lines.join("\n") }],
-    structuredContent: { passed, failed, total, results }
+    structuredContent: success(
+      failed === 0 ? `Self-test: all ${total} schemas valid.` : `Self-test: ${failed}/${total} schemas failed.`,
+      { passed, failed, total, results }
+    )
   };
 }
 function registerHealthTools(server) {
@@ -8211,12 +8764,9 @@ function registerHealthTools(server) {
       inputSchema: healthSchema,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async (args) => {
-      const parsed = healthSchema.safeParse(args ?? {});
-      if (!parsed.success) {
-        const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-        return { content: [{ type: "text", text: `Invalid arguments: ${issues}` }] };
-      }
+    withEnvelope(async (args) => {
+      const parsed = parseOrFail(healthSchema, args);
+      if (!parsed.ok) return parsed.result;
       const { action, limit } = parsed.data;
       return runWithToolContext({ tool: "health", action }, async () => {
         if (action === "check") return handleHealthCheck();
@@ -8224,11 +8774,9 @@ function registerHealthTools(server) {
         if (action === "status") return handleWorkspaceStatus();
         if (action === "audit") return handleAudit(limit ?? 20);
         if (action === "self-test") return handleSelfTest();
-        return {
-          content: [{ type: "text", text: `Unknown action '${action}'. Valid actions: ${HEALTH_ACTIONS.join(", ")}.` }]
-        };
+        return unknownAction(action, HEALTH_ACTIONS);
       });
-    }
+    })
   );
   server.registerTool(
     "orient",
@@ -8238,13 +8786,16 @@ function registerHealthTools(server) {
       inputSchema: orientSchema,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    async ({ mode = "full", task } = {}) => {
+    withEnvelope(async ({ mode = "full", task } = {}) => {
       const errors = [];
       const agentSessionId = getAgentSessionId();
       if (isSessionOriented() && mode === "brief" && !task) {
         return {
           content: [{ type: "text", text: "Already oriented. Session active, writes unlocked. Use `orient mode='full'` or `orient task='...'` for full context." }],
-          structuredContent: { alreadyOriented: true, sessionId: agentSessionId }
+          structuredContent: success(
+            "Already oriented. Session active, writes unlocked.",
+            { alreadyOriented: true, sessionId: agentSessionId }
+          )
         };
       }
       let wsCtx = null;
@@ -8310,13 +8861,11 @@ function registerHealthTools(server) {
         }
         return {
           content: [{ type: "text", text: scanLines.join("\n") }],
-          structuredContent: {
-            stage: "blank",
-            readinessScore: readiness?.score ?? 0,
-            oriented,
-            orientationStatus,
-            redirectHint: "Use the `start` tool for the full guided setup experience."
-          }
+          structuredContent: success(
+            "Workspace is blank. Use the start tool for guided setup.",
+            { stage: "blank", readinessScore: readiness?.score ?? 0, oriented, orientationStatus, redirectHint: "Use the `start` tool for the full guided setup experience." },
+            [{ tool: "start", description: "Guided workspace setup", parameters: {} }]
+          )
         };
       }
       const lines = [];
@@ -8390,7 +8939,13 @@ function registerHealthTools(server) {
           lines.push("");
           for (const err of errors) lines.push(`- ${err}`);
         }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          structuredContent: success(
+            `Oriented (brief). Stage: ${readiness?.stage ?? "unknown"}.`,
+            { mode: "brief", stage: readiness?.stage ?? "unknown", oriented: isSessionOriented(), sessionId: agentSessionId }
+          )
+        };
       }
       const orientStage = readiness?.stage ?? "seeded";
       if (isLowReadiness && wsCtx?.createdAt) {
@@ -8628,8 +9183,14 @@ function registerHealthTools(server) {
         lines.push("---");
         lines.push("_No active agent session. Call `session action=start` to begin a tracked session._");
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
-    }
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: success(
+          `Oriented (full). Stage: ${orientStage}. ${isLowReadiness ? "Low readiness \u2014 gaps remain." : "Ready."}`,
+          { mode: "full", stage: orientStage, oriented: isSessionOriented(), sessionId: agentSessionId }
+        )
+      };
+    })
   );
 }
 
@@ -9955,4 +10516,4 @@ export {
   SERVER_VERSION,
   createProductBrainServer
 };
-//# sourceMappingURL=chunk-6O4EVIVI.js.map
+//# sourceMappingURL=chunk-FMEZXUP5.js.map