diff --git a/src/agents/tools/message-tool.test.ts b/src/agents/tools/message-tool.test.ts
index f7616f12a83d..2f3e95223963 100644
--- a/src/agents/tools/message-tool.test.ts
+++ b/src/agents/tools/message-tool.test.ts
@@ -1,3 +1,5 @@
+// Message tool tests cover channel action discovery, secret scoping, and
+// outbound message execution context.
 import { Type } from "typebox";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ChannelMessageAdapterShape } from "../../channels/message/types.js";
@@ -144,6 +146,8 @@ function latestSecretResolveCall(): {
   if (!call) {
     throw new Error("expected secret resolution call");
   }
+  // Secret resolution is scoped to the active channel/account; tests inspect
+  // the exact target set to avoid broad credential reads.
   return call[0] as {
     allowedPaths?: Set<string>;
     config?: unknown;
diff --git a/src/agents/tools/skill-workshop-tool.test.ts b/src/agents/tools/skill-workshop-tool.test.ts
index 574a5cec3418..ba6413a371e2 100644
--- a/src/agents/tools/skill-workshop-tool.test.ts
+++ b/src/agents/tools/skill-workshop-tool.test.ts
@@ -1,3 +1,5 @@
+// skill_workshop tests cover proposal creation/revision/listing without
+// applying generated skills to the workspace.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -63,6 +65,8 @@ describe("skill_workshop tool", () => {
   });
 
   it("creates pending skill proposals without applying them", async () => {
+    // Creation writes reviewable proposal artifacts under state, not live skill
+    // files in the workspace.
     const workspaceDir = await tempDirs.make("openclaw-skill-workshop-tool-");
     const tool = createSkillWorkshopTool({
       workspaceDir,
diff --git a/src/agents/tools/subagents-tool.test.ts b/src/agents/tools/subagents-tool.test.ts
index b52dee1f9056..50ef7c2ca8ba 100644
--- a/src/agents/tools/subagents-tool.test.ts
+++ b/src/agents/tools/subagents-tool.test.ts
@@ -1,8 +1,12 @@
+// Subagents tool tests cover requester-scoped listing guidance and numeric
+// status-window validation.
 import { describe, expect, it } from "vitest";
 import { createSubagentsTool } from "./subagents-tool.js";
 
 describe("subagents tool", () => {
   it("does not advertise sessions_yield as unconditionally available", () => {
+    // sessions_yield is context-dependent; the model-facing description should
+    // not promise it exists in every runtime.
     const tool = createSubagentsTool();
 
     expect(tool.description).toBe(
diff --git a/src/agents/tools/transcripts-tool.test.ts b/src/agents/tools/transcripts-tool.test.ts
index f7551beaada7..5ff45bc33f9f 100644
--- a/src/agents/tools/transcripts-tool.test.ts
+++ b/src/agents/tools/transcripts-tool.test.ts
@@ -1,3 +1,5 @@
+// Transcripts tool tests cover manual imports, live provider lifecycle, summary
+// artifacts, and date-qualified session selectors.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -101,6 +103,8 @@ describe("transcripts tool", () => {
   });
 
   it("bounds summary input while retaining the full transcript", async () => {
+    // Summary generation uses a bounded utterance window, but the durable JSONL
+    // transcript must retain every utterance.
     const stateDir = await makeStateDir();
     const { tool } = await createHarness(stateDir, { maxUtterances: 1 });
 
@@ -159,6 +163,8 @@ describe("transcripts tool", () => {
   });
 
   it("stops date-qualified active sessions with the canonical provider session id", async () => {
+    // Date-qualified selectors disambiguate storage paths; providers still own
+    // the original session id.
     const stateDir = await makeStateDir();
     const start = vi.fn(async (request) => {
       await request.onUtterance({