MCP Tool Description ガイドライン

📋 目的

このガイドラインは、MCP (Model Context Protocol) ツールの [Description] 属性を効果的に記述するためのベストプラクティスをまとめたものです。

なぜ重要か

LLM の理解向上: 適切な Description により、AI がツールの使い方を正確に理解できる
ユーザー体験: 開発者がツールの目的と使い方を迅速に把握できる
誤用防止: 明確な境界を示すことで、不適切な使い方を防ぐ
保守性: 統一されたフォーマットにより、複数のツール間で一貫性を保つ

🏗️ Description 構造のベストプラクティス

推奨構造

[概要] - 1行でツールの機能を説明
RECOMMENDED FIRST STEPS - 初めて使うユーザー向けの導線（オプション）
WHEN TO USE - 適切な使用シーン
DO NOT USE WHEN - 使うべきでないシーン（代替手段を含む）
[RULES] - パラメータや入力の制約
REQUIREMENTS - 必要な環境やツール
EXAMPLES - 具体的な使用例
[RETURNS/NOTE] - 戻り値や補足情報（情報取得系ツール向け）

📋 Description セクション一覧

必須セクション

全てのツールで必ず含めるべきセクション

セクション名	ツールタイプ	説明	使用例
概要	全て	ツールの機能を1〜2行で説明	`Markdown とナレーションからプレゼンテーション動画を生成します。`
WHEN TO USE	全て	ツールを使うべきシーン	`社内資料を作りたい時`
DO NOT USE WHEN	全て	使うべきでないシーン + 代替手段	`スライドだけ作りたい（use generate_slide）`
REQUIREMENTS	全て	必要な環境やツール	`VOICEVOX がインストールされていること`
EXAMPLES	全て	具体的な使用例	`✓ 'このMarkdownを動画にして'`

条件付き必須セクション

該当する場合は必ず含めるべきセクション

セクション名	ツールタイプ	条件	説明	使用例
GENERATION RULES	処理実行系	生成処理に制約がある場合	生成処理のルール	`スライド数とナレーション数を一致させてください`
IMPORTANT RULES	全て	重要な制約がある場合	重要な制約	`日本語で記述してください`
RETURNS	情報取得系	戻り値が複雑な場合	戻り値の内容	`利用可能なナレーター一覧を返します`

オプションセクション（推奨）

該当する場合は含めることを推奨するセクション

セクション名	ツールタイプ	いつ使うか	説明	使用例
RECOMMENDED FIRST STEPS	処理実行系	複雑なツール、事前確認が必要な場合	初めて使うユーザー向けの導線	`まず GetXxxGuide() でガイドを確認してください`
NOTE	情報取得系	補足説明が必要な場合	補足情報	`設定がない場合はデフォルト値を返します`
LIMITATIONS	全て	機能制限がある場合	機能の制限	`同時実行は3つまで`
PERFORMANCE NOTES	処理実行系	処理時間が長い場合	パフォーマンスに関する注意	`処理には約30秒かかります`
TROUBLESHOOTING	全て	よくある問題がある場合	よくある問題と解決策	`音声が生成されない場合はXxxを確認`

オプションセクション（高度）

必要に応じて追加する高度なセクション

セクション名	ツールタイプ	いつ使うか	説明	使用例
INPUT FORMAT	処理実行系	入力形式が特殊な場合	入力データの形式	`JSON 形式で提供してください`
OUTPUT FORMAT	処理実行系	出力形式を明示したい場合	出力データの形式	`MP4 形式で出力されます`
INPUT RULES	処理実行系	入力パラメータに制約がある場合	入力パラメータのルール	`最大長は1000文字です`
DEPENDENCIES	全て	特定バージョンの依存がある場合	依存する他のツール/サービス	`FFmpeg 6.0 以降が必要`
SECURITY CONSIDERATIONS	全て	機密データを扱う場合	セキュリティ上の考慮事項	`機密情報は含めないでください`
RATE LIMITS	全て	レート制限がある場合	レート制限	`1時間に10回まで実行可能`
CACHING	情報取得系	キャッシング機能がある場合	キャッシングに関する情報	`結果は5分間キャッシュされます`
ERROR HANDLING	処理実行系	エラー処理が特殊な場合	エラー処理の説明	`失敗時は部分的な結果を返します`
BEST PRACTICES	全て	推奨される使い方がある場合	推奨される使い方	`大量のスライドは分割して処理`
ADVANCED OPTIONS	処理実行系	高度なカスタマイズが可能な場合	高度なオプション	`--quality オプションで品質調整可能`
RELATED TOOLS	全て	関連ツールがある場合	関連する他のツール	`GetXxxGuide(), GenerateXxx() も参照`
VERSIONING	全て	バージョン情報を明示したい場合	バージョン情報	`v2.0 以降で利用可能`
DEPRECATION WARNING	全て	非推奨になった場合	非推奨警告	`このツールは v3.0 で削除予定です`

セクションの優先順位

優先度1: 必須（全ツール）

概要
WHEN TO USE
DO NOT USE WHEN
REQUIREMENTS
EXAMPLES

優先度2: 条件付き必須

GENERATION RULES / IMPORTANT RULES（制約がある場合）
RETURNS（情報取得系ツール）

優先度3: オプション（推奨）

RECOMMENDED FIRST STEPS（複雑なツール）
NOTE（情報取得系）
LIMITATIONS（制限がある場合）
PERFORMANCE NOTES（処理時間が長い場合）
TROUBLESHOOTING（よくある問題がある場合）

優先度4: オプション（高度）

上記以外の高度なセクションは、必要に応じて追加

セクションの組み合わせパターン

パターン1: シンプルな処理実行系ツール

概要 → WHEN TO USE → DO NOT USE WHEN → REQUIREMENTS → EXAMPLES

パターン2: 複雑な処理実行系ツール（推奨）

概要 → RECOMMENDED FIRST STEPS → WHEN TO USE → DO NOT USE WHEN 
→ GENERATION RULES → REQUIREMENTS → EXAMPLES

パターン3: 情報取得系ツール

概要 → WHEN TO USE → RETURNS → NOTE → EXAMPLES

パターン4: 高度な処理実行系ツール

概要 → RECOMMENDED FIRST STEPS → WHEN TO USE → DO NOT USE WHEN 
→ INPUT FORMAT → GENERATION RULES → OUTPUT FORMAT → LIMITATIONS 
→ REQUIREMENTS → PERFORMANCE NOTES → EXAMPLES → TROUBLESHOOTING

📖 各セクションの詳細

1. 概要（必須）

目的: ツールが何をするかを1〜2行で簡潔に説明

[Description("""
    Markdown とナレーションからプレゼンテーション動画を生成します。
    
    ...
""")]

ポイント:

動詞で始める（例: 「生成します」「取得します」「変換します」）
入力と出力を明確にする
専門用語は最小限に

2. RECOMMENDED FIRST STEPS（オプション・推奨）

目的: 初めてツールを使うユーザーに適切な順序を示す

RECOMMENDED FIRST STEPS:
- 初めて使用する場合は、まず GetPresentationVideoGenerationGuide() でガイドを確認してください
- 利用可能なナレーターや設定を確認するには、GetPresentationVideoKnowledge() でナレッジを参照してください
- これらの情報を確認することで、より適切な動画を生成できます

いつ使うか:

ツールが複雑で、事前に確認すべき情報がある場合
関連する情報取得ツール（ガイド、ナレッジ）がある場合
パラメータの選択肢が多く、事前調査が推奨される場合

ポイント:

箇条書きで明確に
関連ツールへの明示的な参照
「なぜ確認すべきか」の理由を含める

3. WHEN TO USE（必須）

目的: ツールを使うべきシーンを明確にする

WHEN TO USE:
- Markdown からスライド＋音声付き動画を作りたい時
- 社内資料・説明動画・納品用動画を生成したい時
- Marp + VOICEVOX + FFmpeg をまとめて使いたい時

ポイント:

具体的なユースケースを列挙
ビジネス価値を示す（「社内資料」「納品用」など）
技術的な詳細は簡潔に

4. DO NOT USE WHEN（必須）

目的: 誤用を防ぎ、適切な代替手段を示す

DO NOT USE WHEN:
- スライドだけ作りたい（use generate_slide_markdown）
- 音声だけ作りたい（use generate_voice）

ポイント:

代替ツールを明示的に示す（use tool_name）
なぜ適切でないかを簡潔に説明
境界を明確にする

5. ルールセクション（必須）

種類:

GENERATION RULES - 生成処理のルール
IMPORTANT RULES - 重要な制約
INPUT RULES - 入力パラメータのルール
NARRATION RULES - ナレーション特有のルール（音声生成時）

GENERATION RULES:
- スライドの数とナレーションの数は同じにしてください
- マークダウンの見出し（# や ## など）で、スライドが分割されます

IMPORTANT NARRATION RULES:
- ナレーション文は **日本語（ひらがな・カタカナ・漢字）で記述してください**
- 英語・アルファベット表記は音声品質が大きく低下します

  EXAMPLES:
  - MCP -> エムシーピー
  - VS Code -> ブイエスコード

ポイント:

箇条書きで明確に
重要な制約は太字で強調
具体例（EXAMPLES）を含める
OK/NG パターンを示す

6. REQUIREMENTS（必須）

目的: 実行に必要な環境やツールを明示

REQUIREMENTS:
- VOICEVOX がインストールされていること
- Marp CLI がインストールされていること
- FFmpeg がインストールされていること

ポイント:

インストールが必要なソフトウェア
必要な権限やライセンス
ネットワーク接続の要否

7. EXAMPLES（必須）

目的: 具体的な使用例を示す

EXAMPLES:
✓ 'このMarkdownを動画にして'
✓ '各スライドにナレーションを付けて動画化して'

ポイント:

自然な会話形式
成功例（✓）と失敗例（✗）を区別
短く、わかりやすく

8. RETURNS / NOTE（情報取得系ツール向け）

目的: 戻り値の内容や補足情報を説明

RETURNS:
- プレゼンテーション動画生成の統合ガイド
- 音声生成サービスのガイド
- スライド生成サービスのガイド

NOTE:
- ナレッジはローカルファイル、Notion、データベースなどから注入されます
- 設定されていない場合はデフォルトメッセージが返されます

いつ使うか:

情報取得・参照系ツール
戻り値が複雑な場合
動的に変わる情報の場合

9. INPUT FORMAT / OUTPUT FORMAT（オプション）

目的: 入出力データの形式を明示

INPUT FORMAT:
- JSON 形式で提供してください
- 必須フィールド: title, content, narrations

OUTPUT FORMAT:
- MP4 形式（H.264 + AAC）
- 解像度: 1920x1080
- フレームレート: 30fps

いつ使うか:

データ形式が複雑な場合
特定のスキーマが必要な場合
複数の形式をサポートする場合

10. LIMITATIONS（オプション）

目的: ツールの制限を明示

LIMITATIONS:
- 同時実行は3つまで
- 最大スライド数: 100枚
- 最大ナレーション長: 1分/スライド
- 対応言語: 日本語のみ

いつ使うか:

技術的な制約がある場合
リソース制限がある場合
同時実行数の制限がある場合

11. PERFORMANCE NOTES（オプション）

目的: パフォーマンスに関する情報を提供

PERFORMANCE NOTES:
- 10スライドの処理に約30秒かかります
- 音声生成が全体の70%の時間を占めます
- 大量のスライドは分割処理を推奨します

いつ使うか:

処理時間が長い場合
リソース消費が大きい場合
パフォーマンスチューニングのヒントがある場合

12. TROUBLESHOOTING（オプション）

目的: よくある問題と解決策を提供

TROUBLESHOOTING:
Q: 音声が生成されない
A: VOICEVOXが起動しているか確認してください

Q: スライドが1つしか生成されない
A: 見出し（# または ##）で区切られているか確認してください

Q: 動画ファイルが開けない
A: FFmpeg が正しくインストールされているか確認してください

いつ使うか:

よくあるエラーパターンがある場合
デバッグ情報が必要な場合
サポート負荷を減らしたい場合

13. SECURITY CONSIDERATIONS（オプション）

目的: セキュリティ上の注意事項を提供

SECURITY CONSIDERATIONS:
- 機密情報を含むナレーションは使用しないでください
- 生成された動画は一時ディレクトリに保存されます
- 処理完了後、手動で削除することを推奨します

いつ使うか:

機密データを扱う場合
外部サービスとの通信がある場合
生成物が永続化される場合

14. ADVANCED OPTIONS / BEST PRACTICES（オプション）

目的: 高度な使い方や推奨プラクティスを提供

BEST PRACTICES:
- 1スライドのナレーションは30秒以内に収める
- 複雑なアニメーションは避ける
- 画像は事前に最適化する

ADVANCED OPTIONS:
- --quality high: 高品質モード（処理時間2倍）
- --cache-voice: 音声をキャッシュして再利用

いつ使うか:

最適な使い方がある場合
高度なカスタマイズが可能な場合
パフォーマンス改善のヒントがある場合

8. RETURNS / NOTE（情報取得系ツール向け）（旧セクション8の内容）

📝 実例: PresentationVideoTool

動画生成ツール（処理実行系）

[McpServerTool]
[Description("""
    Markdown とナレーションからプレゼンテーション動画を生成します。
    
    RECOMMENDED FIRST STEPS:
    - 初めて使用する場合は、まず GetPresentationVideoGenerationGuide() でガイドを確認してください
    - 利用可能なナレーターや設定を確認するには、GetPresentationVideoKnowledge() でナレッジを参照してください
    
    WHEN TO USE:
    - Markdown からスライド＋音声付き動画を作りたい時
    - 社内資料・説明動画・納品用動画を生成したい時
    
    DO NOT USE WHEN:
    - スライドだけ作りたい（use generate_slide_markdown）
    - 音声だけ作りたい（use generate_voice）

    GENERATION RULES:
    - スライドの数とナレーションの数は同じにしてください
    - 見出し1（#）と見出し2（##）のみがスライド区切りとして認識されます

    REQUIREMENTS:
    - VOICEVOX がインストールされていること
    - Marp CLI がインストールされていること
    
    EXAMPLES:
    ✓ 'このMarkdownを動画にして'
    ✓ '各スライドにナレーションを付けて動画化して'
    """)]
public async Task<string> GeneratePresentationVideo(...)

ガイド取得ツール（情報取得系）

[McpServerTool]
[Description("""
    プレゼンテーション動画生成のガイドを取得します。
    
    WHEN TO USE:
    - プレゼンテーション動画の生成方法を知りたい時
    - 利用可能な機能や制約を確認したい時
    
    RETURNS:
    - プレゼンテーション動画生成の統合ガイド
    - 音声生成サービスのガイド
    - スライド生成サービスのガイド
    
    EXAMPLES:
    ✓ 'プレゼンテーション動画の作り方を教えて'
    ✓ '動画生成のガイドを見せて'
    """)]
public string GetPresentationVideoGenerationGuide()

✅ チェックリスト

新しいツールに Description を追加する際のチェックリスト：

🎯 ツールタイプ別のテンプレート

処理実行系ツール

[Description("""
    [概要 - 何を生成/変換/処理するか]
    
    RECOMMENDED FIRST STEPS:
    - [関連する情報取得ツールへの参照]
    
    WHEN TO USE:
    - [ユースケース1]
    - [ユースケース2]
    
    DO NOT USE WHEN:
    - [避けるべきケース]（use [代替ツール]）
    
    [RULES]:
    - [制約1]
    - [制約2]
    
    REQUIREMENTS:
    - [必要なツール/環境]
    
    EXAMPLES:
    ✓ '[使用例1]'
    ✓ '[使用例2]'
    """)]

情報取得系ツール

[Description("""
    [概要 - 何の情報を取得するか]
    
    WHEN TO USE:
    - [取得すべきタイミング1]
    - [取得すべきタイミング2]
    
    RETURNS:
    - [戻り値の内容1]
    - [戻り値の内容2]
    
    NOTE:
    - [補足情報]
    
    EXAMPLES:
    ✓ '[使用例1]'
    ✓ '[使用例2]'
    """)]

🔄 更新と保守

いつ Description を更新すべきか

ツールの機能が変更された時
新しいパラメータが追加された時
制約や要件が変わった時
ユーザーから誤用の報告があった時
関連ツールが追加/削除された時

レビューポイント

LLM がツールの境界を理解できるか
初めてのユーザーが使い方を理解できるか
代替手段が明確か
具体例が十分か

📚 参考資料

実装例

PresentationVideoTool.cs - 複雑なツールの実例
Ateliers.Ai.Mcp.Tools プロジェクト全体

📝 変更履歴

日付	バージョン	変更内容
2025-01-XX	1.0	初版作成

🤝 貢献

このガイドラインへの改善提案は、以下の方法で受け付けています：

GitHub Issue での提案
Pull Request での修正
チーム内レビューでのフィードバック

維持管理: Ateliers Development Team

📋 目的​

なぜ重要か​

🏗️ Description 構造のベストプラクティス​

推奨構造​

📋 Description セクション一覧​

必須セクション​

条件付き必須セクション​

オプションセクション（推奨）​

オプションセクション（高度）​

セクションの優先順位​

優先度1: 必須（全ツール）​

優先度2: 条件付き必須​

優先度3: オプション（推奨）​

優先度4: オプション（高度）​

セクションの組み合わせパターン​

パターン1: シンプルな処理実行系ツール​

パターン2: 複雑な処理実行系ツール（推奨）​

パターン3: 情報取得系ツール​

パターン4: 高度な処理実行系ツール​

📖 各セクションの詳細​

1. 概要（必須）​

2. RECOMMENDED FIRST STEPS（オプション・推奨）​

3. WHEN TO USE（必須）​

4. DO NOT USE WHEN（必須）​

5. ルールセクション（必須）​

6. REQUIREMENTS（必須）​

7. EXAMPLES（必須）​

8. RETURNS / NOTE（情報取得系ツール向け）​

9. INPUT FORMAT / OUTPUT FORMAT（オプション）​

10. LIMITATIONS（オプション）​

11. PERFORMANCE NOTES（オプション）​

12. TROUBLESHOOTING（オプション）​

13. SECURITY CONSIDERATIONS（オプション）​

14. ADVANCED OPTIONS / BEST PRACTICES（オプション）​

8. RETURNS / NOTE（情報取得系ツール向け）（旧セクション8の内容）​

📝 実例: PresentationVideoTool​

動画生成ツール（処理実行系）​

ガイド取得ツール（情報取得系）​

✅ チェックリスト​

🎯 ツールタイプ別のテンプレート​

処理実行系ツール​

情報取得系ツール​

🔄 更新と保守​

いつ Description を更新すべきか​

レビューポイント​

📚 参考資料​

関連ドキュメント​

実装例​

関連ガイドライン​

📝 変更履歴​

🤝 貢献​

📋 目的

なぜ重要か

🏗️ Description 構造のベストプラクティス

推奨構造

📋 Description セクション一覧

必須セクション

条件付き必須セクション

オプションセクション（推奨）

オプションセクション（高度）

セクションの優先順位

優先度1: 必須（全ツール）

優先度2: 条件付き必須

優先度3: オプション（推奨）

優先度4: オプション（高度）

セクションの組み合わせパターン

パターン1: シンプルな処理実行系ツール

パターン2: 複雑な処理実行系ツール（推奨）

パターン3: 情報取得系ツール

パターン4: 高度な処理実行系ツール

📖 各セクションの詳細

1. 概要（必須）

2. RECOMMENDED FIRST STEPS（オプション・推奨）

3. WHEN TO USE（必須）

4. DO NOT USE WHEN（必須）

5. ルールセクション（必須）

6. REQUIREMENTS（必須）

7. EXAMPLES（必須）

8. RETURNS / NOTE（情報取得系ツール向け）

9. INPUT FORMAT / OUTPUT FORMAT（オプション）

10. LIMITATIONS（オプション）

11. PERFORMANCE NOTES（オプション）

12. TROUBLESHOOTING（オプション）

13. SECURITY CONSIDERATIONS（オプション）

14. ADVANCED OPTIONS / BEST PRACTICES（オプション）

8. RETURNS / NOTE（情報取得系ツール向け）（旧セクション8の内容）

📝 実例: PresentationVideoTool

動画生成ツール（処理実行系）

ガイド取得ツール（情報取得系）

✅ チェックリスト

🎯 ツールタイプ別のテンプレート

処理実行系ツール

情報取得系ツール

🔄 更新と保守

いつ Description を更新すべきか

レビューポイント

📚 参考資料

関連ドキュメント

実装例

関連ガイドライン

📝 変更履歴

🤝 貢献