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. 明确必需输入要求

问题：用户不知道只需提供一项输入，还是必须提供所有输入。

修复：对于互斥选项，使用“必需：提供一种输入类型”。

// 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 的 AnnData
• RPM → 每百万条测序读段数
• TSS → 转录起始位点
• TAD → 拓扑关联域
• DRS → 数据仓库服务
• 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”“选项 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. 中（可选优化）：

   • 添加文件大小警告
   • 明确网页表单与 API 的区别
   • 说明文件类型的差异

预期影响：用户错误减少 50-75%，首次成功使用所需时间缩短 50-67%。