From 2cbaacda43839031e82fac9ea416945a306d79c3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 10:14:36 -0400
Subject: [PATCH] docs: document built-in tool helpers

---
 src/agents/tool-mutation.ts                          |  5 +++++
 src/agents/tool-policy-shared.ts                     | 11 +++++------
 src/agents/tools/agent-step.ts                       | 11 +++++------
 src/agents/tools/agents-list-tool.ts                 |  5 +++++
 src/agents/tools/chat-history-text.ts                |  5 +++++
 src/agents/tools/common.ts                           |  5 +++++
 src/agents/tools/cron-tool-canonicalize.ts           |  5 +++++
 src/agents/tools/cron-tool.ts                        |  9 +++++++--
 src/agents/tools/embedded-gateway-stub.ts            | 11 +++++------
 src/agents/tools/gateway-schema.ts                   | 11 +++++------
 src/agents/tools/gateway-tool.ts                     |  5 +++++
 src/agents/tools/goal-tools.ts                       | 11 +++++------
 src/agents/tools/image-generate-background.ts        | 11 +++++------
 src/agents/tools/image-generate-tool.actions.ts      |  8 +++++---
 src/agents/tools/image-generate-tool.ts              |  5 +++++
 src/agents/tools/image-tool.helpers.ts               | 10 +++++-----
 src/agents/tools/image-tool.ts                       |  5 +++++
 src/agents/tools/manifest-capability-availability.ts | 11 +++++------
 18 files changed, 92 insertions(+), 52 deletions(-)

diff --git a/src/agents/tool-mutation.ts b/src/agents/tool-mutation.ts
index 3c7557a4acf6..2ecfb63e93ca 100644
--- a/src/agents/tool-mutation.ts
+++ b/src/agents/tool-mutation.ts
@@ -1,3 +1,8 @@
+/**
+ * Tool mutation classification and fingerprinting.
+ *
+ * Identifies mutating tool calls and file targets so retry/recovery logic can reason about side effects.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
diff --git a/src/agents/tool-policy-shared.ts b/src/agents/tool-policy-shared.ts
index 1c05634c4a03..89facfb87f6e 100644
--- a/src/agents/tool-policy-shared.ts
+++ b/src/agents/tool-policy-shared.ts
@@ -1,3 +1,8 @@
+/**
+ * Shared runtime tool policy normalization.
+ *
+ * Keeps aliases, groups, profile expansion, and prefix matching consistent across allow/deny paths.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import {
@@ -6,12 +11,6 @@ import {
   type ToolProfileId,
 } from "./tool-catalog.js";
 
-/**
- * Shared normalization helpers for runtime tool policy.
- *
- * Aliases and groups live here so allowlist parsing, prefix matching, and
- * profile expansion resolve names consistently.
- */
 type ToolProfilePolicy = {
   allow?: string[];
   deny?: string[];
diff --git a/src/agents/tools/agent-step.ts b/src/agents/tools/agent-step.ts
index 712ab6187705..6a45a02afb65 100644
--- a/src/agents/tools/agent-step.ts
+++ b/src/agents/tools/agent-step.ts
@@ -1,3 +1,8 @@
+/**
+ * Nested agent-step executor.
+ *
+ * Sends annotated inter-session messages through in-process or Gateway execution and reads the assistant reply.
+ */
 import crypto from "node:crypto";
 import { callGateway } from "../../gateway/call.js";
 import { annotateInterSessionPromptText } from "../../sessions/input-provenance.js";
@@ -6,12 +11,6 @@ import { retireSessionMcpRuntimeForSessionKey } from "../agent-bundle-mcp-tools.
 import { resolveNestedAgentLaneForSession } from "../lanes.js";
 import { waitForAgentRunAndReadUpdatedAssistantReply } from "../run-wait.js";
 
-/**
- * Runs a single nested agent step for sessions_send and related inter-session flows.
- *
- * The helper supports both in-process command execution and Gateway execution,
- * then waits for the updated assistant reply when the Gateway path is used.
- */
 export { readLatestAssistantReply } from "../run-wait.js";
 
 type GatewayCaller = typeof callGateway;
diff --git a/src/agents/tools/agents-list-tool.ts b/src/agents/tools/agents-list-tool.ts
index 8f98a7dadef7..8870602ebf0f 100644
--- a/src/agents/tools/agents-list-tool.ts
+++ b/src/agents/tools/agents-list-tool.ts
@@ -1,3 +1,8 @@
+/**
+ * agents_list built-in tool.
+ *
+ * Lists configured or allowed agent ids plus model/runtime metadata for subagent spawn decisions.
+ */
 import { Type } from "typebox";
 import { getRuntimeConfig } from "../../config/config.js";
 import {
diff --git a/src/agents/tools/chat-history-text.ts b/src/agents/tools/chat-history-text.ts
index 1ac2d45009cd..cc528312fb14 100644
--- a/src/agents/tools/chat-history-text.ts
+++ b/src/agents/tools/chat-history-text.ts
@@ -1,3 +1,8 @@
+/**
+ * Chat-history text helpers for session tools.
+ *
+ * Removes tool messages and extracts sanitized assistant-visible text from stored messages.
+ */
 import { extractAssistantTextForPhase } from "../../shared/chat-message-content.js";
 import { sanitizeAssistantVisibleTextWithProfile } from "../../shared/text/assistant-visible-text.js";
 import { sanitizeUserFacingText } from "../embedded-agent-helpers/sanitize-user-facing-text.js";
diff --git a/src/agents/tools/common.ts b/src/agents/tools/common.ts
index ce264ef1c107..b775a97c6b72 100644
--- a/src/agents/tools/common.ts
+++ b/src/agents/tools/common.ts
@@ -1,3 +1,8 @@
+/**
+ * Shared built-in tool contracts and helpers.
+ *
+ * Defines erased tool types, parameter readers, JSON results, progress blocks, and media sanitization.
+ */
 import { detectMime } from "@openclaw/media-core/mime";
 import {
   asPositiveSafeInteger,
diff --git a/src/agents/tools/cron-tool-canonicalize.ts b/src/agents/tools/cron-tool-canonicalize.ts
index 977db3b0c730..d06a026e56e4 100644
--- a/src/agents/tools/cron-tool-canonicalize.ts
+++ b/src/agents/tools/cron-tool-canonicalize.ts
@@ -1,3 +1,8 @@
+/**
+ * Cron tool argument canonicalization.
+ *
+ * Recovers flat or partial model/tool inputs into the structured cron job/patch shape.
+ */
 import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";
 import { isRecord } from "../../utils.js";
 
diff --git a/src/agents/tools/cron-tool.ts b/src/agents/tools/cron-tool.ts
index c846467953b0..9ac0c7f396e3 100644
--- a/src/agents/tools/cron-tool.ts
+++ b/src/agents/tools/cron-tool.ts
@@ -1,3 +1,8 @@
+/**
+ * cron built-in tool.
+ *
+ * Manages scheduled jobs, wake/run actions, delivery context, and reminder-style payload normalization.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { Type, type TSchema } from "typebox";
 import { getRuntimeConfig } from "../../config/config.js";
@@ -34,8 +39,8 @@ import { gatewayCallOptionSchemaProperties } from "./gateway-schema.js";
 import { callGatewayTool, readGatewayCallOptions, type GatewayCallOptions } from "./gateway.js";
 import { resolveInternalSessionKey, resolveMainSessionAlias } from "./sessions-helpers.js";
 
-// We spell out job/patch properties so that LLMs know what fields to send.
-// Nested unions are avoided; runtime validation happens in normalizeCronJob*.
+// Spell out job/patch properties for model-facing schema; runtime validation
+// still happens in normalizeCronJob* to avoid nested union schemas.
 
 const CRON_ACTIONS = [
   "status",
diff --git a/src/agents/tools/embedded-gateway-stub.ts b/src/agents/tools/embedded-gateway-stub.ts
index 9ecfcb77e012..a9a4c257221a 100644
--- a/src/agents/tools/embedded-gateway-stub.ts
+++ b/src/agents/tools/embedded-gateway-stub.ts
@@ -1,3 +1,8 @@
+/**
+ * Embedded-mode Gateway method stub.
+ *
+ * Implements only the Gateway calls needed by session tools and rejects unsupported methods.
+ */
 import type {
   SessionsListParams,
   SessionsResolveParams,
@@ -10,12 +15,6 @@ import type { SessionsResolveResult } from "../../gateway/sessions-resolve.js";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
 import { readPositiveIntegerParam } from "./common.js";
 
-/**
- * Local Gateway method stub used when session tools run in embedded mode.
- *
- * It implements only the Gateway methods needed by session tools and rejects
- * everything else so callers do not accidentally depend on partial behavior.
- */
 type EmbeddedCallGateway = <T = Record<string, unknown>>(opts: CallGatewayOptions) => Promise<T>;
 
 interface EmbeddedGatewayRuntime {
diff --git a/src/agents/tools/gateway-schema.ts b/src/agents/tools/gateway-schema.ts
index 6e1efb7c4f9d..c12bbc0784d1 100644
--- a/src/agents/tools/gateway-schema.ts
+++ b/src/agents/tools/gateway-schema.ts
@@ -1,12 +1,11 @@
+/**
+ * Shared Gateway tool schema fragments.
+ *
+ * Keeps gateway URL/token/timeout parameters aligned across tools that call Gateway methods.
+ */
 import { Type } from "typebox";
 import { optionalPositiveIntegerSchema } from "../schema/typebox.js";
 
-/**
- * Shared TypeBox schema fragments for tools that call the Gateway.
- *
- * Keeping gateway options centralized prevents drift between tool schemas and
- * gateway call option parsing.
- */
 /** Returns optional gateway URL/token/timeout schema properties for tool params. */
 export function gatewayCallOptionSchemaProperties() {
   return {
diff --git a/src/agents/tools/gateway-tool.ts b/src/agents/tools/gateway-tool.ts
index c529f7b946df..93d357d4d426 100644
--- a/src/agents/tools/gateway-tool.ts
+++ b/src/agents/tools/gateway-tool.ts
@@ -1,3 +1,8 @@
+/**
+ * gateway built-in tool.
+ *
+ * Exposes selected Gateway control/config/update actions with fail-closed config mutation boundaries.
+ */
 import { isDeepStrictEqual } from "node:util";
 import { isRecord as isPlainObject } from "@openclaw/normalization-core/record-coerce";
 import {
diff --git a/src/agents/tools/goal-tools.ts b/src/agents/tools/goal-tools.ts
index 3f800b200599..b7b31d3a2fde 100644
--- a/src/agents/tools/goal-tools.ts
+++ b/src/agents/tools/goal-tools.ts
@@ -1,3 +1,8 @@
+/**
+ * Model-facing thread goal tools.
+ *
+ * Provides create/get/update goal operations scoped to the current session store.
+ */
 import { Type } from "typebox";
 import {
   createSessionGoal,
@@ -17,12 +22,6 @@ import {
   readStringParam,
 } from "./common.js";
 
-/**
- * Model-facing thread goal tools.
- *
- * Goal state is scoped to the current session store so agents can inspect,
- * create, or close a persistent objective without direct store access.
- */
 type GoalToolOptions = {
   agentSessionKey?: string;
   runSessionKey?: string;
diff --git a/src/agents/tools/image-generate-background.ts b/src/agents/tools/image-generate-background.ts
index cf6568961053..3516261552f3 100644
--- a/src/agents/tools/image-generate-background.ts
+++ b/src/agents/tools/image-generate-background.ts
@@ -1,3 +1,8 @@
+/**
+ * Image generation background task facade.
+ *
+ * Binds shared detached media-task lifecycle behavior to image_generate labels and completion messages.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { AgentGeneratedAttachment } from "../generated-attachments.js";
 import { IMAGE_GENERATION_TASK_KIND } from "../image-generation-task-status.js";
@@ -6,12 +11,6 @@ import {
   type MediaGenerationTaskHandle,
 } from "./media-generate-background-shared.js";
 
-/**
- * Image-generation-specific facade over the shared media generation task lifecycle.
- *
- * This binds shared detached-task behavior to image task labels, event source,
- * and completion wording used by image_generate.
- */
 /** Detached image generation task handle. */
 export type ImageGenerationTaskHandle = MediaGenerationTaskHandle;
 
diff --git a/src/agents/tools/image-generate-tool.actions.ts b/src/agents/tools/image-generate-tool.actions.ts
index 30bcf4f9e8ca..8f9794beef6a 100644
--- a/src/agents/tools/image-generate-tool.actions.ts
+++ b/src/agents/tools/image-generate-tool.actions.ts
@@ -1,3 +1,8 @@
+/**
+ * image_generate action helpers.
+ *
+ * Handles provider listing, task status, and duplicate-guard output for the image generation tool.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { listRuntimeImageGenerationProviders } from "../../image-generation/runtime.js";
 import type { ImageGenerationProvider } from "../../image-generation/types.js";
@@ -17,9 +22,6 @@ import {
   type MediaGenerateActionResult,
 } from "./media-generate-tool-actions-shared.js";
 
-/**
- * Image-generation list/status/duplicate-guard action helpers.
- */
 export type ImageGenerateActionResult = MediaGenerateActionResult;
 
 /** Formats provider auth setup hints for the image generation `list` action. */
diff --git a/src/agents/tools/image-generate-tool.ts b/src/agents/tools/image-generate-tool.ts
index 1f108f6671d4..ffd965ec89ba 100644
--- a/src/agents/tools/image-generate-tool.ts
+++ b/src/agents/tools/image-generate-tool.ts
@@ -1,3 +1,8 @@
+/**
+ * image_generate built-in tool.
+ *
+ * Loads references, resolves providers/options, saves generated images, and supports detached background runs.
+ */
 import { Type } from "typebox";
 import { getRuntimeConfig } from "../../config/config.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/agents/tools/image-tool.helpers.ts b/src/agents/tools/image-tool.helpers.ts
index 07b28ea9d705..3c8533d96625 100644
--- a/src/agents/tools/image-tool.helpers.ts
+++ b/src/agents/tools/image-tool.helpers.ts
@@ -1,3 +1,8 @@
+/**
+ * Image/media understanding helper functions.
+ *
+ * Handles model config, data URL decoding, provider lookup, and reasoning-only response validation.
+ */
 import { estimateBase64DecodedBytes } from "@openclaw/media-core/base64";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
@@ -7,11 +12,6 @@ import { isMinimaxVlmProvider } from "../minimax-vlm.js";
 import { findNormalizedProviderValue, normalizeProviderId } from "../model-selection.js";
 import { coerceToolModelConfig, type ToolModelConfig } from "./model-config.helpers.js";
 
-/**
- * Shared image-tool helpers for model selection, data URL decoding, and response validation.
- *
- * These helpers are reused by image, PDF, and media factory paths.
- */
 /** Image tool model config uses the shared tool model config shape. */
 export type ImageModelConfig = ToolModelConfig;
 
diff --git a/src/agents/tools/image-tool.ts b/src/agents/tools/image-tool.ts
index 6883648be70b..7391add17822 100644
--- a/src/agents/tools/image-tool.ts
+++ b/src/agents/tools/image-tool.ts
@@ -1,3 +1,8 @@
+/**
+ * image built-in tool.
+ *
+ * Describes local, staged, web, and generated media through configured media-understanding providers.
+ */
 import { resolve, isAbsolute } from "node:path";
 import { Type } from "typebox";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/agents/tools/manifest-capability-availability.ts b/src/agents/tools/manifest-capability-availability.ts
index d82796c66d32..a79ba1b9a205 100644
--- a/src/agents/tools/manifest-capability-availability.ts
+++ b/src/agents/tools/manifest-capability-availability.ts
@@ -1,3 +1,8 @@
+/**
+ * Manifest capability availability checks.
+ *
+ * Combines plugin contracts, availability, config signals, auth profiles, env candidates, and base URL guards.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { getCurrentPluginMetadataSnapshot } from "../../plugins/current-plugin-metadata-snapshot.js";
 import { isManifestPluginAvailableForControlPlane } from "../../plugins/manifest-contract-eligibility.js";
@@ -14,12 +19,6 @@ import { getActivePluginRegistryWorkspaceDirFromState } from "../../plugins/runt
 import { listProfilesForProvider } from "../auth-profiles/profile-list.js";
 import type { AuthProfileStore } from "../auth-profiles/types.js";
 
-/**
- * Manifest capability availability checks for media/web-style tools.
- *
- * These helpers combine plugin contracts, plugin availability, config signals,
- * auth profiles, env candidates, and provider base URL guards.
- */
 /** Manifest contract keys that represent provider-backed tool capabilities. */
 export type CapabilityContractKey =
   | "imageGenerationProviders"