token-optimization

トークン最適化のベストプラクティス

深い知識：包括的なドキュメントを参照するには、technology: token-optimization を指定して mcp__documentation__fetch_docs を使用してください。

MCP サーバーや外部ツールとのやり取りで、トークン消費を最小限に抑えるためのガイドラインです。

このスキルを使用しないケース

このスキルは、API／ツール呼び出しの最適化に重点を置いています。次の用途には使用しないでください。

• 実行時のパフォーマンス - 速度の最適化には performance スキルを使用します
• コードの圧縮 - ビルドツール（Vite、Webpack など）を使用します
• データベースクエリの最適化 - データベース固有のスキルを使用します
• アルゴリズムの効率化 - コンピューターサイエンスの基礎知識を使用します
• プロンプトエンジニアリング - これはツールの使い方に関するものであり、プロンプトの設計に関するものではありません

一般原則

原則	説明
遅延読み込み	情報は本当に必要な場合にのみ読み込みます
最小限の出力	必要なデータのみをリクエストし、limit や compact パラメーターを使用します
段階的な詳細化	概要や要約から始め、必要な場合にのみ詳細を確認します
キャッシュ優先	外部呼び出しの前に、情報がすでにコンテキストにあるか確認します

アンチパターン

アンチパターン	問題点	トークン効率のよい解決策
**SELECT ***	不要な列も返されます	必要な列を正確に指定します
LIMIT 句なし	データセット全体が返されます	常に LIMIT を追加します（例：100）
スキーマ全体のリクエスト	膨大な仕様が返されます	compact=true または format="summary" を使用します
ドキュメントの再帰的な取得	ドキュメントツリー全体を取得します	特定のクエリを指定して search_docs を使用します
ログ全体の取得	数千行が返されます	上限を指定して tail_logs または find_errors を使用します
ドキュメントのコピー＆ペースト	内容が重複します	そのまま引用せず、要約して参照します
ページネーションなし	すべての結果が一度に返されます	大規模なデータセットには offset／limit を使用します
API スキーマ全体の調査	数 MB の仕様になります	まずエンドポイント一覧を取得し、必要に応じて詳細を確認します

すぐにできるトラブルシューティング

問題	確認事項	解決策
MCP のレスポンスが大きい	出力サイズが 2000 トークンを超えている	limit パラメーターを追加し、コンパクト形式を使用します
API 呼び出しの繰り返し	同じツールを複数回呼び出している	会話のコンテキストに結果をキャッシュします
コンテキストの蓄積が遅い	ツール呼び出しが多すぎる	関連するクエリをまとめ、より具体的なツールを使用します
不要なドキュメントの取得	情報がすでにわかっている	まずスキルファイルを確認し、最後の手段としてドキュメントを取得します
全件テーブルスキャンの結果	データベースクエリが返す情報が多すぎる	WHERE 句と LIMIT を追加します
詳細すぎるエラーログ	スタックトレース全体が繰り返されている	エラーを要約し、行番号を参照します

MCP サーバーのパターン

database-query

-- BAD: Query without limits
SELECT * FROM users

-- GOOD: Query with filters and limits
SELECT id, name, email FROM users WHERE active = true LIMIT 100

ツールの使い方：

• execute_query：必ず limit パラメーターを使用します（デフォルト：1000）
• get_schema(compact=true)：DB 構造の概要を確認します
• describe_table：探索的なクエリを実行する前に使用します
• explain_query：大規模なテーブルに対して複雑なクエリを実行する前に使用します

api-explorer

-- BAD: Full schema
get_api_schema(format="full")

-- GOOD: Summary only for overview
get_api_schema(format="summary")

-- GOOD: Path list with limit
list_api_paths(limit=50)

-- GOOD: Single endpoint details
get_api_endpoint_details(path="/users/{id}", method="GET")

ツールの使い方：

• get_api_schema(format="summary")：API の概要を確認します
• list_api_paths(limit=50)：エンドポイント一覧を取得します
• get_api_models(compact=true)：スキーマ全体を取得せずにモデル一覧を取得します
• search_api(limit=10)：対象を絞った検索を行います

documentation

-- BAD: Entire document
fetch_docs(topic="react")

-- GOOD: Targeted search
search_docs(query="useEffect cleanup", maxResults=3)

ツールの使い方：

• search_docs(maxResults=3)：特定の情報を検索します
• fetch_docs：非常に具体的なトピックに限って使用します
• ドキュメントを取得する前に、必ずスキルファイルを確認します

log-analyzer

-- BAD: All logs
parse_logs(file="/var/log/app.log")

-- GOOD: Recent errors only
find_errors(file="/var/log/app.log", limit=50)

-- GOOD: Tail for live debugging
tail_logs(file="/var/log/app.log", lines=50)

ツールの使い方：

• tail_logs(lines=50)：最近のログを確認します
• find_errors(limit=50)：エラーをデバッグします
• parse_logs(limit=200)：詳細な分析が必要な場合にのみ使用します

security-scanner

ツールの使い方：

• scan_dependencies：scan_all より優先して使用します
• scan_secrets：全件スキャンより高速です
• scan_all：完全な監査を行う場合にのみ使用します

code-quality

ツールの使用方法：

• analyze_complexity(path="src/specific/file.ts")：特定のファイルを対象にします
• find_duplicates(minLines=10)：重要な重複のみを絞り込みます
• code_metrics：概要を把握するための簡潔な出力です

MCP 呼び出し前のチェックリスト

MCP ツールを呼び出す前に、次の点を確認してください。

• この情報はすでにコンテキストにありますか？
• 汎用的なツールではなく、より具体的なツールを使用できますか？
• 適切な limit を設定しましたか？
• 利用できる場合、compact=true を使用しましたか？
• 予想される出力は妥当な範囲ですか（2000 トークン未満）？

出力形式の基準

コード分析の場合

• カテゴリーごとに最大 5 件の問題
• スニペットは最大 10 行
• リストには表を使用

データベースクエリの場合

• 直接出力する行数は最大 20 行
• 結果が 20 行を超える場合：「N 行が見つかりました。先頭 20 行：...」
• コンパクトな表形式

ドキュメントの場合

• 関連する箇所のみ引用（最大 500 文字）
• 内容を複製する代わりに、完全なドキュメントへのリンクを記載
• 原文をそのまま引用する代わりに要約

効率的な応答の例

データベースクエリ — 簡潔な出力

Found 1523 rows. First 20:
| id | name | status |
|----|------|--------|
| 1  | ...  | active |
...
Use offset=20 for next page.

API の調査 — 段階的な詳細表示

API has 45 endpoints. Summary by tag:
- users: 8 endpoints
- auth: 5 endpoints
- products: 12 endpoints
...
Use get_api_endpoint_details for specifics.

ログ分析 — 要点を絞った出力

Found 234 errors in last hour. Top 5 by frequency:
1. ConnectionTimeout: 89 occurrences
2. ValidationError: 45 occurrences
...
Use tail_logs or parse_logs with filters for details.

リファレンスドキュメント

詳細なナレッジ：高度な最適化手法については、technology: token-optimization を指定して mcp__documentation__fetch_docs を使用してください。