Preface¶

In the plugin scenario of DSH, a live agent might encounter many global tools. The more tools there are, the longer the tool list presented to the model at once; if all eligible global tools are continuously visible, the schemas of tools not actually used will remain in the request context.

Below is an introduction to an experimental DSH plugin: @deepseek-ai/dsh-tool-search. It is used for per-agent tool discovery and progressive schema disclosure: each live agent can see a scope-local tool_search tool, as well as global tools explicitly marked alwaysVisible; other eligible global tools only become executable after being selected by tool_search.

What is this¶

@deepseek-ai/dsh-tool-search is an experimental external Native Tool Mode plugin. Its core goal is not to replace all tools, but to add a set of on-demand discovery and on-demand loading tool visibility mechanisms in the DSH profile.

Verified data indicates that the package name is @deepseek-ai/dsh-tool-search, marked as version: 0.0.1, private: true, and license: MIT in package.json. This repository is the source of the plugin code but has not been published to the npm registry and is in an unreleased state with no compatibility commitments.

The GitHub repository address used in this article is:

https://github.com/dsh-external/dsh-tool-search

Core Features¶

Tool Visibility¶

This plugin handles global tools in two categories:

• Global tools matched by alwaysVisible remain visible before searching.
• Other eligible global tools do not directly enter the model’s initial visible set by default; they only become executable when tool_search selects them.

tool_search itself is a scope-local tool; what each live agent sees is their own scope’s tool_search and the global tools already visible to that agent.

Search and Selection¶

tool_search accepts a required query and an optional integer limit.

The search rules include:

• Exact callable-name takes priority.
• Name and description matching uses deterministic BM25 matching.
• limit can range from 1 to maxResults, but cannot exceed the upper limit provided by the deployment configuration.
• The model can request a smaller limit, but cannot raise the upper limit beyond the deployment configuration.

Session Events and Invariants¶

A successful expansion writes a tool-search/selection session event. The plugin also loads an invariant companion to check the event shape and enforce that the selection set maintains monotonic cumulative selection.

In other words, subsequent selections cannot arbitrarily backtrack; it should behave as a monotonic change to the cumulative visible set.

Implementation¶

This plugin uses the existing ctx.tools.restrict() seam to restrict the visible tool set, rather than directly modifying agent-loop.

This means it is adding further constraints on the existing tool visibility boundaries in DSH, rather than bypassing existing permissions and filtering mechanisms.

Configuration¶

The plugin can be configured with the following three items:

The following configurations will fail during plugin loading:

• Invalid positive-integer bounds.
• Empty pattern.
• Pattern with whitespace padding.
• Duplicate pattern.

Installation and Enablement¶

Installation Requirements¶

This repository is a private repository, and the package has not been published to the npm registry. Installation requires:

• Git credentials.
• pnpm 11.7.0.
• Installation of a reviewed commit.
• Installation separately for each profile that needs to use the plugin.

DSH profiles are mutually independent. Installing to the web profile does not automatically enable the headless profile.

Installing to a Specific Profile¶

Install the reviewed commit to the headless profile:

dsh plugin --profile headless add -w github:dsh-external/dsh-tool-search#<reviewed-commit>

Install the same reviewed commit to the web profile:

dsh plugin --profile web add -w github:dsh-external/dsh-tool-search#<reviewed-commit>

Where <reviewed-commit> is a placeholder; it should be replaced with the actually reviewed commit during installation.

Pre-Boot Validation¶

After installing to the web profile, execute the following first:

dsh --profile web --dump-config

Before booting the profile, you should confirm that the output includes:

tool-search
tool-search-invariant

After both appear, then start that profile.

Removing the Plugin¶

Remove this bundle from a profile:

dsh plugin --profile <profile> remove -w @deepseek-ai/dsh-tool-search

Typical Usage¶

Configuration Example¶

Below is a configuration example:

- id: tool-search
  name: '@deepseek-ai/dsh-tool-search'
  config:
    alwaysVisible: [read_file, todo_*]
    maxResults: 5
    maxQueryChars: 512

In this configuration:

• read_file is always visible.
• todo_* remains visible as a pattern combining literal characters and wildcards; only * is a wildcard.
• A single search returns at most 5 results.
• The trimmed query submitted by the model is at most 512 JavaScript characters long.

Model Calling tool_search¶

The model can use tool_search as follows:

• Provide the required query.
• Optionally provide an integer limit.
• The allowed range for limit is 1 to maxResults.

If tool_search returns selected tools, these tools will be loaded in the next model request. The model should call these newly loaded tools after the search results are returned.

Search Results and Selection Results¶

After a successful search, the plugin writes a tool-search/selection session event. The invariant companion checks the event shape and ensures subsequent selections maintain monotonic cumulative selection.

If a tool is already visible, it does not enter a new deferred flow due to another search; if it is still blocked by other restrictions, it will not become available just because it was searched for.

Use Cases and Notes¶

Suitable Scenarios¶

This plugin is suitable for DSH usage scenarios where global tool visibility needs to be controlled per agent, particularly:

• Need for the model to actively discover tools via tool_search.
• Desire to keep certain global tools always visible.
• Desire for other eligible global tools to enter subsequent requests only after selection.
• Desire to maintain a scope-local tool discovery interface under Native Tool Mode.

Limitations¶

The following limitations should be noted before use:

• Only supports Native Tool Mode. Calls nested under run_code will fail loudly.
• Search is lexical search only. Embeddings and provider-native search are still deferred.
• Only processes global tools. Agent-scoped tools are already visible by default and do not enter the deferred catalog.
• If an agent starts in a restricted initial global view, the eligible-name set will be frozen; unless alwaysVisible explicitly names a late tool pattern.
• The plugin will not relax other filters. Existing creation-time restrictions, parent/subagent policy, scoped shadows, and other ctx.tools.restrict() calls will continue to intersect.
• This plugin has not been published to the npm registry and is in an unreleased state with no compatibility commitments.

Security Check¶

This plugin joins DSH’s plugin loading chain and runs with the current dsh process permissions. Before installation, check the source code, license, and the source of the reviewed commit.

The verified data for this session indicates its license is MIT, but it is still recommended to review the code and dependencies yourself before actual integration.

Conclusion¶

@deepseek-ai/dsh-tool-search provides an experimental tool discovery layer: it gives each live agent its own tool_search entry, keeps alwaysVisible tools in the initial visible set, and defers the loading of other eligible global tools until after search and selection. For scenarios requiring control over tool visibility ranges, maintenance of monotonic selection sets, and progressive tool disclosure within DSH profiles, it is a plugin direction worth further evaluation.

Related Links:

• GitHub: https://github.com/dsh-external/dsh-tool-search
• Directory Page: The verified data for this session does not include a valid directory page address, so it is not listed here for now.