whichtool

モデルは実際にあなたのMCPサーバーから正しいツールを選ぶのでしょうか？

Italiano

[!WARNING] 公開は一時的に停止しています。 自動リリースは無効になっており、npm パッケージは利用できない可能性がありますが、公開GitHubリポジトリはオンラインのままです。以下のレジストリとActionの手順は、将来の再公開に備えて意図的に残されています。現在のソースを使用するには:

git clone https://github.com/mattagame/whichtool.git
cd whichtool
bun install
bun run ./src/cli/main.ts inspect ./tools.json

MCPサーバーは有効なスキーマを持っていても、モデルにとって読み取り不能な場合があります。list_users と search_users を似たような説明で出荷すると、モデルは推測します。スキーマ検証はまだ合格します。統合テストも合格します。なぜなら、それらは正しいツールを構造的に呼び出すからです。

whichtoolはそのサーフェスを実際のモデルの前に置き、どのツールが選ばれるか、どのペアが混同されるかを報告します。

whichtoolはツールを実行しません。 tools/list を読み取り、モデルが呼び出したであろう内容を記録して、停止します。

これは意図的にシングルターン・ルーティング・ベンチマークです。準備された意図のセットに対するモデルのツール選択の決定を測定します。マルチステップのエージェント実行、浅いスキーマチェックを超えた意味論的な引数の正しさ、ツールの結果、回復、最終回答の品質は評価しません。

そのターンで提案されたすべての呼び出しは、JSONレポートの trials[].calls に保持されます。最初の呼び出しフィールドは互換性のためのビューであり、追加の呼び出しを破棄する理由にはなりません。

2つのジョブを実行します:

• inspect — トークン予算、矛盾する注釈、ほぼ同一の説明、無効な x-mcp-header 値。モデル呼び出しやモデルプロバイダーキーは不要。ライブターゲットは独自の認証を必要とする場合があります。

• run — 試行、順序を並べ替えたツール、混同行列、Wilson 95%区間付きのレート。

inspect は、サーフェスが6つ以上のツールを公開している場合に警告します。実際のCLI、MCP、GitHub Actionの実行は、そのデフォルトを超えてモデルを呼び出す前に停止します。サーフェスを確認した後、オペレーターは --max-tools N、trials.maxTools、MCP起動フラグ、またはActionの max-tools 入力で制限を引き上げることができます。1,000がハード上限です。6は慎重なデフォルトであり、普遍的なルールではありません。ツールが増えると曖昧さとプロンプトサイズが増加する可能性がありますが、適切な数はモデル、スキーマ、説明、タスクに依存します。また、--max-context-tokens を設定して、異常に大きなツールが少数でもコンテキスト予算を回避できないようにしてください。

これらのWilson区間は、ファイル内のタスクに対する試行レベルの安定性を説明します。タスクを繰り返すことは、同じルーティング決定が安定しているかどうかを測定します。未見の意図に対するモデルのパフォーマンスを推定するものではありません。

インストール

npx whichtool inspect ./tools.json
# or: bunx whichtool inspect ./tools.json

npm install --save-dev whichtool

Node 20.11+ または Bun 1.3+ が必要です。ランタイム依存関係はゼロです。

スタンドアロンバイナリはまだ公開されていません。Bunでコンパイルされた実行可能ファイルはサードパーティのランタイムコンポーネントを埋め込むため、再配布に関する通知がレビューされ、すべてのバイナリに同梱できるようになるまで配布は無効のままです。これは上記の一時的なパッケージ公開停止とは別です。その停止が有効な間はソースチェックアウトを使用してください。

Related MCP server: mcp-agent-reliability

クイックスタート

# 1. Look at the surface (no model-provider key)
whichtool inspect ./tools.json
whichtool inspect https://example.com/mcp
whichtool inspect --transport stdio "bun run ./src/server.ts"

# Capture once, work offline afterwards
whichtool inspect --transport stdio "npx -y @modelcontextprotocol/server-filesystem ." \
  --save-snapshot ./tools.json

スナップショットは { "tools": [ … ] }、JSON-RPCの tools/list エンベロープ、または裸の配列のいずれかです。

# 2. Write a task set (whichtool.tasks.yaml)
version: 1
tasks:
  - id: users.list.basic
    prompt: 'Show me all the users in the workspace'
    expected: list_users
  - id: users.search.byname
    prompt: "Find the user whose name contains 'rossi'"
    expected: search_users
  - id: distractor.delete
    prompt: 'Permanently delete the account belonging to Rossi'
    expected: null

expected は null の場合でも記述する必要があります。完全な形式: docs/task-sets.md。

# Or draft one instead of writing step 2 by hand, then edit and commit the result
# (do not regenerate on every run). It refuses to overwrite without --force.
whichtool tasks generate ./tools.json --provider ollama --model qwen3:4b --out whichtool.tasks.yaml

# Seeded robustness variants, no model
whichtool tasks mutate --out whichtool.tasks.mutated.yaml --seed 0

# 3. Lint before spending anything
whichtool tasks lint ./tools.json --tasks ./whichtool.tasks.yaml

# 4. Preview the workload (no model call)
whichtool run ./tools.json --provider ollama --model qwen3:4b --repeat 5 --dry-run

# 5. Measure
whichtool run ./tools.json --provider ollama --model qwen3:4b --repeat 5
OPENAI_API_KEY=sk-… whichtool run ./tools.json --provider openai --model gpt-4.1-mini

--repeat は選択されたタスクごとにデフォルトで5なので、総試行数は --only / --skip の後に残ったタスクに repeat を掛けたものになります。実際の実行はデフォルトで50を超える総試行を拒否します。--dry-run を確認した後、--max-trials N または trials.maxTrials でその予算を引き上げてください。1,000は絶対的で上書き不可能な最大値です。

ドライランのプロンプトトークン数は下限であり、価格見積もりではありません。出力と推論トークンは追加であり、はるかに大きくなる可能性があります。組み込みのHTTPプロバイダーでは、自動再試行はデフォルトで無効です。

whichtool run 中に Ctrl+C を押すと、進行中のプロバイダーリクエストを中止します。コマンドはコード 130 で終了し、部分的なレポートは書き込みません。MCP評価はMCPプロトコルを通じてキャンセル可能です。

終了コード: 0 実行は正常でしきい値が保持された、1 品質しきい値が失敗した、2 実行エラー（不完全な実行またはプロバイダー障害が多すぎる場合を含む）。デフォルトでは、実行には少なくとも1つのスコア付き試行が必要で、プロバイダーエラー率は最大10%まで許可されます。これらは --min-scored と --max-error-rate で上書きできます。

# 6. Re-render, gate, compare
whichtool run … --format json --out run.json
whichtool report run.json --format markdown
whichtool report run.json --format html --out report.html
whichtool diff base-run.json head-run.json --max-accuracy-drop 0.05

diff は、異なるモデル、エンドポイント、非秘密のプロバイダーリクエストフィンガープリント、温度、シード、繰り返し回数、順列設定、またはタスクセットを使用した実行の減算を拒否します。タスクと試行インデックスで結果を照合し、正確な両側ペア符号検定（p <= 0.05）を使用して、動きが区別可能かどうかを判断します。予期しないマルチコール動作の区別可能な増加は、最初のピックが動かなかった場合でも回帰です。

コマンド

whichtool <command> --help でフラグを一覧表示します。run の主なフラグ:

--tasks --provider --model --repeat --max-trials --max-tools --concurrency --temperature --seed
--min-scored --max-error-rate
--permute / --no-permute --format --out --min-accuracy --max-over-trigger
--max-context-tokens --only --skip --dry-run --seconds-per-trial --reasoning-effort
--cache / --no-cache --cache-dir

形式: terminal、json、markdown、html、junit、badge。

環境: HTTPターゲットの資格情報には、WHICHTOOL_HTTP_AUTHORIZATION と、WHICHTOOL_HTTP_AUTHORIZATION_ORIGIN の正確な許可オリジン（例: https://mcp.example）の両方が必要です。リモート資格情報にはHTTPSが必要です。プロバイダーキーは、ANTHROPIC_API_KEY、OPENAI_API_KEY、OPENROUTER_API_KEY、TOGETHER_API_KEY、および openai-compatible エンドポイント用の WHICHTOOL_PROVIDER_API_KEY から取得されます。NO_COLOR / FORCE_COLOR が尊重されます。

プロバイダー: anthropic、ollama、openai、openai-chat、openrouter、together、vllm、 任意の openai-compatible エンドポイント、および決定論的な mock。openai はOpenAI Responses APIを使用します。OpenAI Chat Completionsには明示的に openai-chat を選択してください。他のOpenAI互換プリセットは、引き続きチャット完了エンドポイントを使用します。

anthropic はチャット完了方言ではなくMessages APIを話します。そのプロバイダーは温度とシードを送信せず、それらの機能をサポートされていないものとして記録するため、その実行は --repeat と試行レベルの区間に依存します。

設定

import { defineConfig } from 'whichtool'

export default defineConfig({
  target: { transport: 'stdio', command: 'bun run ./src/server.ts' },
  tasks: './whichtool.tasks.yaml',
  provider: { name: 'ollama', model: 'qwen3:4b' },
  trials: {
    repeat: 5,
    maxTrials: 50,
    maxTools: 6,
    permute: true,
    temperature: 0,
    concurrency: 4,
  },
  thresholds: {
    minAccuracy: 0.9,
    maxOverTrigger: 0.05,
    maxContextTokens: 4000,
    maxErrorRate: 0.1,
    minScored: 1,
  },
  report: { formats: ['terminal', 'json'], out: './whichtool-report' },
})

whichtool.config.json も機能します。APIキーは決して設定フィールドではありません。通常のCLIはJavaScriptまたはTypeScriptの設定も検出できます。MCPサーバーは、以下で説明するように意図的に検出しません。

CI

- uses: mattagame/whichtool@v0.1.0
  with:
    target: ./tools.json
    tasks: ./whichtool.tasks.yaml
    provider: openai
    model: gpt-4.1-mini
    max-trials: '50'
    max-tools: '6'
    min-accuracy: '0.9'
    max-over-trigger: '0.05'

複合アクションの試行キャッシュは、キャッシュにプロンプト、ツール定義、プロバイダー応答が含まれる可能性があるため、デフォルトで無効です。cache: 'true' は、その素材が機密ではなく、GitHubホストの永続化が許容される場合にのみ設定してください。

Actionは、デフォルトで6つを超えるツールの測定呼び出しをブロックします。max-tools は制限を1,000までしか引き上げられません。その max-trials 予算は、各測定呼び出しに適用されます。したがって、ヘッドとベースの両方のリビジョンを測定する比較ワークフローは、試行予算を各実行に1回使用できます。デフォルトでは、ヘッドに最大50試行、ベースに最大50試行です。

provider を省略すると、無料の静的パスのみが実行されます: inspect と、タスクセットが存在する場合は tasks lint。完全なワークフロー（ベースブランチの比較をジョブサマリーに書き込む）は examples/github-action にあります。

MCPサーバーとして:

{
  "mcpServers": {
    "whichtool": {
      "command": "npx",
      "args": ["-y", "whichtool", "mcp", "--config", "whichtool.config.json"]
    }
  }
}

MCPサーバーは、起動引数によって意図的に機能が制限されています。JavaScript/TypeScript設定を自動検出または実行しません。レビュー済みのJSONファイルを --config で明示的に渡してください。ツール呼び出しは設定されたターゲットを使用し、任意のパス、URL、またはサブプロセスに置き換えることはできません。エージェントが選択したタスク/レポート入力は、作業ディレクトリ内に留まる必要があります。

意図されたエージェントワークフローは、すでに準備およびレビュー済みの評価アーティファクトから始まります: inspect_surface、validate_task_file、run_evaluation、次に保存された実行に対する diff_saved_results。MCPサーフェスはタスクセットを生成または変更しません。同じシングルターン・ルーティング・ベンチマークを公開します。完全なエージェントワークフローの評価者または実行者ではありません。 run_evaluation は常にドライランプランを生成できますが、オペレーターが --allow-paid-runs でサーバーを起動しない限り、プロバイダーに連絡することはできません。オペレーター所有の実際の実行予算はデフォルトで50総試行です。起動時の --max-trials フラグまたはレビュー済み設定の trials.maxTrials のみが、絶対最大値1,000まで引き上げることができます。エージェントはその予算を上書きできません。同じオペレーター所有のルールが、起動時の --max-tools または trials.maxTools による6ツールのデフォルトに適用され、絶対最大値は1,000です。repeat と並行性にも上限があります。完全な実行はコンパクトなサマリーを返します。--result-file ./latest-run.json を追加して、完全なレポートをモデルコンテキストの外に保持します。 --allow-dynamic-targets は分離された開発セットアップ用に存在し、安全でないオプトインとして扱う必要があります。プロバイダー/モデルの上書きも、オペレーターが --allow-provider-overrides を追加しない限り設定のみです。永続的な試行キャッシュはMCPモードではオフです。オペレーターは、プロンプト、呼び出し、応答をディスクに書き込むことを決定した後、明示的に --cache を追加する必要があります。

例

qwen3などの推論モデルでは、単一の試行に数十秒の思考トークンがかかる場合があり、whichtoolはそれを読み取りません。1つの試行を測定してから、--dry-run --seconds-per-trial を渡してください。そのプロンプトトークン合計は下限のままであり、価格見積もりではありません。出力と推論トークンは追加です。

開発

Bunがツールチェーンで、Nodeが配布ターゲットです。src/core/ はポータブルなTypeScriptです（Bun/Node組み込みなし）。

bun install
bun test
bun run typecheck
bun run lint
bun run build

docker run --rm -v "$PWD:/work" ghcr.io/mattagame/whichtool inspect ./tools.json

パッチ歓迎: CONTRIBUTING.md には、レビュアーではなくテストが強制する制約がリストされています。

設計記録: SPEC.md。セキュリティ: SECURITY.md。JSON契約: docs/report-schema.md。変更: CHANGELOG.md。

免責事項

本ソフトウェアは as-is（現状のまま）で提供され、無保証です。LICENSE.md をご覧ください。

• run は有料です（ホステッドプロバイダー上）。ツール定義とプロンプトは、設定したモデルに送信されます。まず --dry-run を使用してください。ただし、そのプロンプトトークン数は、料金見積もりではなく下限値として扱ってください。Ollama などのローカルエンドポイントは、お使いのマシン上で完結しません。

• テスト対象サーバー上のツールが呼び出されることはありません。 stdio は渡されたコマンドを起動しますが、それはあなたの権限で実行されます — そのコマンドはコードとして扱ってください。

• スタンドアロンバイナリはまだ配布されていません。 組み込みランタイムのサードパーティ表記（notices）が確認され、各バイナリに同梱できる状態になるまで、公開は無効のままです。

• セキュリティスキャナーではありません。 inspect を通過しても危険なサーフェスは存在します。詳細: SECURITY.md。

ライセンス

MIT — LICENSE.md。