ツールディスクリプションとは何か

ツールディスクリプションは「道具の説明書き」

ツールディスクリプション(tool description)というのは、AIが使える道具=ツールに添えられた説明文のことです。Claude Codeのようなツールを使えるAIは、ファイルを読む・コマンドを実行する・Webを検索するといった「道具」を渡されて動いています。その道具ひとつひとつに「これは何をする道具で、どういうときに使い、どんな入力が必要か」を書いた説明文がくっついている、と考えてください。それがツールディスクリプションです。

身近な例えでいうと、キッチンの引き出しに道具がずらっと並んでいる状態を想像してみてください。ピーラー、おろし金、菜箸、キッチンばさみ。料理を手伝ってくれる人が初めてそのキッチンに来たとき、道具の見た目だけでは何に使うか分からないものもありますよね。そこで各道具に「野菜の皮をむくとき用。硬いカボチャには使わないこと」といったタグが貼ってあれば、その人は迷わず適切な道具を選べます。このタグにあたるのがツールディスクリプションです。

AIは説明文だけを頼りに道具を選んでいる

ここが初心者の方が意外に思うポイントなのですが、AIはツールの中身のプログラムを読んで理解しているわけではありません。基本的には「ツールの名前」と「説明文」と「入力の形式」だけを見て、今やるべき作業にどれが合っているかを判断しています。

つまり説明文が曖昧だと、AIは道具を選び間違えます。「データを取得する」としか書かれていないツールが2つ並んでいたら、どちらを使えばいいのか判断のしようがない。逆に「社内の勤怠システムから、指定した従業員IDの今月の打刻記録を取得する。過去分の照会には使えない」くらい具体的に書いてあれば、AIは自信を持って選べますし、使うべきでない場面では避けてくれます。

説明文にはだいたい何が書かれるか

決まったフォーマットがあるわけではありませんが、よく書かれる内容としては次のようなものがあります。

• 何をするツールか — 一言で言うとどんな動作をするのか
• いつ使うか — どんな場面で呼び出すのが適切か
• いつ使わないか — 似た別のツールがあるときは特に重要
• 引数の意味 — 何を渡せばいいのか、必須なのかどうか
• 戻ってくるもの — 結果としてどんな形のデータが返るのか
• 注意点や制約 — 実行に時間がかかる、取り消せない操作である、など

特に「いつ使わないか」を書いておくのは効きます。人間に仕事を教えるときも「これはこう使う」だけでなく「ただしこのケースでは使わないでね」と伝えたほうが事故が減りますよね。AIも同じで、境界線を引いてあげると振る舞いが安定します。

自分でツールを作るときに関係してくる

「使うだけなら関係ない話では」と思うかもしれませんが、自分でAIに新しい道具を持たせようとした瞬間に、この話は自分ごとになります。たとえばMCPサーバーという仕組みで独自のツールをClaudeに追加する場合、そのツールの説明文は自分で書くことになります。

そして、たいてい最初はうまく動きません。「作ったツールをClaudeが呼んでくれない」というつまずきは非常によくあるのですが、原因がツール本体のバグではなく説明文の書き方だった、というケースがかなりあります。呼んでくれないなら、まず説明文を疑ってみる。これは覚えておくと得をする感覚です。

書くときのコツ

難しく考えず、「このツールを初めて使う新人に、一段落で説明するとしたら」と想像して書くのが近道です。専門用語を並べるより、具体的な動詞と対象を書いたほうが伝わります。「処理する」ではなく「読み込んでJSONに変換する」のように。

もうひとつ、長ければいいというものでもありません。説明文はAIが読む文章として毎回コンテキストを消費するので、ツールが何十個もある環境では全部が冗長だと圧迫します。必要なことを漏らさず、それでいて贅肉のない文章。要はいい技術文書を書くときのコツとほぼ同じです。

ツールディスクリプションは地味な要素ですが、AIエージェントの精度を左右する部分でもあります。うまく動かないときに「モデルが賢くないから」と結論づける前に、渡している説明文がちゃんと道案内になっているかを見直してみてください。