diff --git a/src/mcp/server/miftah-server.ts b/src/mcp/server/miftah-server.ts
index ed4d9fcc..288354a6 100644
--- a/src/mcp/server/miftah-server.ts
+++ b/src/mcp/server/miftah-server.ts
@@ -473,6 +473,7 @@ export class MiftahServer {
     }).catch(() => undefined);
   }
 
+  /** Closes subscriptions, the MCP server, and upstreams while preserving the first shutdown failure. */
   async close(): Promise<void> {
     this.profileTransitionSession += 1;
     this.profileTransitionConfirmations = new WeakMap<object, ProfileTransitionConfirmationBinding>();
@@ -1053,6 +1054,7 @@ export class MiftahServer {
     }
   }
 
+  /** Resolves an exposed upstream tool, validates its routed target, and executes it through the policy pipeline. */
   private async handleUpstreamTool(
     name: string,
     args: Record<string, unknown>,
diff --git a/src/mcp/server/operation-pipeline.ts b/src/mcp/server/operation-pipeline.ts
index 08b4fb4d..8fd33bd2 100644
--- a/src/mcp/server/operation-pipeline.ts
+++ b/src/mcp/server/operation-pipeline.ts
@@ -207,6 +207,7 @@ export class OperationPipeline {
     }
   }
 
+  /** Throws the safe policy error when the routed operation is blocked by its enforcement decision. */
   private assertPolicyAllows(
     operation: ProxiedOperation<unknown>,
     route: RoutingDecision,