# mcp-tools Specification

## Purpose
TBD - created by archiving change fix-search-content-parameters. Update Purpose after archive.
## Requirements
### Requirement: 出力形式パラメータ排他制御

search_contentツールは出力形式に関連するパラメータの同時指定を検証し、競合を防止しなければならない（MUST）。

#### Scenario: 単一出力形式パラメータの許可

**Given** search_contentツールにアクセスする場合
**When** `total_only=True`のみを指定する
**Then** 処理が正常に実行される
**And** 期待される形式の結果が返される

#### Scenario: 複数出力形式パラメータの拒否

**Given** search_contentツールにアクセスする場合
**When** `total_only=True`と`count_only_matches=True`を同時に指定する
**Then** バリデーションエラーが発生する
**And** 明確なエラーメッセージが返される
**And** "出力形式パラメータは排他的です"という内容のメッセージが含まれる

#### Scenario: 全出力形式パラメータの排他制御

**Given** search_contentツールにアクセスする場合
**When** `total_only`、`count_only_matches`、`summary_only`、`group_by_file`、`optimize_paths`のうち複数を同時指定する
**Then** バリデーションエラーが発生する
**And** 競合するパラメータ名が明示される

### Requirement: max_count機能の正常動作

search_contentツールはmax_countパラメータが指定された場合、ripgrepコマンドに正しく`-m`オプションを適用しなければならない（MUST）。

#### Scenario: max_countパラメータの適用

**Given** search_contentツールにmax_countパラメータを指定する場合
**When** `max_count=5`を設定してクエリを実行する
**Then** ripgrepコマンドに`-m 5`オプションが含まれる
**And** 結果の件数が5件以下に制限される

#### Scenario: max_countのデフォルト値適用

**Given** search_contentツールでmax_countを指定しない場合
**When** 検索クエリを実行する
**Then** デフォルトの制限値が適用される
**And** ripgrepコマンドに適切な`-m`オプションが含まれる

#### Scenario: max_countの上限制御

**Given** search_contentツールに過大なmax_countを指定する場合
**When** `max_count=50000`を設定する
**Then** 安全な上限値（10000）に調整される
**And** ripgrepコマンドに`-m 10000`が適用される

### Requirement: キャッシュキー生成改善

search_contentツールのキャッシュシステムは出力形式パラメータを考慮した適切なキャッシュキー生成を行わなければならない（MUST）。

#### Scenario: 出力形式別キャッシュキー生成

**Given** 同一の検索クエリで異なる出力形式を指定する場合
**When** 最初に`total_only=True`で実行し、次に`count_only_matches=True`で実行する
**Then** 異なるキャッシュキーが生成される
**And** それぞれの形式に対応した結果が返される

#### Scenario: キャッシュヒット時の形式一致

**Given** キャッシュに保存された検索結果が存在する場合
**When** 同じクエリと出力形式で再度検索する
**Then** キャッシュから適切な形式の結果が返される
**And** `cache_hit=True`が設定される

#### Scenario: 形式変更時のキャッシュミス

**Given** `total_only=True`でキャッシュされた結果が存在する場合
**When** 同じクエリで`summary_only=True`を指定する
**Then** キャッシュミスが発生する
**And** 新しい検索が実行される
**And** 適切な形式の結果が返される

### Requirement: エラーハンドリング強化

search_contentツールは明確で有用なエラーメッセージを提供し、デバッグを支援しなければならない（MUST）。

#### Scenario: パラメータ競合エラーの詳細

**Given** 競合する出力形式パラメータを指定する場合
**When** バリデーションエラーが発生する
**Then** エラーメッセージに競合するパラメータ名が含まれる
**And** 正しい使用方法の例が提示される

#### Scenario: max_count範囲外エラー

**Given** 不正なmax_count値を指定する場合
**When** 負の値や文字列を指定する
**Then** 適切なエラーメッセージが返される
**And** 許可される値の範囲が明示される

### Requirement: 後方互換性維持

search_contentツールの修正は既存のAPIや動作を変更せず、完全な後方互換性を維持しなければならない（MUST）。

#### Scenario: 既存パラメータの動作保持

**Given** 修正前のsearch_contentツール使用コードが存在する場合
**When** 修正後のツールで同じパラメータを使用する
**Then** 同一の結果が返される
**And** エラーが発生しない

#### Scenario: レガシー出力形式の保持

**Given** 出力形式パラメータを指定しない場合
**When** 検索を実行する
**Then** デフォルトの標準形式で結果が返される
**And** 従来と同じフィールド構成が維持される

### Requirement: 型安全性とコード品質

search_contentツール関連のコードはmypyとruffの品質チェックに完全に準拠しなければならない（MUST）。

#### Scenario: 型注釈の完全性

**Given** search_contentツール関連のPythonコードを検査する場合
**When** `mypy --strict`を実行する
**Then** 型エラーが発生しない
**And** 全ての関数と変数に適切な型注釈が付与されている

#### Scenario: コード品質基準準拠

**Given** search_contentツール関連のコードを検査する場合
**When** `ruff check`を実行する
**Then** lintエラーが発生しない
**And** PEP 8準拠のコード記述になっている

### Requirement: テストカバレッジと品質保証

search_contentツールの修正は包括的なテストスイートでカバーされ、90%以上のテストカバレッジを維持しなければならない（MUST）。

#### Scenario: 新機能のテストカバレッジ

**Given** 新たに追加された機能を検証する場合
**When** テストスイートを実行する
**Then** 全ての新機能がテストされている
**And** エッジケースとエラーケースがカバーされている

#### Scenario: 既存機能の非破壊テスト

**Given** 既存のsearch_content関連テストを実行する場合
**When** 修正後のコードでテストする
**Then** 全ての既存テストが通過する
**And** 予期しないテスト失敗が発生しない

### Requirement: search_contentツールのLLMガイダンス強化

search_contentツールは、LLMが自律的に最適なパラメータを選択できるよう、トークン効率性とベストプラクティスに関する包括的なガイダンスをツール定義に埋め込まなければならない（MUST）。

#### Scenario: ツール説明への効率性ガイドセクション追加

**GIVEN** search_contentツールの定義を参照する場合
**WHEN** LLMがツールのdescriptionフィールドを読む
**THEN** description冒頭に以下のセクションが含まれる：
- `⚠️ IMPORTANT: Token Efficiency Guide` - トークン効率性の重要性説明
- `🎯 RECOMMENDED WORKFLOW` - 段階的使用戦略のフローチャート
- `💡 TOKEN EFFICIENCY COMPARISON` - 各出力形式のトークンコスト比較表

**AND** 各セクションが明確に区切られている
**AND** 最重要情報が先頭に配置されている

#### Scenario: トークン効率性比較表の提供

**GIVEN** search_contentツールの出力形式を選択する場合
**WHEN** LLMがツール定義を参照する
**THEN** description内に以下の形式でトークンコスト比較表が含まれる：

```
💡 TOKEN EFFICIENCY COMPARISON:
  total_only:          ~10 tokens      (最も効率的)
  count_only_matches:  ~50-200 tokens  (ファイル数依存)
  summary_only:        ~500-2000 tokens
  group_by_file:       ~2000-10000 tokens
  Normal (full):       ~10000-50000 tokens (マッチ数依存)
```

**AND** 各形式の適用シナリオが併記される

#### Scenario: 段階的使用フローの明示

**GIVEN** search_contentツールで段階的に情報を取得する場合
**WHEN** LLMがツール定義を参照する
**THEN** description内に以下の推奨ワークフローが含まれる：

```
🎯 RECOMMENDED WORKFLOW:
  Step 1: Use total_only=true to check if matches exist (0件なら終了)
  Step 2: Use count_only_matches=true for file distribution (少数ファイルならStep 3)
  Step 3: Use summary_only=true for overview (詳細が必要ならStep 4)
  Step 4: Use group_by_file=true for organized results (全詳細が必要ならStep 5)
  Step 5: Use normal mode for complete details
```

**AND** 各ステップでの判断基準が明示される

### Requirement: 出力形式パラメータ説明の強化

search_contentツールの各出力形式パラメータは、効率性順位、推奨シナリオ、排他性警告を含む詳細な説明を持たなければならない（MUST）。

#### Scenario: total_onlyパラメータの完全な説明

**GIVEN** total_onlyパラメータを選択する場合
**WHEN** LLMがパラメータのdescriptionを読む
**THEN** 以下の情報が含まれる：
- 「Return only the total match count as a number」（基本説明）
- 「Most token-efficient option (~10 tokens)」（効率性順位）
- 「Best for: checking if matches exist, quick filtering, large-scale searches」（推奨シナリオ）
- 「⚠️ EXCLUSIVE: Cannot be used with count_only_matches, summary_only, group_by_file, or optimize_paths」（排他性警告）
- 「Takes priority over all other output formats」（優先順位）

#### Scenario: count_only_matchesパラメータの完全な説明

**GIVEN** count_only_matchesパラメータを選択する場合
**WHEN** LLMがパラメータのdescriptionを読む
**THEN** 以下の情報が含まれる：
- 「Return only match counts per file instead of full match details」（基本説明）
- 「Token-efficient (~50-200 tokens depending on file count)」（効率性順位）
- 「Best for: understanding distribution across files, identifying hotspots」（推奨シナリオ）
- 「⚠️ EXCLUSIVE: Cannot be used with total_only, summary_only, group_by_file, or optimize_paths」（排他性警告）

#### Scenario: summary_onlyパラメータの完全な説明

**GIVEN** summary_onlyパラメータを選択する場合
**WHEN** LLMがパラメータのdescriptionを読む
**THEN** 以下の情報が含まれる：
- 「Return a condensed summary of results to reduce context size」（基本説明）
- 「Moderate efficiency (~500-2000 tokens)」（効率性順位）
- 「Best for: initial investigation, understanding scope before diving deep」（推奨シナリオ）
- 「Shows top files and sample matches」（動作説明）
- 「⚠️ EXCLUSIVE: Cannot be used with total_only, count_only_matches, group_by_file, or optimize_paths」（排他性警告）

#### Scenario: group_by_fileパラメータの完全な説明

**GIVEN** group_by_fileパラメータを選択する場合
**WHEN** LLMがパラメータのdescriptionを読む
**THEN** 以下の情報が含まれる：
- 「Group results by file to eliminate file path duplication」（基本説明）
- 「More efficient than normal (~2000-10000 tokens)」（効率性順位）
- 「Best for: reviewing matches in context, reducing path duplication」（推奨シナリオ）
- 「Significantly reduces tokens when multiple matches exist in same files」（効果説明）
- 「⚠️ EXCLUSIVE: Cannot be used with total_only, count_only_matches, summary_only, or optimize_paths」（排他性警告）

#### Scenario: optimize_pathsパラメータの完全な説明

**GIVEN** optimize_pathsパラメータを選択する場合
**WHEN** LLMがパラメータのdescriptionを読む
**THEN** 以下の情報が含まれる：
- 「Optimize file paths in results by removing common prefixes」（基本説明）
- 「Token savings: ~10-30% depending on path depth」（効率性順位）
- 「Best for: deep directory structures, token budget constraints」（推奨シナリオ）
- 「⚠️ EXCLUSIVE: Cannot be used with total_only, count_only_matches, summary_only, or group_by_file」（排他性警告）

### Requirement: 排他性エラーメッセージの多言語化

search_contentツールの出力形式パラメータ競合エラーは、英語と日本語の両方で明確なメッセージを提供しなければならない（MUST）。

#### Scenario: 英語エラーメッセージの詳細化

**GIVEN** 複数の出力形式パラメータが同時指定された場合
**WHEN** 英語ロケールでエラーが発生する
**THEN** 以下の形式のエラーメッセージが返される：

```
Output format parameters are mutually exclusive. 
Multiple formats specified: total_only, count_only_matches.
Please specify only one of: total_only, count_only_matches, summary_only, group_by_file, optimize_paths.

Examples of correct usage:
  - For count only: {"total_only": true}
  - For per-file counts: {"count_only_matches": true}
  - For summary: {"summary_only": true}
```

#### Scenario: 日本語エラーメッセージの詳細化

**GIVEN** 複数の出力形式パラメータが同時指定された場合
**WHEN** 日本語ロケールまたはデフォルトでエラーが発生する
**THEN** 以下の形式のエラーメッセージが返される：

```
出力形式パラメータは排他的です。複数指定できません: total_only, count_only_matches.
次のうち1つのみ指定してください: total_only, count_only_matches, summary_only, group_by_file, optimize_paths.

正しい使用例:
  - 件数のみ取得: {"total_only": true}
  - ファイル別件数: {"count_only_matches": true}
  - サマリー取得: {"summary_only": true}
```

### Requirement: ドキュメントとツール定義はMUST同期

search_contentツールの説明改善は、関連するドキュメント（Rooルール、READMEなど）にも反映され、一貫性が維持されなければならない（MUST）。

#### Scenario: Rooルールへのベストプラクティス追加

**GIVEN** search_contentツールのベストプラクティスが定義された場合
**WHEN** Rooルールファイルを更新する
**THEN** `.roo/rules/`に以下の内容が追加される：
- トークン効率的な検索戦略
- 段階的情報取得のフロー
- 出力形式パラメータの排他性ルール

#### Scenario: README文書の更新

**GIVEN** search_contentツールの使用方法が改善された場合
**WHEN** プロジェクトREADMEを更新する
**THEN** 以下のセクションが追加または更新される：
- 「Token-Efficient Search Strategies」
- 「Output Format Selection Guide」
- 「Common Pitfalls and Solutions」

### Requirement: 実装の後方互換性

search_contentツールの説明改善は、既存のAPI、パラメータ、動作を一切変更せず、完全な後方互換性を維持しなければならない（MUST）。

#### Scenario: 既存パラメータの動作保持

**GIVEN** 説明改善前のsearch_contentツール使用コードが存在する場合
**WHEN** 説明改善後のツールで同じパラメータを使用する
**THEN** 同一の結果が返される
**AND** エラーが発生しない
**AND** レスポンス形式が変更されない

#### Scenario: 新規ユーザーへの明確なガイダンス

**GIVEN** search_contentツールを初めて使用するLLMの場合
**WHEN** ツール定義を読んで最適なパラメータを選択する
**THEN** 明確なガイダンスに基づいて適切な出力形式を選択できる
**AND** 不要なトークン消費を回避できる
**AND** エラーを起こさずに実行できる

