# GPT-5.4+ Tool Search (Tool Narrowing) 改善方針

GPT-5.4以降のResponses API環境において、`UAGENT_ENABLE_GPT54_TOOL_SEARCH=true`（ツール絞り込み機能）を有効にした際にLLMの挙動が不安定になる問題を解決するための改善方針です。

## 1. 現状の課題
現在の実装（`src/uagent/llm_tool_narrowing.py`）は、**直前のユーザーの1発言（`latest_user_text`）のみ**を基準に `get_tool_catalog` でツールを検索・絞り込んでいます。

- **文脈の喪失（ステートレスの限界）**:
  「ファイルを検索し、見つかったら中身を読む」といったマルチターンのタスクにおいて、2ターン目以降は直前の発言がツール実行結果やLLM自身の思考に置き換わるため、最初のユーザー指示（「中身を読んで」）という文脈が検索クエリから消え、必要なツール（`read_file`など）がLLMの選択肢から排除されてしまいます。
- **キーワード一致の限界**:
  日本語の表記揺れや「暗黙の意図（例: 『DEVELOP.mdを読んで』に対して `read_file` を連想する）」に対して、簡易的なキーワードスコアリングでは適合するツールを正しくヒットさせられないケースがあります。

---

## 2. 改善方針案

### 方針A: クエリ生成に「会話履歴（コンテキスト）」を取り込む
直前の1発言だけでなく、会話の文脈を維持したクエリを作成します。
- **実装イメージ**:
  直近3〜5ターン程度のユーザー発言を結合してクエリにする、あるいはシステムプロンプトを除くスレッド全体のユーザー発言からキーワードを抽出して検索クエリを構成します。

### 方針B: 常に露出させる「コアツールセット」の定義
タスクの進行に不可欠な汎用性の高いツールを「常時露出（常時有効）」として定義し、絞り込みロジックから除外します。
- **対象候補**:
  - `read_file` (ファイル閲覧)
  - `list_dir` / `file_exists` (環境確認)
  - `finish_skill` (タスク完了)
  - `human_ask` (対話・確認: 現在も常時露出)

### 方針C: ツール間の「依存関係（チェイン）」による連動露出
あるツールがヒットした際、それと高確率で併用される関連ツールを自動的にホワイトリストへ追加します。
- **連動例**:
  - `search_files` や `file_grep` がヒットした場合 → `read_file` も自動露出
  - `create_file` がヒットした場合 → `python_compile` や `lint_format` も自動露出

### 方針D: セマンティック検索（Embedding）の検討
キーワードの部分一致に頼らず、ユーザーの意図とツールの `description` をベクトル化して類似度検索を行うことで、表記揺れや暗黙の意図（「catして」「中身を見せて」など）を正しくマッピングします。

---

## 3. 次のアクション（TODO）
1. [ ] `src/uagent/llm_tool_narrowing.py` の `_select_tool_specs_for_gpt54` において、`call_messages` から直近複数ターンのユーザー発言をマージしてクエリにするプロトタイプの実装。
2. [ ] 常時露出させる「コアツール」リストを定義し、絞り込み結果に常にマージするロジックの追加。
3. [ ] 開発環境でのマルチターンタスク（検索 → 読み込み → 編集）におけるツール生存率の検証。
