DSH plugin tools: how DeepSeek Harness registers them

A registered tool in DeepSeek Harness is a ToolDefinition: a schema plus an execute function, with the output declaration required, and parameters and output described by the same JSON value schema (source). Tools are the bridge between the model and the outside world: the model cannot read files or reach the network by itself, it can only request a tool call, and what actually does the work is the execute function registered in the system. This piece covers how a tool is registered, made visible and run; the built-in list is in built-in tools in DeepSeek Harness, writing one is in how to build a tool plugin, and its place in the chain in how one turn runs.

Why tools are the bridge between the model and the world

The model can only produce text: it cannot touch the file system, the network or any external resource, so every outward action must go through a tool — that is the root reason the tool mechanism exists (source). Once that boundary is clear, several things follow:

1. Tools decide "what is possible": how much capability the model can read depends on which tools are registered in the current environment; a capability that is not registered cannot even be conceived of.
2. Tools are where permissions land: because real execution happens inside a tool, "whether an action touches your files" depends on the tool and its constraints, not on what the model said.
3. Tools are the main exit for plugin capability: the most common way a DSH plugin gives the model a new ability is to register a tool — the most visible form of everything-is-a-plugin.

So understanding the tool mechanism is understanding "how much the model can do, who executes it, and what limits it" — three questions in one.

What a tool is: a schema plus an execute function

A registered tool in DeepSeek Harness is a ToolDefinition — a schema plus an execute function, with output required; the execute function runs only on an accepted call and returns a conforming value (source). Three points:

1. The schema defines the boundary: it describes which parameters the tool accepts and what it returns, and is the part the model sees; the model uses it to decide which tool to use and what to pass.
2. output is required: the return value must have an explicit declaration, and results are validated against it, so what the model gets is predictable.
3. The execute function does the work: it runs on a frozen snapshot of arguments and returns a value conforming to output; it does not talk to the model, it just takes arguments and gives a result.

Registration is a trusted in-process contract: the registry validates schema and semantic requirements, then execution and display share the same resolved definition. For writing one, see how to build a tool plugin.

Parameters and output share one schema

DeepSeek Harness describes a tool's parameters and output with the same JSON value schema DSL: the author declares types with one vocabulary, and the compiler turns it into a supported subset of raw JSON Schema (source). Why this helps:

1. Consistent declarations: parameters and output do not use two vocabularies, cutting down on inconsistencies between the two sides.
2. Common types covered: string, number, integer, boolean, null, array, object, and oneOf for exactly one matching branch — enough for most tool shapes.
3. Open by default, tightened under control: raw JSON Schema stays open by default, and unsupported keywords are rejected rather than admitted but unenforced — better to fail early than to leave a declaration that does not take effect.
4. Author-side type inference: because it is one controlled vocabulary, writing declarations with author-side type inference surfaces problems in parameters and output earlier.

How the model sees the tools: schema projected into the prompt

The model "knows" which tools exist because each tool's schema is projected into the per-turn system prompt prefix — what the model reads is the projection from the registry (source). This line explains three things:

1. Register and it is visible: once a tool is registered, its schema joins prefix assembly, so the model can see it in later turns.
2. More tools, longer prefix: every extra tool means another description in the prefix, a main source of context overhead; see system prompt explained.
3. Changing the schema changes the model's basis for acting: adjusting parameter descriptions does not just change documentation, it changes when and how the model uses the tool.

The execution pipeline: waterfall makes execution wrappable

Tool execution runs through an extensible waterfall event pipeline that applies monotonic policy, with each step processed in waterfall semantics (source). Why waterfall rather than a direct call:

1. Execution can be wrapped: there are steps before and after the actual function, so a plugin can step in — wrapping, recording or adding constraints — without changing the tool itself.
2. Monotonic policy never loosens: policy on the pipeline tightens downstream; a later step can add restrictions but cannot undo what an earlier step fixed, so constraints only accumulate.
3. ctx.tools is the service entry: registration, schema projection and dispatch are all exposed there, so a DSH plugin joins the tool lifecycle without editing the core.

Scope filtering: how ToolRestriction narrows visibility

In DeepSeek Harness, ToolRestriction is a scope's live filter over the tools it inherits: it narrows the visible set by name, multiple restrictions intersect, and that scope's own registrations are unaffected (source). Three points:

1. It applies only to inherited tools: it filters the set inherited from above, not the tools the scope registers itself.
2. Multiple restrictions intersect: stacked restrictions only narrow the set, never widen it — the same idea as the pipeline's monotonic policy.
3. Sub-scopes therefore have their own view: a delegated sub-agent can work in a narrower set while still keeping the tools it needs to report back — which is exactly why its own registrations are not constrained.

Notes on the tool pipeline

Read a tool as "schema + execute function + wrapping pipeline" and things stop blurring.

1. The model only sees the schema: descriptions and parameters are the model-visible part; execution details stay off the protocol.
2. output cannot be omitted: the return value must be declared so results can be validated.
3. Registration is a trusted contract: the in-process registry validates schema and semantics; do not expect the system to rescue a non-conforming definition.
4. Execution can be wrapped: the waterfall design leaves room for plugins to cooperate, and constraints can be tightened downstream.
5. Visibility can be narrowed per scope: ToolRestriction decides which inherited tools a scope sees, and multiple restrictions intersect.
6. More tools, longer prefix: registering a tool adds both capability and context cost, so weigh them together.
7. For the built-in list, see the how-to: which tools exist is in built-in tools; where tools sit in the chain is in how one turn runs.

Source: DeepSeek Harness docs - tools subsystem, docs - core subsystems.