devtu-optimize-descriptions

ToolUniverse ツール説明の最適化

ToolUniverse の JSON 設定ファイルにあるツールの説明を最適化し、明確で完全、かつ使いやすいものにします。

このスキルを使う場面

次の場合に使用します：

• 新しく作成されたツールの説明をレビューするとき
• ユーザーから「これらのツールは理解しやすいですか？」と聞かれたとき
• 既存のツールのドキュメントを改善するとき
• ToolUniverse に新しいツールを追加するとき
• ユーザーがツールの使いやすさ、明確さ、またはドキュメントについて言及したとき

最適化のクイックチェックリスト

Tool Description Review:
- [ ] Prerequisites stated (packages, API keys, accounts)
- [ ] Critical abbreviations expanded on first use
- [ ] Required vs optional parameters clear
- [ ] Mutually exclusive options numbered/labeled
- [ ] Parameter guidance includes trade-offs
- [ ] Filter syntax shows available fields
- [ ] File size warnings where relevant
- [ ] Examples show realistic usage

重要な改善点（すぐに修正）

1. 必須入力の要件を明確にする

問題：ユーザーは入力を1つだけ指定すればよいのか、すべて指定する必要があるのか分かりません。

修正方法：相互に排他的な選択肢には「必須：入力タイプを1つ指定」を使用します。

// Before
"description": "Process BED regions, motifs, or gene lists..."

// After
"description": "Process genomic data. **Required: Provide ONE input type** - (1) BED regions, (2) DNA motif, or (3) gene list. Analyzes..."

選択肢に番号を付け、「必須」は太字にします。

2. 最初のツールに前提条件を追加する

問題：ユーザーは、使用前に何をインストールまたは設定する必要があるのか分かりません。

修正方法：各ファミリーの最初のツールに前提条件の注記を追加します。

"description": "Query single-cell data. Prerequisites: Requires 'package-name' (install: pip install tooluniverse[extra]). Returns..."

以下を含めます：

• パッケージのインストールコマンド
• API キーの要件
• アカウント作成手順

3. 重要な略語を展開する

問題：新しいユーザーには専門用語が分かりません。

修正方法：初出時に「略語（正式名称）」の形式で展開します。

展開する一般的な略語：

• H5AD → HDF5-based AnnData
• RPM → Reads Per Million
• TSS → Transcription Start Site
• TAD → Topologically Associating Domain
• DRS → Data Repository Service
• API 名（MACS2、IUPAC など）

// Before
"description": "Download H5AD files..."

// After  
"description": "Download H5AD (HDF5-based AnnData) files..."

優先度の高い改善点

4. フィルターパラメーターの説明を強化する

問題：ユーザーは、利用可能なフィールドや使用する構文が分かりません。

修正方法：演算子や一般的なフィールドを列挙し、複数の例を示します。

"parameter_name": {
  "type": "string",
  "description": "Filter using SQL-like syntax. Format: 'field == \"value\"'. Operators: ==, !=, in, <, >, <=, >=. Combine with 'and'/'or'. Common fields: tissue, cell_type, disease, assay, sex, ethnicity. Examples: 'tissue == \"lung\"', 'disease == \"COVID-19\" and tissue == \"lung\"', 'cell_type in [\"T cell\", \"B cell\"]'."
}

以下を含めます：

• 構文の形式
• 利用可能な演算子
• よく使われるフィールドを5～10個
• 多様な例を2～3個

5. パラメーターのガイダンスを改善する

問題：ユーザーは、どの値を選ぶべきか、またどのようなトレードオフがあるのか分かりません。

修正方法：各値の意味を説明し、推奨事項を示します。

// Before
"threshold": "Q-value threshold (05=1e-5, 10=1e-10, 20=1e-20)"

// After
"threshold": "Peak calling stringency. '05'=1e-5 (permissive, more peaks, broad features), '10'=1e-10 (moderate, balanced), '20'=1e-20 (strict, high confidence, narrow peaks). Default '05' suitable for most analyses. Higher values = fewer but more confident peaks."

各パラメーターの選択肢について、以下を説明します：

• 実際には何を意味するか
• どのような場合に使うか
• どのようなトレードオフがあるか
• 推奨されるデフォルト値

6. 相互に排他的な選択肢に番号を付ける

問題：1つしか指定できないのに、ユーザーが複数の選択肢を指定します。

修正方法：選択肢に「選択肢 1」、「選択肢 2」などのラベルを付けます。

"bed_data": {
  "description": "**Option 1**: BED format regions (tab-separated: chr, start, end). Example: 'chr1\\t1000\\t2000'."
},
"motif": {
  "description": "**Option 2**: DNA sequence motif in IUPAC notation. Use: A/T/G/C, W=A|T, S=G|C. Example: 'CANNTG'."
},
"gene_list": {
  "description": "**Option 3**: Gene symbols as array. Example: ['TP53', 'MDM2']."
}

優先度が中程度の改善点

7. ファイルサイズに関する警告を追加する

大きなファイルをダウンロードまたは返すツールの場合：

"description": "Download contact matrices. Note: Files can be large (GBs), check file_size in metadata before downloading. Returns..."

8. ウェブフォームと API の結果を明確にする

ツールが直接結果ではなく送信 URL を返す場合：

"description": "Perform enrichment analysis. Note: Returns submission URL (web form-based analysis). Analyzes..."

9. ファイル形式の違いを説明する

複数の形式を選べるツールの場合：

"file_type": "File format. Common types: 'cooler' (multi-resolution contact matrices), 'pairs' (aligned read pairs), 'hic' (Juicer format), 'mcool' (multi-resolution cooler)."

説明の構成テンプレート

{
  "name": "Tool_operation_name",
  "type": "ToolClassName",
  "description": "[Action verb] to [purpose]. [Prerequisites if first tool]. [Key data/features]. [Required inputs if mutually exclusive]. [Note about limitations/requirements]. Use for: [use case 1], [use case 2], [use case 3].",
  "parameter": {
    "properties": {
      "param_name": {
        "type": "string",
        "description": "[What it does]. [Format/syntax if applicable]. [Options with trade-offs]. [Examples]. [Recommendation if applicable]."
      }
    }
  }
}

説明の品質チェックリスト

明確さの確認

• 最初の文で目的が明確になっている
• 専門用語が展開されている
• 前提条件が最初に記載されている
• 現実的な使い方を例で示している
• 「用途：」セクションに具体的なユースケースが3～5個記載されている

完全性の確認

• 必須入力が明確に示されている
• パラメーターの選択肢が説明されている
• 制限事項（ファイルサイズ、ウェブフォームなど）が記載されている
• フィルターで利用可能なフィールドが列挙されている
• デフォルト値が推奨されている

使いやすさの確認

• 新しいユーザーが外部ドキュメントを参照せずに理解できる
• ユーザーが何を入力すればよいか分かる
• ユーザーが十分な情報に基づいてパラメーターを選択できる
• 相互に排他的な選択肢を明示するなど、エラーを防ぐ工夫がある

説明の品質をテストする

説明の品質を確認するには、次の点を確認します：

1. 新しいユーザーがツールの機能を理解できますか？

   • 説明だけを読む（ドキュメントは参照しない）
   • 30秒以内に理解できること

2. ユーザーは最初の試行で正しい入力を指定できますか？

   • 必須入力が明確である
   • 形式や構文が明確である
   • 相互に排他的な選択肢が明示されている

3. ユーザーは適切なパラメーターを選べますか？

   • トレードオフが説明されている
   • 推奨事項が示されている
   • デフォルト値の根拠が説明されている

4. 前提条件は明確ですか？

   • インストール手順
   • API キーやアカウント
   • ファイルサイズに関する警告

ツールの種類ごとの一般的なパターン

API クエリツール

"description": "Query [data type] from [source]. [Prerequisites]. Filter by [criteria]. Returns [output]. [Data scale]. Use for: [discovery], [analysis], [specific research tasks]."

主な要素：

• クエリ対象
• フィルター方法
• 取得できる情報
• データ規模
• 前提条件

データダウンロードツール

"description": "Download [file types] from [source]. [Format details]. [File size warning]. [Authentication requirement]. Use for: [offline analysis], [custom processing], [integration]."

主な要素：

• 利用可能なファイル形式
• サイズに関する注意
• 認証要件
• ファイルの内容

エンリッチメント／分析ツール

"description": "Analyze [input type] to find [results]. **Required: Provide ONE input type** - (1) [option], (2) [option], (3) [option]. Compares against [database/background]. [Result format]. Use for: [identifying], [discovering], [predicting]."

主な要素：

• 入力要件を明確にする
• オプションに番号を付ける
• 比較対象を示す
• 得られる知見を示す

検証コマンド

説明を更新した後、JSON 構文を検証します：

# Validate all tool JSONs
python3 -m json.tool src/tooluniverse/data/your_tools.json > /dev/null && echo "✓ Valid"

# Check all tools in category
for f in src/tooluniverse/data/*_tools.json; do
  python3 -m json.tool "$f" > /dev/null && echo "✓ $f valid" || echo "✗ $f invalid"
done

例：変更前と変更後

変更前（不明瞭）：

{
  "name": "Tool_enrichment",
  "description": "Perform enrichment with tool to find factors.",
  "parameter": {
    "properties": {
      "bed": {"description": "BED data"},
      "motif": {"description": "Motif"},
      "genes": {"description": "Genes"},
      "threshold": {"description": "Threshold value"}
    }
  }
}

変更後（明確）：

{
  "name": "Tool_enrichment_analysis",
  "description": "Identify transcription factors enriched in your data. **Required: Provide ONE input type** - (1) BED genomic regions, (2) DNA sequence motif (IUPAC notation), or (3) gene symbol list. Compares against 400,000+ ChIP-seq experiments. Returns ranked proteins with enrichment scores. Note: Returns submission URL (web-based analysis). Use for: identifying regulators of regions, finding proteins bound to motifs, discovering transcription factors regulating genes.",
  "parameter": {
    "properties": {
      "bed_data": {
        "description": "**Option 1**: BED format regions (tab-separated: chr, start, end). For finding proteins bound to genomic regions. Example: 'chr1\\t1000\\t2000'."
      },
      "motif": {
        "description": "**Option 2**: DNA motif in IUPAC notation (A/T/G/C, W=A|T, S=G|C, M=A|C, K=G|T, R=A|G, Y=C|T). Example: 'CANNTG' (E-box)."
      },
      "gene_list": {
        "description": "**Option 3**: Gene symbols as array or single gene. Example: ['TP53', 'MDM2', 'CDKN1A']."
      },
      "threshold": {
        "description": "Peak stringency. '05'=1e-5 (permissive, more peaks), '10'=1e-10 (moderate), '20'=1e-20 (strict, high confidence). Default '05' suitable for most analyses."
      }
    }
  }
}

まとめ

最適化の優先順位：

1. 重大（直ちに修正）：

   • 必須入力を明確にする
   • 前提条件を追加する
   • 略語を展開する

2. 高（早めに修正）：

   • フィルターの説明を強化する
   • パラメーターの指針を改善する
   • 相互排他的なオプションに番号を付ける

3. 中（できれば対応）：

   • ファイルサイズに関する注意を追加する
   • Web フォームと API の違いを明確にする
   • ファイル形式の違いを説明する

期待される効果：ユーザーのエラーを50～75％削減し、初回の利用成功までの時間を50～67％短縮します。