DeepSeek Harness Cookbook: Add a Tool Step by Step
The official Cookbook shows a minimal tool that runs, but “runs” and “the model sees and uses it” are different claims. This walkthrough follows the Cookbook order, then adds the three checks and five policy hooks it does not spell out. The existing API contracts are in develop-tool-plugin and develop-tool-execute-contract; this article is about doing the build and proving it.
DeepSeek Harness: The minimal tool
A tool needs four things: a name, a model-facing description, a parameter schema, and an output schema. The official minimal shape looks like this (source):
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'my-tool'
export const inject = ['tools']
export function apply(ctx) {
ctx.tools.register(defineTool({
name: 'read_file',
description: 'Read a file from disk.',
parameters: {
path: { type: 'string', required: true },
limit: { type: 'number' },
},
output: {
schema: { type: 'string' },
render: (_args, value) => [{ type: 'text', text: value }],
},
async execute(args, exec) {
return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
},
}))
}
inject declares the ctx.tools dependency, apply registers, and the registration is a side effect. When the plugin unloads, the registration is removed with the fiber; there is no manual unregister.
The minimal form proves the declaration is complete. It does not prove the model will use it. The name must describe an action, the description must say when to use it, and the parameters must be fillable.
DeepSeek Harness: Four rules for execute
execute is not an ordinary function; the registry constrains it in four ways. The official rules prevent most “registered but not working” cases (source):
- Arguments are already validated — defineTool validates model arguments before execute runs; add checks for non-empty strings, positive numbers, or cross-field rules and reject with ToolArgsError.
- Registration borrows a read-only definition — do not mutate the schema or replace the callback after registering; dispose and register a replacement for a hot swap.
- Return a canonical JSON value — return the value declared by output.schema, not content blocks or prose; the registry snapshots, validates, and freezes it before render.
- Respect exec.signal — propagate the signal reason or AbortError so the registry records TOOL_ABORTED; do not replace it with a generic Error.
The common thread is treating the tool as one stage in a pipeline. Arguments, identity, return value, and cancellation each have an owner; crossing a boundary fails somewhere downstream.
Two optional additions help: throwing a HarnessError subclass with a stable code preserves the error name and code, and presentationMeta can derive replayable card data from the same canonical value.
DeepSeek Harness: Long-running work and ctx.jobs
Whether to background a tool depends on whether it must outlive the current call. The Cookbook controls run_in_background through producer config, then registers with ctx.jobs.start({ kind, label, owner, run }) (source).
Three cases:
- Seconds — do it in the foreground and return the result.
- Minutes, result needed — stay foreground but honor
exec.signalso cancellation works. - Cross-turn or user-inspectable — hand it to
ctx.jobs, return a handle, and letjob_*tools manage it.
After backgrounding, cancellation changes. Once ctx.jobs.start() publishes an id, use the job's own signal, not exec.signal. Cancelling the outer call stops waiting, not the published work; lifecycle belongs to job_kill, owner dispose, and teardown.
Getting this wrong produces “I cancelled but it is still running” or “the task returned but the background still writes.” The first treats the outer signal as the job signal; the second never hands out the job handle.
DeepSeek Harness: Five policy and observation hooks
Do not bake deployment policy into the tool; use the pipeline hooks. The five official positions have different jobs (source):
| Hook | Use it for | Do not use it for |
|---|---|---|
| tools/pre-execute | Extensible allow/reject/ask policy | Business logic |
| ctx.tools.guard() | Final monotonic rejection | Reversible temporary checks |
| tools/execute | Deadlines, retries, metrics | Changing the return value |
| tools/post-execute | Replacing display, blocking results, adding context | Bypassing programmatic access |
| tools/result | Observing the immutable result | Modifying it |
The order is fixed: pre-execute before dispatch, guard as the final rejection, execute around dispatch, post-execute for display, result for observation. Putting policy in the wrong place often means “it looks enforced, but programmatic calls bypass it.”
A useful rule: the tool body does “how to do this,” while policy and observation live in the plugin layer. One tool can then use different permissions and metrics in different deployments.
DeepSeek Harness: UI cards and PTC: two extra checks
A tool that returns a result is not automatically usable in the UI or PTC. The Cookbook treats both as separate concerns (source):
- UI cards — output.render decides what the model sees; UI cards come from presentCall and presentResult. A tool without them falls back to a generic card with the name and raw args.
- PTC mode — every visible tool becomes callable as
await tools.<name>(args); output.schema is also the programmatic return type, so do not hide handles in prose.
Both fail after “the model can call it.” A tool may return human-readable text that satisfies the model, while the UI shows raw JSON or PTC cannot find the structured id.
Design all three views together: what the model sees, what the user sees, and what a program gets. They can differ, but each needs a decision rather than a default.
DeepSeek Harness: Three checks after the build
After adding a tool, verify in three steps; “no error” is not enough. Three checks (source):
- Schema reaches the prompt — the name, description, and parameters appear in the model-visible tool list. If not, check inject and registration.
- The model calls it — trigger a task that clearly needs the tool. If the model does not call it, improve the description and parameter docs before doubting registration.
- The result renders — check output.render, the UI card fallback, and whether PTC gets the canonical value.
All three make the tool usable. Passing only the first is “registered but ignored”; passing the first two is “the model used it but the user cannot read it”; all three move you to tuning.
Compare with the existing articles: develop-tool-plugin covers how to organize tools inside a plugin, and develop-tool-execute-contract covers execute details. This article covers the Cookbook walkthrough and verification. Together they prevent “it registered” from being mistaken for “it works.”
FAQ
In DeepSeek Harness, declare name, description, parameters, output, and execute with defineTool, register it through ctx.tools.register in apply, and declare inject. Registration is a side effect that unloads with the plugin.
DeepSeek Harness supports that. DeepSeek Harness defineTool validates model arguments for type, required keys, and literal constraints; constraints the schema cannot express still need ToolArgsError in execute.
In DeepSeek Harness, return the canonical JSON value declared by output.schema, not content blocks or prose. DeepSeek Harness snapshots and validates it, then passes it to output.render for the model.
In DeepSeek Harness, check three places: the schema reaches prompt assembly, the model can call the tool, and the result renders through output.render. All three prove the tool is usable, not just registered.
Related Terms
- defineTool
- defineTool is the DeepSeek Harness API for declaring a model-facing tool with name, description, parameters, output, and execute.— DeepSeek Harness reference - Adding a tool
- ctx.tools.register
- ctx.tools.register is the DeepSeek Harness call that registers a tool; it is a plugin side effect and is removed when the plugin fiber unloads.— DeepSeek Harness reference - Adding a tool
- canonical JSON value
- A canonical JSON value is the lossless structured result a DeepSeek Harness tool returns; the registry snapshots, validates, and freezes it before rendering.— DeepSeek Harness reference - Adding a tool
- ToolArgsError
- ToolArgsError is the DeepSeek Harness error a tool throws when a constraint the parameter schema cannot express is violated.— DeepSeek Harness reference - Adding a tool
Sources
- DeepSeek Harness reference - Adding a tool· deepseek-harness
- DeepSeek Harness reference - Tools subsystem· deepseek-ai