OpenClaw Tool Search

Tool Search is OpenClaw’s answer to a catalog that has grown past what a prompt should carry: an experimental agent runtime feature that gives the model one compact way to discover and call a large set of tools, useful when a run has many available tools but will need only a few. The docs separate it from the Codex-native surfaces and from Code Mode, which exposes a JavaScript exec and wait pair instead. Here is what the model sees, how a turn runs, the three modes, the API, the runtime boundary, and the configuration.

What the model sees

• A bounded directory of trusted tool names and descriptions, sorted by name, capped at 18,000 characters, placed above the system-prompt cache boundary so repeated turns stay cache-eligible; when space is tight, descriptions shorten before names are omitted, and every authorized entry stays searchable and callable.
• With the feature set to true, one code tool that runs a short JavaScript body in an isolated Node subprocess with a bridge offering search, describe and call, plus any direct-only tools whose structured results cannot cross the compact bridge.
• The catalog can hold core tools, plugin tools, MCP tools and client-provided tools; the untrusted names and descriptions of MCP and client tools are never copied into the system prompt, the model searches compact descriptors instead and describes one tool when it needs the exact schema.
• Local inference routes, Ollama, LM Studio and managed local services, use structured Tool Search automatically when the setting is unset, with a default search limit of five and a maximum of ten, and hosted Ollama routes are excluded from that default.

Large catalogs are useful but expensive.

How a turn runs

At planning time the embedded runner resolves the active tool policy for the agent, profile, sandbox and session, lists the eligible core and plugin tools, the eligible MCP tools through the session MCP runtime, and the client tools for the run, keeps core coding primitives and direct-only tools model-visible, indexes compact descriptors for the rest, adds a deterministic, policy-filtered capability directory to the cache-stable prompt prefix, and exposes the bridge or the structured fallback tools beside the directly callable tools. At execution time every real tool call returns to OpenClaw: the isolated Node runtime holds no plugin implementations, no MCP client objects and no secrets, and a call crosses the bridge back into the Gateway where the normal policy, approvals, hooks, logging and result handling apply. The reason the feature exists is the quote above: sending every schema makes the request larger, slows planning and increases accidental tool selection.

Modes and the API

• Code mode, the default, exposes the code tool; tools mode exposes search, describe and call as plain structured tools for providers that should not receive code; directory mode exposes those three plus the bounded prompt directory, keeping core primitives, direct-only tools and delivery-policy tools visible while other schemas stay deferred. If the isolated child process cannot launch, code mode falls back to tools mode.
• Search is lexical, BM25 over names, descriptions and first-party parameter text with light English stemming and a small intent expansion, so queries must be in English; untrusted parameter schemas are never indexed, each hit carries a bounded TypeScript-style input signature, trusted core and plugin tools may add a compact output hint, and MCP and client inputs stay deferred as unknown until described. A batch shape takes up to sixteen queries, fifty candidates in total, within a 4,000-character response budget that marks truncation.
• Call validates a trusted tool’s declared input schema before execution, returning actionable errors for missing or mistyped arguments with a suggested parameter for misspellings, and validates a declared output schema after the normal hooks; in structured mode it also repairs flattened target arguments from local models and rejects ambiguous selectors.

OpenClaw Code Mode is the sibling feature for models that write programs rather than search, and OpenClaw and MCP explains the servers whose tools this catalog can include.

Runtime boundary and config

The code bridge runs in a short-lived Node subprocess started with permission mode on, an empty environment, no filesystem, network, child-process or worker grants, and a parent-enforced wall-clock timeout; it exposes only the console methods and the three bridge functions, and final calls still obey allow and deny policies, per-agent and per-sandbox restrictions, channel policy, approval hooks and plugin hooks. Configuration is one key: true for the code bridge, a mode of tools or directory, a code timeout of ten seconds by default within one to sixty, a default search limit of eight and a maximum of twenty within one to fifty, or false to disable; an explicit value wins over the local-model default. Failure is closed by design: a tool outside the effective policy is never returned by search, a tool that becomes unavailable fails at call time, and a blocked execution reports the block rather than bypassing it. OpenClaw local models is where the automatic default matters most, and OpenClaw skills explained explains the other thing a catalog search can confuse with a tool, a skill name.

On Diali

On Diali the catalog an assistant sees is the one you assembled from skills, MCP servers and connectors, and Tool Search stays at the upstream default for the model in use, so a local-model assistant gets the compact surface without a setting. Hosted OpenClaw on Diali is the assistant.

• A bounded directory instead of every schema.
• Search in English, describe when you need the schema, call through the Gateway.
• Fails closed: policy filters the search, not just the call.