ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness Cookbook: Add a Tool Step by Step

Plugin DevelopmentPublished 2026-11-18Author: DeepSeek Plugin Market
DeepSeek HarnessDSH plugincustom tooldefineToolCookbook
The official Cookbook gives a minimal tool, but running it is not the same as proving the model can use it. Follow the build, then apply three checks.

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):

ts
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):

  1. 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.
  2. 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.
  3. 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.
  4. 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.signal so cancellation works.
  • Cross-turn or user-inspectable — hand it to ctx.jobs, return a handle, and let job_* 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):

HookUse it forDo not use it for
tools/pre-executeExtensible allow/reject/ask policyBusiness logic
ctx.tools.guard()Final monotonic rejectionReversible temporary checks
tools/executeDeadlines, retries, metricsChanging the return value
tools/post-executeReplacing display, blocking results, adding contextBypassing programmatic access
tools/resultObserving the immutable resultModifying 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):

  1. Schema reaches the prompt — the name, description, and parameters appear in the model-visible tool list. If not, check inject and registration.
  2. 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.
  3. 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.”

ChatGPTClaudeGrok / X / CursorGemini

FAQ

What is the minimum for adding a custom DeepSeek Harness tool?

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.

Does DeepSeek Harness validate tool arguments before execute runs?

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.

What should a DeepSeek Harness tool execute function return?

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.

How do I confirm the model can actually see a new DeepSeek Harness tool?

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