fix(agents): identify Tool Search counter lifetimes (#116070)

* fix(agents): scope Tool Search telemetry counters

* fix(agents): keep tool-search scopes visible

* docs(tool-search): document counter scopes

---------

Co-authored-by: Peter Steinberger <steipete@macos.shared>

docs/tools/code-mode.md

@@ -991,6 +991,9 @@ Each result's `telemetry` field reports: hidden catalog size and a source
 breakdown (`openclaw`/`mcp`/`client` counts), cumulative search/describe/call
 counts for the run's catalog, and the model-visible tool names (`exec`,
 `wait`, and retained direct-only tools).
+The `counterScope` identifies one counter lifetime, changing when a catalog is
+replaced or restored but remaining stable when tools are appended or prompt
+policy narrows that catalog.
 
 The run metadata (`meta.agentMeta` in `openclaw agent --json`, mirrored on the
 `agent exec --json` envelope) adds per-run stats:

docs/tools/tool-search.md

@@ -331,6 +331,9 @@ Code mode attaches a `telemetry` object to every `tool_search_code` result:
 
 - `catalogSize`: number of catalog entries the runtime resolved
 - `sources`: catalog entry counts split into `openclaw`, `mcp`, and `client`
+- `counterScope`: opaque identifier for the counter lifetime; it stays stable
+  when tools are appended or prompt policy narrows the catalog, and changes
+  when the catalog is replaced or restored
 - `searchCount`, `describeCount`, `callCount`: running totals for the catalog
   session, carried across calls rather than reset per call