tool-search

参考資料（アーカイブ）： SCAFFOLD_SKILLS_ARCHIVE_MAP.md — everything-claude-code の backend-patterns、tdd-workflow に基づく、埋め込みを利用したセマンティックなツール検出。

ツール検索スキル

概要

ツール検索 — 埋め込みを利用したセマンティックなツール検出を提供し、コンテキストを90％以上削減しながら、数十から数千のツールに対応できます。

機能

• セマンティックなツール検索：タスクのコンテキストに基づいて関連するツールを見つけます
• 埋め込みベースのマッチング：埋め込みを使用して、正確なツール検出を行います
• オンデマンド読み込み：必要なときにだけツールを読み込みます
• コンテキスト効率：ツール定義のトークンを90％以上削減します

課題

従来のツール読み込み：

• すべてのツールを事前に読み込みます
• 58個のツールで約55Kトークンを消費します
• コンテキストがすぐに埋まります
• 約100個を超える規模への拡張が困難です

解決策

埋め込みを利用したツール検索：

• 初期状態で読み込むのは、ツール検索ツールのみ（約500トークン）です
• セマンティック検索により、必要に応じてツールを検出します
• 検索ごとに関連するツールを3〜5個読み込みます（約3Kトークン）
• 合計：約8.7Kトークン。従来の約77Kトークンから85％削減できます

仕組み

1. 初期状態：ツール検索ツールと重要なツールのみを読み込みます
2. ツール検出：エージェントがタスクに基づいてツールを検索します
3. セマンティックマッチング：埋め込みによって、ツールとタスクのコンテキストを照合します
4. ツールの展開：一致したツールを完全な定義に展開します
5. ツールの使用：エージェントが検出したツールを使用します

設定

MCP 設定（.claude/.mcp.json）

{
  "betaFeatures": ["advanced-tool-use-2025-11-20"],
  "toolSearch": {
    "enabled": true,
    "autoEnableThreshold": 20,
    "defaultDeferLoading": true
  },
  "mcpServers": {
    "repo": {
      "deferLoading": true,
      "alwaysLoadTools": ["search_code", "read_file"]
    },
    "github": {
      "deferLoading": true,
      "alwaysLoadTools": ["create_pull_request", "get_issue"]
    }
  }
}

重要なツールを常に読み込む

最もよく使う3〜5個のツールは、常に読み込んでおきます：

• 基本的なファイル操作：read_file、write_file、search_code
• 必須の連携機能：create_pull_request、get_issue
• よく使う機能：take_screenshot、navigate_page

使用パターン

ツール検索を使うタイミング

特に効果的な場合：

• ツール定義が10Kを超えるトークンを消費している
• ツールライブラリに10個以上のツールがある
• ツール選択の精度に問題がある
• 複数のサーバーを使用する、MCP を活用したシステムを構築している

効果が小さい場合：

• ツールライブラリが小規模（10個未満）
• すべてのツールを各セッションで頻繁に使用する
• ツール定義がコンパクトである

ツールの検出

エージェントのワークフロー：

1. エージェントが必要な機能を判断します（例：「プルリクエストを作成する」）
2. エージェントが「github pull request creation」を検索します
3. ツール検索がcreate_pull_requestツールを返します
4. ツールが完全な定義に展開されます
5. エージェントがツールを使用します

例：

User: "Create a pull request for my changes"

Agent searches: "github pull request creation"
Tool Search finds: create_pull_request tool
Tool loaded and used

ベストプラクティス

1. 明確なツール名と説明

良い例：

{
  "name": "search_customer_orders",
  "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
}

悪い例：

{
  "name": "query_db_orders",
  "description": "Execute order query"
}

2. システムプロンプトでのガイダンス

エージェントのプロンプトにガイダンスを追加します：

You have access to tools for Slack messaging, Google Drive file management,
Jira ticket tracking, and GitHub repository operations. Use the tool search
to find specific capabilities when needed.

3. 重要なツールを常に読み込む

以下の読み込みは後回しにしないでください：

• 基本的なファイル操作
• 必須の連携機能
• よく使うツール

4. ツールの使用状況を監視する

検出されたツールを追跡します：

• 検索頻度の高いツール
• ツール検出のパターン
• 実現したコンテキスト削減量

実装

埋め込みベースのツール検索

ツール検索では、埋め込みを利用してツールとクエリを照合します：

1. ツールのインデックス化：すべてのツール定義の埋め込みを作成します
2. クエリの埋め込み：ユーザーのクエリの埋め込みを作成します
3. 類似度検索：埋め込みが類似するツールを見つけます
4. ツールの展開：一致したツールをコンテキストに読み込みます

ツール検索ツール

ツール検索ツール自体は、次の機能を提供します：

• ツールライブラリをセマンティックに検索します
• クエリに基づいて関連するツールを返します
• ツールを完全な定義に展開します
• ツールのインデックスを維持します

メリット

コンテキスト効率

• ツール定義のトークンを85％削減
• コンテキスト全体の52.5％（87％から減少）
• 最適な範囲内（目標は60〜70％）

精度の向上

• ツール選択の精度が11％向上
• 79.5％ → 88.1％（Opus 4.5）
• 複雑なクエリでも、ツールのマッチングが向上します

拡張性

• 数千のツールに対応
• コンテキスト上限を心配する必要がありません
• ツールを動的に検出します

例

例1：GitHub の操作

User: "Create a pull request"

Agent workflow:
1. Searches: "github pull request creation"
2. Tool Search finds: create_pull_request tool
3. Tool loaded (3K tokens)
4. Agent uses tool
5. Total context: ~8.7K tokens (vs. 55K traditional)

例2：ファイル操作

User: "Search for authentication code"

Agent workflow:
1. Searches: "code search file operations"
2. Tool Search finds: search_code, read_file tools
3. Tools loaded (5K tokens)
4. Agent uses tools

例3：複数の連携機能

User: "Check Slack messages and create Jira ticket"

Agent workflow:
1. Searches: "slack message reading"
2. Tool Search finds: read_slack_message tool
3. Searches: "jira ticket creation"
4. Tool Search finds: create_jira_ticket tool
5. Both tools loaded (6K tokens total)

連携

MCP サーバーとの連携

ツール検索はMCP サーバーで機能します。

• GitHub MCP：35個のツール → 必要に応じて3～5個を読み込み
• Slack MCP：11個のツール → 必要に応じて2～3個を読み込み
• カスタムMCP：ツール数は任意 → 必要に応じて読み込み

エージェントシステムとの連携

すべてのエージェントがツール検索のメリットを得られます。

• コンテキスト使用量の削減
• より適切なツール選択
• 拡張可能なツールライブラリ

トラブルシューティング

ツールが見つからない

• ツール名と説明が明確であることを確認します
• ツール検索が有効になっていることを確認します
• 検索クエリを見直します
• ツールのインデックスが最新であることを確認します

コンテキストが依然として大きい

• deferLoadingが有効になっていることを確認します
• alwaysLoadToolsリストを確認します（最小限にする必要があります）
• ツール定義を見直します（冗長すぎる可能性があります）
• 実際のツール使用状況を監視します

ツール選択に関する問題

• ツールの説明を改善します
• 検索クエリにコンテキストを追加します
• ツールの命名規則を見直します
• 埋め込みの品質を確認します

プログラムによるツール呼び出し（PTC）との連携

ツール検索はプログラムによるツール呼び出しと非常に相性が良いです。

1. ツール検索で関連するツールを見つけます（必要に応じて読み込み）
2. PTCでツールを効率的に調整します（コンテキストを削減）
3. 結果：トークン消費を最小限に抑えた最適なツール使用

ワークフローの例：

# Tool Search finds tools
tools = search_tools("github issue management")

# PTC orchestrates multiple tool calls
team = await get_team_members("engineering")
issues = await asyncio.gather(*[
    get_issue(member["github_username"]) for member in team
])
# Only final results in context, not all intermediate data

PTCの包括的なドキュメントについては、PTCパターンガイドを参照してください。

関連ドキュメント

• 高度なツール使用 - 包括的なツール使用ガイド
• PTCパターン - プログラムによるツール呼び出しのパターン
• コンテキストの最適化 - コンテキスト管理

参考資料

• 埋め込みを使ったツール検索のクックブック
• プログラムによるツール呼び出しのクックブック
• 高度なツール使用のドキュメント

**コマンドの例**：

# Search for git-related tools
node .claude/tools/tool_search.mjs --query "git"

# Search for database tools
node .claude/tools/tool_search.mjs --query "database" --limit 3

# Search for testing tools
node .claude/tools/tool_search.mjs --query "testing"

</usage_example>

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.mdを読みます

完了後：

• 新しいパターン → .claude/context/memory/learnings.md
• 見つかった問題 → .claude/context/memory/issues.md
• 決定事項 → .claude/context/memory/decisions.md

中断を前提とします：メモリに記録されていなければ、実行されていないものとします。