人間とAIとウェブの未来ENJA
メニュー

取り組み2026-09-10公開2026-09-28無料

MCPツールの説明文にいつ使うかを書いたら、AIエージェントが呼び出した

English

この記事の目次

本記事の概要

私は、複数の独立したタスクをサブエージェントに割り当てて並列に実行させるMCPツールを自作しました。以下では、このMCPツールを、並列実行のMCPツールと書きます。MCPは、Model Context Protocolの略で、外部のツールをAIエージェントが見つけて呼び出すための標準規格です。サブエージェントは、AIエージェントがタスクを任せるために起動する別のAIエージェントです。しかし、OpenHands、OpenCode、Qwen Codeの3種類のAIコーディングエージェントは、並列実行のMCPツールを自分からは呼び出しませんでした。

呼び出される条件を見つけるために、私は3つのことを試しました。1つ目に、AIエージェントに要約させる短いメモを、6件から30件に増やしました。2つ目に、AIエージェントに渡すタスクを、読解と修正と検証が必要な8件の独立したタスクに替えました。3つ目に、AIエージェントが起動時に読み込むルールファイルに、並列実行のMCPツールの名前と、対象が互いに独立していて5件以上ある場合に使うという条件を書きました。この3つでは、サブエージェントがタスクを完了した実行は1回もありませんでした。

私がMCPツールの説明文に、使う場面を書いた1文を追加した場合だけ、AIエージェントは並列実行のMCPツールを呼び出しました。MCPツールの説明文は、MCPのツール定義のdescriptionフィールドに書く文章です。条件は、3種類のAIエージェントとルールファイルの有無を組み合わせた6通りです。6通りの条件のそれぞれを、説明文に1文がある場合と無い場合で2回ずつ実行し、合計24回の実行を比べました。1文がある場合は、12回の実行のうち7回で、AIエージェントが並列実行のMCPツールを呼び出しました。この7回のうち4回で、サブエージェントがタスクを完了しました。1文が無い場合は、12回の実行のすべてで、呼び出しが0回でした。

この差をFisherの正確確率検定で検定すると、実行を単位にした場合のp値は0.0046、条件を単位にした場合のp値は0.0152でした。ただし、1文がある場合の12回の実行のうち6回は、説明文以外の2つの点をそろえる前の実行です。2つの点は、プロンプトの中の数の書き方と、AIエージェントに与えた制限時間の記録です。2つの点をそろえた実行だけを比べると、呼び出しがあった実行は、1文がある場合が6回のうち3回、無い場合が6回のうち0回です。この比較のp値は0.182で、0.05より大きい値です。

比較のために、相談用のMCPツールも測定しました。相談用のMCPツールは、AIエージェントが設計を決める前に、別のモデルに1回だけ意見を求めるための既製のMCPツールです。AIエージェントが相談用のMCPツールを呼び出すかどうかは、ルールファイルに相談についての規定を書いたかどうかで分かれました。規定がある場合は、6回の実行のすべてで呼び出しがありました。規定が無い場合は、6回の実行のすべてで呼び出しが0回でした。

並列実行のMCPツールの呼び出しは、サブエージェントを複数起動する重い処理です。相談用のMCPツールの呼び出しは、別のモデルに1回だけ意見を求める軽い処理です。処理の重さによって、AIエージェントが呼び出すかどうかを決める要因が変わる、という説明は、仮説として書いています。理由は、相談用のMCPツールが既製のツールで、私が説明文を変えられないことです。

本文では、最初に24回の実行の結果と、1文を既定の説明文に追加した判断を説明します。次に、4つの測定で同じにした設定と、判定の方法を説明します。4つの測定は、メモ6件の測定、メモ30件の測定、タスク8件の測定、説明文の1文の有無を比べた測定です。その後、4つの測定の結果と、検定の結果を示します。続けて、測定用のプログラムの不備が原因で測定し直した3件を説明します。最後に、相談用のMCPツールの測定と、分離できていない4つの要因を説明します。呼び出しが0回だった理由を後から区別するための実行記録の設計と、この実験の結果から言えないことも説明します。参照した資料の書誌は、末尾の節にまとめました。

記事から得られること

MCPサーバを自分で作っていて、そのMCPツールをAIエージェントが呼び出さないことに困っている方に向けて、次の3つを説明します。

3つとも、私が実行した4つの測定と、測定用のプログラムの不備が原因で測定し直した3件に基づいています。

この記事は、私が進めている取り組みの一次記録に基づく考察です。本文では、比べた3種類のAIコーディングエージェントの名前を出します。内容は各提供元の見解を代表するものではありません。

説明文に1文を追加した場合だけ呼び出されたMCPツール

私は、自作したMCPツールをAIエージェントが自分から呼び出す条件を測定しました。AIエージェントは、この記事ではAIコーディングエージェントを指します。MCPは、Model Context Protocolの略で、外部のツールをAIエージェントが見つけて呼び出すための標準規格です。

私は並列実行のMCPツールをMCPサーバとして実装し、測定の対象にしました。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させます。サブエージェントは、AIエージェントがタスクを任せるために起動する、別のAIエージェントです。

この記事では2つの数を分けて数えます。1つ目はAIエージェントが並列実行のMCPツールを呼び出した実行の数です。2つ目はサブエージェントがタスクを完了した実行の数です。

結論は次のとおりです。私がMCPツールの説明文に、使う場面を書いた1文を追加した場合だけ、AIエージェントは並列実行のMCPツールを呼び出しました。MCPツールの説明文は、MCPのツール定義のdescriptionフィールドに書く文章です。AIエージェントは、呼び出すツールを選ぶときにMCPツールの説明文を読みます。

条件は6通りあります。私は3種類のAIエージェントであるOpenHands、OpenCode、Qwen Codeのそれぞれに、ルールファイルを読み込ませる場合と読み込ませない場合を用意しました。ルールファイルは、AIエージェントが起動時に読み込む、作業の進め方を書いたファイルです。

私は6通りの条件のそれぞれで、使う場面を書いた1文がMCPツールの説明文にある場合に2回、無い場合に2回実行しました。実行は合計24回で、結果は次の表のとおりです。

説明文の1文 実行の回数 AIエージェントが並列実行のMCPツールを呼び出した実行 サブエージェントがタスクを完了した実行
あり 12回 7回 4回
なし 12回 0回 0回

使う場面を書いた1文がMCPツールの説明文に無い場合の12回の実行のうち、6回はルールファイルを読み込ませた実行です。この6回の実行でも、AIエージェントが並列実行のMCPツールを呼び出した実行は0回でした。

私はこの結果を根拠にして、使う場面を書いた1文を並列実行のMCPツールの既定の説明文に追加しました。ただし、将来もう一度比べるために、環境変数で説明文を差し替える仕組みを残しました。また、既定の説明文にこの1文が含まれていることを単体テストで固定しました。

私が並列実行のMCPツールの既定の説明文に、使う場面を書いた1文を追加したので、比較できる内容が変わりました。1文を追加した後は、並列実行のMCPツールを使う場面が、MCPツールの説明文とルールファイルの両方に書かれています。そのため、今後、ルールファイルを読み込ませる場合と読み込ませない場合を比べても、並列実行のMCPツールの呼び出しについては、別の比較になります。使う場面の記述が2か所にある場合と、1か所にある場合の比較です。2か所はMCPツールの説明文とルールファイルで、1か所はMCPツールの説明文です。

それでも、私は並列実行のMCPツールの既定の説明文に、使う場面を書いた1文を追加しました。理由は、1文が無い場合の12回の実行のうち、サブエージェントがタスクを完了した実行が0回だったことです。比較の厳密さより、並列実行のMCPツールが使われることを優先しました。

私はどのタスクをAIに任せてよいかの考え方を、別の記事「AIに任せて壊れた作業と、壊れなかった作業の違い」に書きました。今回は、AIエージェントがタスクをサブエージェントに任せるかどうかを測定しました。

4つの測定で同じにした設定と、判定の方法

私は、AIエージェントが自作の並列実行のMCPツールを自分から呼び出す条件を、4つの測定で調べました。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させるMCPツールです。4つの測定は、メモ6件の測定、メモ30件の測定、タスク8件の測定、説明文の1文の有無を比べた測定です。4つの測定のすべてで、モデル、推論のエンドポイント、実行の順序、判定の方法の4つを同じにしました。

私はOpenHands、OpenCode、Qwen Codeの3種類のAIエージェントを比べました。2026年8月17日にこれらをmacOSにインストールし、その時点のバージョンを記録しました。バージョンは、OpenHandsがCLIの1.16.0、OpenCodeが1.18.18、Qwen Codeが0.21.13です。

すべての実行で、私はモデルを同じ1種類にしました。3種類のAIエージェントは、推論サービスの共有エンドポイントを経由して、コード向けのモデルのプレビュー版を呼び出します。測定用のプログラムが1回の実行ごとに書く実行記録では、すべての行でモデルのフィールドが同じ値です。

推論サービスの共有エンドポイントには同時に実行できる数の制限があるため、私は1回ずつ順番に実行しました。

AIエージェントが自分でツールを選ぶかどうかを確かめるために、私はプロンプトにMCPツールの名前を書きませんでした。プロンプトはAIエージェントに渡す指示の文章です。

AIエージェントがツールを呼び出したかどうかの判定に、私はAIエージェントが出力に書いた報告を使いませんでした。判定には、ツールの種類ごとに決めた次の記録を使いました。

私はタスクの合否をテストの終了コードだけで判定しました。テストの原本を、AIエージェントが書き換えられない場所に置き、合否を判定するときはその原本を実行しました。また、AIエージェントがテストを書き換えたかどうかを別の仕組みで検出しました。

4つの測定で変えた点は次の表のとおりです。

測定の名前 AIエージェントに渡したタスク 変えた点
メモ6件の測定 短いメモ6件の要約 基準にする測定
メモ30件の測定 短いメモ30件の要約 対象の件数だけを増やした
タスク8件の測定 読解と修正と検証が必要な、独立したタスク8件 タスク1件に必要な推論の量を増やした
説明文の1文の有無を比べた測定 読解と修正と検証が必要な、独立したタスク8件 MCPツールの説明文の1文の有無だけを変えた

4つの測定のすべてで、条件は3種類のAIエージェントと、ルールファイルの有無の2通りを組み合わせた6通りです。ルールファイルは、AIエージェントが起動時に読み込む、作業の進め方を書いたファイルです。

私は、同じモデルで3種類のAIエージェントを比べる測定の方法を、別の記事「同じAIモデルで3つのAIエージェントを比べて出た、所要時間とやり直しの回数だけの差」で作りました。今回はその方法を使い、測定の対象を成果物の品質からMCPツールの呼び出しに変えました。

対象の件数と推論の量を増やしても呼び出されなかったMCPツール

並列実行のMCPツールの説明文に、使う場面を書いた1文を追加する前に、私は3つの測定を実行しました。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させる、私が自作したMCPツールです。測定の目的は、AIエージェントがどのような場合に並列実行のMCPツールを自分から呼び出すかを見つけることです。

私は3つの測定で、対象の件数と、タスク1件に必要な推論の量を変えました。条件は、3つの測定のすべてで、OpenHands、OpenCode、Qwen Codeの3種類のAIエージェントとルールファイルの有無を組み合わせた6通りです。ルールファイルは、AIエージェントが起動時に読み込む、作業の進め方を書いたファイルです。

3つの測定の結果は次の表のとおりです。

測定の名前 AIエージェントに渡したタスク AIエージェントが並列実行のMCPツールを呼び出した条件 サブエージェントがタスクを完了した条件 AIエージェントが処理を終えるまでの時間
メモ6件の測定 短いメモ6件の要約 6通りのうち0通り 0通り 22秒から143秒
メモ30件の測定 短いメモ30件の要約 6通りのうち1通り 0通り 42秒から101秒
タスク8件の測定 独立したタスク8件 6通りのうち1通り 0通り 39秒から264秒

表の時間は、6通りの条件の実行のうち、最も短い実行の時間と、最も長い実行の時間です。

メモ6件の測定では、私はAIエージェントに短いメモ6件をそれぞれ1行に要約させました。6通りの条件のどれでも、AIエージェントは並列実行のMCPツールを呼び出さず、6件の要約を自分で最後まで処理しました。

メモ6件の測定と同じ日に、私は依頼を送るツールも測定しました。依頼を送るツールは、別のセッションで動いているAIエージェントに依頼を送るツールです。6通りの条件のすべてで、AIエージェントは依頼を送るツールを呼び出しました。依頼を受け取る側のファイルには、目印の文字列を含む行が残っていました。目印の文字列は私がタスクの文章に入れておいた文字列です。ルールファイルの有無は依頼を送るツールの結果に関係しませんでした。

並列実行のMCPツールと依頼を送るツールで結果が違った原因は、2つのツールの説明文にあると私は考えました。依頼を送るツールの説明文には、ツールの目的と使う場面が書いてありました。

メモ30件の測定では、私は要約させる短いメモを6件から30件に増やしました。6通りの条件のうち1通りで、AIエージェントは並列実行のMCPツールを呼び出しました。しかし、残っている記録の範囲では、この1通りの条件でもサブエージェントは1件も起動していませんでした。この1通りの条件の実行では、並列実行のMCPツールが書いた呼び出しの記録が2件ありました。当時の測定用のプログラムは、1件目の記録の数値だけを保存していました。測定用のプログラムは、AIエージェントを起動し、実行記録を書き、タスクの合否を判定するプログラムです。1件目の記録では、起動したサブエージェントは0件でした。2件目の記録の内容は、残っていません。

私はメモ30件の測定の結果を次のように考えました。1件ごとの処理が同じ手順の繰り返しである場合、対象が30件あっても、AIエージェントは30件をまとめて自分で処理できます。そのため、対象の件数を増やすだけでは、AIエージェントがタスクをサブエージェントに任せる理由になりませんでした。

タスク8件の測定では、私はAIエージェントに渡すタスクを、メモの要約から8件の独立したタスクに替えました。8件のタスクはどれも読解と修正と検証が必要で、タスクごとに専用の説明の文章とテストがあります。ただし、AIエージェントに正解は渡しませんでした。

タスク8件の測定でも、AIエージェントは6通りの条件のうち1通りだけで、並列実行のMCPツールを呼び出しました。しかし、この1通りの条件では、AIエージェントはサブエージェントを起動するスクリプトを誤って書きました。スクリプトの誤りで、サブエージェントは1件も起動しませんでした。そのため、8件のタスクは親エージェントが自分で処理しました。親エージェントは、サブエージェントを起動しようとしたAIエージェントです。

メモ30件の測定の6通りと、タスク8件の測定の6通りを合わせると、条件は12通りです。タスク8件の測定では、測定用のプログラムの不備を修正した後の実行を数えました。AIエージェントは12通りの条件のうち2通りだけで、並列実行のMCPツールを呼び出しました。しかし、2通りの条件のどちらでもサブエージェントは起動しませんでした。そのため、サブエージェントがタスクを完了した条件は12通りのうち0通りでした。

タスク8件の測定の時点で、ルールファイルには、並列実行のMCPツールの名前が書いてありました。どのような場合に使うかについても、「対象が互いに独立していて、5件以上ある場合に使う」と書いてありました。しかし、ルールファイルにこの2つが書いてあっても、サブエージェントがタスクを完了した条件は1通りもありませんでした。

MCPツールの説明文に追加した、使う場面を書いた1文

この節では、説明文の1文の有無を比べた測定を説明します。この測定の対象は、私が自作した並列実行のMCPツールです。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させるMCPツールです。

私はこの測定のタスクを、タスク8件の測定と同じ8件にしました。タスク8件の測定は、AIエージェントに、読解と修正と検証が必要な独立したタスク8件を解かせた測定です。AIエージェントが並列実行のMCPツールを呼び出すために必要な手順も変えませんでした。ただし、並列実行のMCPツールの説明文の先頭に、使う場面を書いた1文を入れるかどうかだけは変えました。MCPツールの説明文は、MCPのツール定義のdescriptionフィールドに書く文章です。1文を入れる場合と入れない場合は、環境変数で切り替えました。

測定の前に、私はMCPの仕様の2026-07-28の改訂版で、MCPツールの説明文についての規定を確認しました。仕様によると、MCPツールはモデルが制御するように設計されています。仕様の「モデル」は、AIエージェントがツールを選ぶときに使う言語モデルを指します。言語モデルが文脈の理解と利用者のプロンプトに基づいて、ツールを自動で見つけて呼び出せるという説明もあります。descriptionは機能についての、人が読める説明と定義されています。ツールを使う場面をdescriptionに書くことを求める規定は、仕様にありません。ただし、状態を持つツールについての仕様の節には、次の説明があります。作成を担当するツールのdescriptionに保持の方針を書いておくと、モデルがその方針を読めます。そのため、モデルが説明文を読んで判断するという前提は、仕様に書かれています。

使う場面を書いた1文に、私は次の2つの内容を書きました。1つ目の内容は並列実行のMCPツールを使う場面です。使う場面は、互いに独立した対象が複数あり、すべての対象を漏れなく処理したい場面です。1文には、この場面では親エージェントが対象を順番に処理する代わりに、このMCPツールでサブエージェントに並列に処理させる、と書きました。2つ目の内容は並列実行のMCPツールの動作です。起動したサブエージェントの数と完了したサブエージェントの数が、記録に残ります。上の2つの内容は1文の要旨で、1文の文面はこの記事に書きません。

使う場面を書いた1文の書き方は、依頼を送るツールの説明文から取り入れました。依頼を送るツールは、別のセッションで動いているAIエージェントに依頼を送るツールです。メモ6件の測定は、AIエージェントに、短いメモ6件をそれぞれ1行に要約させた測定です。メモ6件の測定と同じ日の測定では、6通りの条件のすべてで、AIエージェントが依頼を送るツールを呼び出しました。条件は、3種類のAIエージェントとルールファイルの有無の組み合わせです。ルールファイルは、AIエージェントが起動時に読み込む、作業の進め方を書いたファイルです。

次に、測定し直した経緯を説明します。初回では、使う場面を書いた1文がある場合の6回の実行のうち4回で、AIエージェントが並列実行のMCPツールを呼び出しました。しかし、その後のレビューで、説明文以外に、そろっていない点が2つ見つかりました。1つ目は、プロンプトの中の数の書き方が、1文がある場合と無い場合で違っていたことです。2つ目は、AIエージェントに与えた制限時間が、記録に残っていなかったことです。私は、2つの点をそろえて、測定し直しました。2回目では、1文が無い場合は6回のうち0回、1文がある場合は6回のうち3回で、呼び出しがありました。

私はもう一度レビューを依頼し、指摘を1件受けました。指摘の内容は次のとおりです。値が空の環境変数をAIエージェントが無視する場合、使う場面を書いた1文を入れない設定で実行しても、MCPサーバでは既定の説明文が使われます。その場合、1文が無い場合として測定した実行は、既定の説明文を使った実行になります。そのため、私はMCPサーバに、実際に使われた説明文を記録に書き出す処理を追加しました。追加した後で、3回目として、1文が無い場合をもう6回実行しました。6回の実行のうち、AIエージェントが並列実行のMCPツールを呼び出した実行は0回でした。記録に書き出された説明文には、6回の実行のすべてで1文が含まれていませんでした。

ここまでの実行を合計すると、使う場面を書いた1文がある場合と無い場合の実行は、それぞれ12回です。ルールファイルの有無で分けた結果は次の表のとおりです。

説明文の1文 ルールファイル 実行の回数 AIエージェントが並列実行のMCPツールを呼び出した実行
あり あり 6回 5回
あり なし 6回 2回
なし あり 6回 0回
なし なし 6回 0回

使う場面を書いた1文がある場合、AIエージェントが並列実行のMCPツールを呼び出した実行は、ルールファイルを読み込ませたときのほうが多くありました。ただし、AIエージェントの種類と、ルールファイルの有無と、1文の有無が同じ実行は、1回か2回だけで、結果のばらつきも大きいです。同じ条件で、1回目の実行では呼び出しがあり、2回目の実行では呼び出しが無かった例があります。そのため、この差は傾向としてしか読めませんが、ルールファイルに効果が無いとは言えません。

私が言える範囲は次の2つです。使う場面を書いた1文が無い場合、ルールファイルを読み込ませても、AIエージェントが並列実行のMCPツールを呼び出した実行は6回のうち0回でした。1文がある場合、呼び出しがあった実行はルールファイルを読み込ませたときのほうが多くありました。

サブエージェントがタスクを完了したかどうかは、AIエージェントの種類によって違いました。

Qwen Codeは3回の実行で並列実行のMCPツールを呼び出し、そのすべてでサブエージェントを8件起動しました。3回の実行のうち2回では、8件のサブエージェントがすべて完了しました。残りの1回では、8件のうち7件が完了しました。7件が完了した実行は、ルールファイルを読み込ませなかった実行です。この実行では、ルールファイルが無くても、8件のうち7件のサブエージェントがタスクを完了しました。

OpenCodeは、初回の、ルールファイルを読み込ませた実行で、サブエージェントを起動するスクリプトの誤りを自分で修正しました。その後、8件のサブエージェントが完了しました。この実行には935秒かかりました。

OpenHandsは、3回の実行で並列実行のMCPツールを呼び出しました。3回の実行を合わせると、このMCPツールが書いた呼び出しの記録は4件で、起動したサブエージェントは32件でした。しかし、完了したサブエージェントは、32件のうち0件でした。この原因は、測定用のプログラムの不備を説明する節に書きました。

すべての実行で、8件のタスクはすべてテストに合格し、AIエージェントがテストを書き換えた例は0件でした。

MCPツールの説明文の品質によって結果が変わるという報告は、外部の研究にもあります。1つ目の研究はMCP Tool Descriptions Are Smelly!です。この研究の対象は、多数のMCPサーバが提供するMCPツールの説明文です。この研究によると、多くの説明文には不備があり、説明文に不足している要素を補うとタスクの成功率が上がります。2つ目の研究はLearning to Rewrite Tool Descriptionsです。この研究は、ツールの説明文を書き直してツールの呼び出しの信頼性を上げる研究です。この研究にも、説明文を書き直すと成功率が上がるという報告があります。

2つの研究で測定された値は、AIエージェントがツールを呼び出す割合ではなくタスクの成功率です。そのため、2つの研究は私の測定の結果の裏づけには使いません。ただし、私は2つの研究から、MCPツールの説明文の品質によって結果が変わるという観測が私だけの観測ではないと受け取りました。2つの研究の調査の規模と数値は、参考にした資料の節に書きました。

MCPツールを呼び出した実行の数を比べたFisherの正確確率検定

私は、AIエージェントがMCPツールを呼び出した実行の数の差を、Fisherの正確確率検定で検定しました。検定した測定は2つあります。

1つ目の測定は並列実行のMCPツールの測定です。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させるMCPツールで、私が自作しました。この測定では、使う場面を書いた1文が並列実行のMCPツールの説明文にある場合と無い場合を比べました。

2つ目の測定は相談用のMCPツールの測定です。相談用のMCPツールは、AIエージェントが設計を決める前に、別のモデルに1回だけ意見を求めるための既製のMCPツールです。この測定で私は、ルールファイルに相談についての規定がある場合と無い場合を比べました。ルールファイルは作業の進め方を書いたファイルで、AIエージェントが起動時に読み込みます。

実験の記録にはFisherの正確確率検定の結果がありませんでした。そのため、私が2026年9月10日に検定の結果を計算しました。Pythonの標準ライブラリだけを使い、超幾何分布から両側のp値を直接計算しました。

私は、AIエージェントがMCPツールを呼び出した数を3種類の単位で数えました。

検定の結果は次の表のとおりです。

比べた対象 数えた値 p値
並列実行のMCPツール。実行を単位にする 1文がある場合は12回のうち7回。1文が無い場合は12回のうち0回 0.0046
並列実行のMCPツール。条件を単位にする 1文がある場合は6通りのうち5通り。1文が無い場合は6通りのうち0通り 0.0152
並列実行のMCPツール。説明文以外の2つの点をそろえた実行だけ 1文がある場合は6回のうち3回。1文が無い場合は6回のうち0回 0.182
並列実行のMCPツール。1文がある場合の、ルールファイルの有無 ルールファイルがある場合は6回のうち5回。無い場合は6回のうち2回 0.242
相談用のMCPツール。実行を単位にする 規定がある場合は6回のうち6回。規定が無い場合は6回のうち0回 0.0022
相談用のMCPツール。AIエージェントの種類を単位にする 規定がある場合は3種類のうち3種類。規定が無い場合は3種類のうち0種類 0.10

表のp値を読むときの注意は4つあります。

1つ目の注意は次のとおりです。並列実行のMCPツールの24回の実行は互いに独立ではありません。6通りの条件を、使う場面を書いた1文がある場合と無い場合で2回ずつ繰り返した実行だからです。そのため、実行を単位にしたp値は実際より小さくなりやすいです。

2つ目の注意は次のとおりです。統計では、差があると判定しにくい数え方を保守的な数え方と呼びます。条件を単位にする数え方は、実行を単位にする数え方より保守的です。並列実行のMCPツールの測定では、条件を単位にした比較のp値は0.0152で、実行を単位にした比較のp値の0.0046より大きいです。しかし、条件を単位にする数え方は、並列実行のMCPツールの説明文以外の2つの点をそろえた実行だけを比べる数え方ほど保守的ではありません。説明文以外の2つの点をそろえた実行だけを比べると、p値は0.182です。

3つ目の注意は次のとおりです。使う場面を書いた1文がある場合の12回の実行は、初回の6回と2回目の6回です。初回の6回は、説明文以外の2つの点をそろえる前の実行です。この6回の実行のうち4回で、AIエージェントは並列実行のMCPツールを呼び出しました。2つの点は、プロンプトの中の数の書き方と、AIエージェントに与えた制限時間の記録です。2回目の6回は、2つの点をそろえた後の実行です。この6回の実行のうち3回で、AIエージェントは並列実行のMCPツールを呼び出しました。1文が無い場合の12回の実行は、すべて2つの点をそろえた後の実行です。2つの点をそろえた実行だけを比べると、AIエージェントが並列実行のMCPツールを呼び出した実行の数は次のとおりです。1文がある場合は6回の実行のうち3回で、1文が無い場合は6回の実行のうち0回です。この比較のp値は0.182で、0.05より大きいです。

4つ目の注意は次のとおりです。相談用のMCPツールの比較では、AIエージェントの種類を単位にすると、p値は0.10になります。この値も0.05より大きいです。

測定用のプログラムの不備で測定し直した3件

4つの測定は、私が自作した並列実行のMCPツールを、AIエージェントがどの場合に自分から呼び出すかを調べた測定です。4つの測定は、メモ6件の測定、メモ30件の測定、タスク8件の測定、説明文の1文の有無を比べた測定です。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて、並列に実行させるMCPツールです。

4つの測定では、測定用のプログラムの不備が3件見つかりました。測定用のプログラムは、AIエージェントを起動し、実行記録を書き、タスクの合否を判定するプログラムです。私は3件の不備をすべて修正して、測定し直しました。この節では、3件の不備を見つかった順に説明します。

1件目の不備はタスク8件の測定の初回で見つかりました。タスク8件の測定は、AIエージェントに独立した8件のタスクを解かせた測定です。測定用のプログラムには、AIエージェントがテストを書き換えたことを検出する処理がありませんでした。私はレビューで、この処理が無いことを指摘されました。測定用のプログラムに、テストの書き換えを検出する処理と、テストを元の状態に戻す処理を追加して、測定し直しました。

ただし、私は不備があった測定の記録を削除していません。その記録は、測定用のプログラムの不備を示すフラグを付けて、集計の対象から外しました。

測定用のプログラムを修正した後のタスク8件の測定では、6通りの条件のすべてで、8件のタスクがすべてテストに合格しました。条件は、OpenHands、OpenCode、Qwen Codeの3種類のAIエージェントと、ルールファイルの有無の組み合わせです。ルールファイルは、AIエージェントが起動時に読み込む、作業の進め方を書いたファイルです。AIエージェントがテストを書き換えた例も、途中で作業をやめた例も、0件でした。

2件目の不備は、説明文の1文の有無を比べた測定の初回で見つかりました。説明文の1文の有無を比べた測定は、並列実行のMCPツールの説明文に、使う場面を書いた1文があるかどうかだけを変える測定です。しかし、初回では、1文がある場合の実行と、無い場合の実行の間に、説明文以外にそろっていない点が2つありました。1つ目は、プロンプトの中の数の書き方が違っていたことです。2つ目は、AIエージェントに与えた制限時間が、記録に残っていなかったことです。私は、2つの点をそろえて、測定し直しました。

3件目の不備はOpenHandsの実行で見つかりました。OpenHandsの実行では、サブエージェントが1件も完了しませんでした。私は不具合を再現するプログラムを使って、サブエージェントが失敗したときのエラーを取り出しました。8件のサブエージェントはすべて、起動してから約1.2秒後に、認証の方式が選択されていないというエラーで終了していました。このエラーは3つの原因が重なって起きていました。

1つ目の原因は、親プロセスの環境変数がMCPサーバに渡らなかったことです。測定用のプログラムがAIエージェントを起動する方法では、OpenHandsのCLIの1.16.0の場合だけ、環境変数が渡りませんでした。OpenCodeとQwen Codeの場合は、同じ方法で環境変数が渡りました。ただし、私はOpenHandsの設定の書き方を変えた場合に、親プロセスの環境変数がMCPサーバに渡るかどうかを確認していません。

2つ目の原因は、並列実行のMCPツールが読み込む場所に環境設定のファイルが無かったことです。並列実行のMCPツールは、環境変数の代わりに、このMCPツールが置かれた場所にある環境設定のファイルを読み込みます。隔離した作業ディレクトリで私が測定を実行したため、この場所には環境設定のファイルがありませんでした。

3つ目の原因は、測定用のプログラムが、サブエージェントが使う認証の鍵をMCPの設定の環境変数の項目で渡していなかったことです。

私は測定用のプログラムを修正し、親プロセスの環境変数が引き継がれることを前提にする方法をやめました。修正した後の測定用のプログラムは、サブエージェントが使う認証の鍵をMCPの設定の環境変数の項目に書いて渡します。修正した後に、OpenHandsで測定し直しました。

ルールファイルを読み込ませた実行では、OpenHandsは並列実行のMCPツールを自分から呼び出して、サブエージェントを8件起動しました。8件のサブエージェントはすべて完了し、8件のタスクはすべてテストに合格しました。この実行で初めて、OpenHandsのサブエージェントがすべて完了しました。

ルールファイルを読み込ませなかった実行でも、OpenHandsは並列実行のMCPツールを呼び出しました。呼び出しの記録は3件で、この実行で起動したサブエージェントは合計16件でした。16件のサブエージェントのうち、完了したサブエージェントは1件でした。

そのため、修正する前の測定では、測定用のプログラムの不備が原因で、OpenHandsのサブエージェントが1件も完了しませんでした。AIエージェントの能力の差は原因ではないため、この結果は3種類のAIエージェントの優劣を示しません。ただし、ルールファイルを読み込ませなかった実行では、起動した16件のサブエージェントのうち15件が、認証の鍵以外の理由で完了しませんでした。私はこの15件のサブエージェントが完了しなかった原因をまだ調べていません。

測定用のプログラムを修正した後のOpenHandsの2回の実行は、修正する前の測定でサブエージェントが1件も完了しなかった原因を調べるための、追加の実行です。そのため、私はこの2回の実行を、説明文の1文の有無を比べた測定の24回の実行の集計とは別に記録しました。

ルールファイルに規定を書いた場合だけ呼び出された相談用のMCPツール

私は並列実行のMCPツールと比べるために、相談用のMCPツールも測定しました。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させるMCPツールで、私が自作しました。並列実行のMCPツールの呼び出しは、サブエージェントを複数起動する重い処理です。

相談用のMCPツールは既製のMCPサーバに含まれるツールです。AIエージェントは設計を決める前に、相談用のMCPツールを使って別のモデルに1回だけ意見を求めます。相談用のMCPツールの呼び出しは軽い処理です。

私はプロンプトには、相談用のMCPツールの名前も相談先のモデルも書きませんでした。プロンプトはAIエージェントに渡す指示の文章です。この測定では、ルールファイルに相談についての規定を書くかどうかだけを変えました。ルールファイルは作業の進め方を書いたファイルで、AIエージェントが起動時に読み込みます。

相談についての規定の内容は2つあります。1つ目は、AIエージェントが設計を決める前に別のモデルに意見を求め、返ってきた意見の要点を考慮して決めることです。2つ目は、AIエージェントが別のモデルに意見を求めずに自分だけで決めてはいけないことです。私は規定に相談用のMCPツールの名前も書きました。

この測定の実行は12回で、相談についての規定の有無の2通りと、OpenHands、OpenCode、Qwen Codeの3種類のAIエージェントと、繰り返しの2回の組み合わせです。規定がある場合には、AIエージェントは6回の実行のすべてで相談用のMCPツールを呼び出しました。規定が無い場合には、6回の実行のすべてで相談用のMCPツールを1回も呼び出しませんでした。この測定では、測定用のプログラムの不備は0件でした。測定用のプログラムはAIエージェントを起動し、実行記録を書き、タスクの合否を判定します。

私は中継サーバの記録で、AIエージェントが相談用のMCPツールを呼び出したかどうかを判定しました。中継サーバは、相談用のMCPツールが相談先のモデルに送るリクエストを中継します。この判定では、中継サーバの記録にあるリクエストのうち、次の3つをすべて満たすリクエストだけを数えました。

私は相談用のMCPツールに無効な鍵を設定しました。有効な鍵は中継サーバにだけあり、中継サーバはリクエストを転送するときに無効な鍵を有効な鍵に入れ替えます。そのため、中継サーバを経由しないリクエストは認証に失敗し、中継サーバの記録に残らない相談は成功しません。

ただし、この測定には制約が1つあります。相談用のMCPツールの説明文が既製のMCPサーバに含まれているので、私はこの説明文を変えられませんでした。相談用のMCPツールの測定は、ルールファイルの規定の有無だけを変えた比較です。

処理の重さで要因が変わるという仮説と、分離できていない4つの要因

この節で、私は2つの測定の結果から言える範囲を説明します。1つ目は並列実行のMCPツールの測定です。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させる、私が自作したMCPツールです。2つ目は相談用のMCPツールの測定です。相談用のMCPツールは、AIエージェントが設計を決める前に別のモデルに1回だけ意見を求めるための、既製のMCPツールです。

2つの測定の結果は次のとおりです。並列実行のMCPツールの説明文に、使う場面を書いた1文がある場合だけ、AIエージェントは並列実行のMCPツールを呼び出しました。また、ルールファイルに相談についての規定がある場合だけ、AIエージェントは相談用のMCPツールを呼び出しました。ルールファイルは、AIエージェントが起動時に読み込む、作業の進め方を書いたファイルです。

2つの測定の結果から最初に書いた結論は、次の内容でした。AIエージェントがMCPツールを自分から呼び出すかどうかを決める要因は、呼び出す処理の重さによって変わります。この結論では、重い処理と軽い処理を次のように分けていました。並列実行のMCPツールを呼び出す処理は、サブエージェントを複数起動する重い処理です。相談用のMCPツールを呼び出す処理は、別のモデルに1回だけ意見を求める軽い処理です。最初の結論では、重い処理の場合はMCPツールの説明文が、軽い処理の場合はルールファイルが要因になると説明していました。

私は最初の結論のレビューを依頼し、重大な指摘を受けました。指摘の理由は2つありました。

1つ目の理由は、並列実行のMCPツールの測定でも、私がAIエージェントにルールファイルを読み込ませた場合のほうが、並列実行のMCPツールを呼び出した実行が多かったことです。使う場面を書いた1文があり、ルールファイルを読み込ませた場合に、AIエージェントは6回の実行のうち5回で並列実行のMCPツールを呼び出しました。1文があり、ルールファイルを読み込ませなかった場合は、6回の実行のうち2回で並列実行のMCPツールを呼び出しました。そのため、処理の重さによって要因が入れ替わるという説明は、測定の結果と合いません。

2つ目の理由は、2つの測定の間で4つの点が違うことです。4つの点は、使ったMCPツール、MCPツールの説明文の品質、AIエージェントに渡したタスク、ルールファイルの規定にMCPツールを書いた具体性です。そのため、私はどの違いが結果の原因かを分離できていません。

私はレビューの指摘を受け入れて、最初の結論の断定を取り下げました。そのため、現在は2つの測定の結果を別々に書いています。処理の重さによって要因が変わるという説明を仮説として書き、要因を分離できていないことも書いています。この説明を断定に戻すと、レビューで差し戻された主張をそのまま再び書くことになるため、断定には戻しません。

分離できていない要因は4つあります。統計では、このような要因を交絡要因と呼びます。4つの要因は次のとおりです。

相談用のMCPツールは既製のMCPツールなので、私は相談用のMCPツールの説明文を変えられません。4つの要因を分離するには、1つのMCPツールを対象にして、使う場面を書いた1文の有無とルールファイルの規定の有無を、すべての組み合わせで測定する必要があります。しかし、この測定はまだ実行していません。

呼び出しが0回だった理由を区別するための実行記録の設計

この節では実行記録の設計を説明します。実行記録は、測定用のプログラムが1回の実行ごとに書く記録です。測定用のプログラムは、AIエージェントを起動し、実行記録を書き、タスクの合否を判定するプログラムです。私は測定用のプログラムで、AIエージェントがMCPツールを自分から呼び出すかどうかを測定しました。

実行記録にMCPツールの呼び出しが0回と書いてある場合、その理由は2通りあります。1つ目はAIエージェントがMCPツールを呼び出さなかったことです。2つ目はAIエージェントがMCPツールを呼び出したものの、その呼び出しが数える条件を満たさなかったことです。数える条件は、測定ごとに決めています。たとえば、別のモデルに相談するMCPツールの測定では、応答のステータスコードが200で、応答の本文が空でないリクエストだけを数えました。この2通りの理由を後から区別できるように、私は実行記録の2つのフィールドの役割を次のように分けました。

測定用のプログラムに不備があった実行の行では、私は実行の状態のフィールドを失敗にして、不備を示すフラグを付けます。測定できていない値を記録しないため、その行には呼び出しのフィールドを書きません。

私はここまでに説明した記録の方法を、2026年8月27日から使っています。実行記録のうち2026年8月27日より前の行は、古い方法で記録したまま書き換えていません。実行記録に行を追記するだけにする、という規定があるためです。また、測定用のプログラムの不備で無効になった測定の記録も削除せず、その記録にフラグを付けて残しています。

私は、測定の結論についてレビューを受けました。このレビューの中で、3つの処理を別々の関数に分けました。3つの処理は、呼び出しの回数を数える処理、測定用のプログラムが正常に動作したかどうかを判定する処理、実行記録を組み立てる処理です。3つの関数の動作を10件の単体テストで固定しました。

私は以前、MCPツールの出力の一部を実行記録の備考のフィールドに書き写していましたが、この方法をやめました。現在は呼び出しの合計の回数と回数の内訳を、構造化したデータとして記録しています。

この実験の結果から言えないこと

私はこの節で、この実験の結果から言えないことと、言えることを説明します。この実験では、OpenHands、OpenCode、Qwen Codeの3種類のAIエージェントが自作の並列実行のMCPツールを自分から呼び出す条件を測定しました。並列実行のMCPツールは、複数の独立したタスクをサブエージェントに割り当てて並列に実行させるMCPツールです。

この実験の結果から言えないことは次の6つです。

この実験の結果から言えることは次のとおりです。3種類のAIエージェントでは、私がルールファイルに並列実行のMCPツールの名前と、どの場合に使うかを書いても、サブエージェントがタスクを完了した実行は1回もありませんでした。

私がAIエージェントに要約させるメモを30件に増やしても、タスク1件に必要な推論の量を増やしても、結果は同じでした。メモ30件の測定の6通りと、タスク8件の測定の6通りを合わせた12通りの条件のうち、2通りの条件でだけ、AIエージェントは並列実行のMCPツールを呼び出しました。ただし、2通りの条件のどちらでもサブエージェントは1件も起動しませんでした。

しかし、私が並列実行のMCPツールの説明文に、使う場面を書いた1文を追加した場合にだけ、サブエージェントがタスクを完了した実行がありました。

ただし、AIエージェントがMCPツールを呼び出すかどうかを決める要因が、MCPツールの説明文と、ルールファイルと、呼び出した後に実行される処理の重さのどれであるかは、まだ分離できていません。

参考にした資料

私はこの記事の本文で公開の資料を3件参照しました。2026年9月10日に3件すべての原文を確認し、2026年9月27日にもう一度確認しました。資料ごとに、その内容とこの記事で引用した範囲を以下に書きます。