From 376bf65d8e40ce526fb7de6c14d128d5f96f281d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 01:10:37 -0400
Subject: [PATCH] docs: document session list web search tools

---
 src/agents/tools/sessions-list-tool.ts | 9 +++++++++
 src/agents/tools/web-search.ts         | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/src/agents/tools/sessions-list-tool.ts b/src/agents/tools/sessions-list-tool.ts
index 10bf58ccea49..469d54081b76 100644
--- a/src/agents/tools/sessions-list-tool.ts
+++ b/src/agents/tools/sessions-list-tool.ts
@@ -49,6 +49,12 @@ import {
   stripToolMessages,
 } from "./sessions-helpers.js";
 
+/**
+ * `sessions_list` tool for visible session discovery and optional transcript hydration.
+ *
+ * Visibility filtering happens before derived titles/last messages are read so sandboxed agents do
+ * not learn metadata from sessions they cannot address.
+ */
 const SessionsListToolSchema = Type.Object({
   kinds: Type.Optional(Type.Array(Type.String())),
   limit: optionalPositiveIntegerSchema(),
@@ -75,6 +81,7 @@ function readSessionRunStatus(value: unknown): SessionRunStatus | undefined {
     : undefined;
 }
 
+/** Creates the sessions-list tool with gateway-backed listing and local transcript enrichment. */
 export function createSessionsListTool(opts?: {
   agentSessionKey?: string;
   sandboxed?: boolean;
@@ -180,6 +187,8 @@ export function createSessionsListTool(opts?: {
           continue;
         }
 
+        // Gateway listings include pseudo/global rows for UI callers. The tool only exposes real
+        // sessions and the explicit global session when the requester is already global.
         if (key === "unknown") {
           continue;
         }
diff --git a/src/agents/tools/web-search.ts b/src/agents/tools/web-search.ts
index 1a87aa230c3f..16b247aab6a6 100644
--- a/src/agents/tools/web-search.ts
+++ b/src/agents/tools/web-search.ts
@@ -6,6 +6,9 @@ import { asToolParamsRecord, jsonResult } from "./common.js";
 import { MAX_SEARCH_COUNT, SEARCH_CACHE } from "./web-search-provider-common.js";
 import { resolveWebSearchToolRuntimeContext } from "./web-tool-runtime-context.js";
 
+/**
+ * Web search tool wrapper over the configured runtime web-search provider.
+ */
 const WebSearchSchema = {
   type: "object",
   required: ["query"],
@@ -69,6 +72,7 @@ function isWebSearchDisabled(config?: OpenClawConfig): boolean {
   return Boolean(search && typeof search === "object" && search.enabled === false);
 }
 
+/** Creates the `web_search` tool, or `null` when web search is disabled by config. */
 export function createWebSearchTool(options?: {
   config?: OpenClawConfig;
   agentDir?: string;
@@ -86,6 +90,8 @@ export function createWebSearchTool(options?: {
     description: "Search web for current info; returns normalized provider results.",
     parameters: WebSearchSchema,
     execute: async (_toolCallId, args, signal) => {
+      // Late binding lets long-lived agents pick up runtime web-search credentials/config without
+      // rebuilding the tool object.
       const { config, preferRuntimeProviders, runtimeWebSearch } =
         resolveWebSearchToolRuntimeContext({
           config: options?.config,