01Prerequisites

Before you start, make sure:

• you have completed Build Your First Plugin: scratch-plugin/ exists at the repo root and cordis.yml already registers src/my-plugin.ts;
• pnpm dsh web --patch ./scratch-plugin/cordis.yml launches the web UI;
• you understand the three exports name, inject, and apply.

02How a tool works

A tool lets the model call your code during a conversation. A regular plugin loads passively at startup and does background work; a tool exposes a capability to the model in a structured way — the model decides when to call it and what arguments to pass, then folds the result into its reply.

A tool call has five steps: the model reads the tool’s name and description and decides whether the current question needs it; if so, it assembles arguments per the parameters schema; the framework validates them and hands them to execute; execute’s return value is converted to content blocks by output.render; the model reads the result and writes its final reply.

03Write the tool plugin

Open scratch-plugin/src/my-plugin.ts and replace its contents with:

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

Compared with the first plugin, the skeleton is unchanged: it still exports the name, inject, apply trio. What changed is that apply now registers a tool defined with defineTool via ctx.tools.register — this is the star of the tutorial.

04Understanding defineTool field by field

Every field of defineTool maps to one link in the chain. Let’s go through them:

05Why you must inject tools

The tools service is a built-in Harness service — a plugin must declare the dependency before using it safely:

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  // the tools service is ready — ctx.tools is guaranteed to exist
  ctx.tools.register(defineTool({ /* ... */ }))
}

06Restart and verify

With the plugin code in place, restart to load it:

pnpm dsh web --patch ./scratch-plugin/cordis.yml
# open http://127.0.0.1:3080

Type this into the chat box:

Use the greet tool to say hi to Ada.

The model recognizes that greet fits, calls it with name: 'Ada', receives Hello, Ada!, and works it into its reply. Seeing the greeting in the reply means the whole tool chain works.

07Writing a good description

Whether a tool gets used at all comes down to its description. On every turn the model reads the name and description of every registered tool and decides from them. Compare two styles:

// bad: implementation detail — the model cannot tell when to use it
description: 'calls the greet function and returns a string'

// good: usage guidance — the model knows when to reach for it
description: 'Greet someone by name when the user asks to say hello.'

Each parameter’s description is shown to the model too — the clearer the argument, the less likely the model passes the wrong value. Treat the model as a new teammate: explain what the tool does, when to use it, and how to fill in each argument, and it will use the tool correctly.

08Iterate and debug

Tool development is a fast iteration loop:

# 1. edit scratch-plugin/src/my-plugin.ts
# 2. restart
pnpm dsh web --patch ./scratch-plugin/cordis.yml
# 3. verify at http://127.0.0.1:3080 with different phrasings

One plugin can register multiple tools — call ctx.tools.register as many times as you like. This is a natural way to ship several capabilities from one domain together.