01前提条件

始める前に、以下を確認してください：

• はじめてのプラグイン開発を完了していること：リポジトリルートに scratch-plugin/ が存在し、cordis.yml に src/my-plugin.ts が登録済みであること；
• pnpm dsh web --patch ./scratch-plugin/cordis.yml で Web UI が起動すること；
• name、inject、apply の3つのエクスポートを理解していること。

02ツールの仕組み

ツールを使うと、会話の中でモデルがあなたのコードを呼び出せるようになります。通常のプラグインは起動時に受動的に読み込まれてバックグラウンドで動作しますが、ツールは構造化された方法でモデルに機能を公開します。モデルが呼び出すタイミングと渡す引数を決め、結果を回答に折り込みます。

ツール呼び出しは5つのステップで構成されます。モデルがツールの name と description を読み、現在の質問に必要かどうかを判断し；必要なら parameters スキーマに従って引数を組み立て；フレームワークが検証して execute に渡し；execute の戻り値を output.render がコンテンツブロックに変換し；モデルが結果を読んで最終的な回答を書きます。

03ツールプラグインを書く

scratch-plugin/src/my-plugin.ts を開き、内容を次のコードに置き換えてください：

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}!`
    },
  }))
}

最初のプラグインと比べて、骨格は変わりません。今でも name、inject、apply の3つをエクスポートします。変わったのは、apply が defineTool で定義したツールを ctx.tools.register で登録するようになったことです。これがこのチュートリアルの主役です。

04defineTool をフィールドごとに理解する

defineTool の各フィールドは、チェーンの1つの輪に対応しています。順に見ていきましょう：

05なぜ tools を inject しなければならないのか

tools サービスは Harness の組み込みサービスです。安全に使うには、プラグインが依存関係を宣言する必要があります：

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({ /* ... */ }))
}

06再起動して確認

プラグインコードができたら、再起動して読み込みます：

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

チャットボックスに次のように入力してください：

Use the greet tool to say hi to Ada.

モデルは greet が適切だと判断し、name: 'Ada' で呼び出し、Hello, Ada! を受け取って、回答に自然に織り込みます。回答に挨拶が含まれていれば、ツールのチェーン全体が動作しています。

07良い description を書く

ツールが使われるかどうかは、ひとえに description にかかっています。モデルは毎ターン、登録されているすべてのツールの name と description を読み、それらを基に判断します。2つの書き方を比べてみましょう：

// 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.'

各パラメータの description もモデルに表示されます。引数の説明が明確なほど、モデルが誤った値を渡す可能性は低くなります。モデルを新しいチームメイトだと思ってください。ツールが何をするのか、いつ使うのか、各引数をどう埋めるのかを説明すれば、正しく使ってくれます。

08反復とデバッグ

ツール開発は高速な反復ループです：

# 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

1つのプラグインで複数のツールを登録できます。ctx.tools.register は何度でも呼び出せます。1つのドメインの複数の機能をまとめて提供する自然な方法です。