docs: document session list web search tools

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;
         }

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,