devtu-optimize-descriptions

Files (1)

• SKILL.md

SKILL.md (first lines)

# ToolUniverse Tool Description Optimization

Optimize tool descriptions in ToolUniverse JSON configuration files to ensure they are clear, complete, and user-friendly.

## When to Apply This Skill

Use when:
- Reviewing newly created tool descriptions
- User asks "are these tools easy to understand?"
- Improving existing tool documentation
- Adding new tools to ToolUniverse
- User mentions tool usability, clarity, or documentation

## Quick Optimization Checklist

```markdown
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
```

## Critical Improvements (Fix Immediately)

### 1. Clarify Required Input Requirements

**Problem**: Users don't know if they need ONE input or ALL inputs.

**Fix**: Use "**Required: Provide ONE input type**" for mutually exclusive options.

```json
// 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..."
```

Number the options and use bold for "Required".

### 2. Add Prerequisites to First Tool

**Problem**: Users don't know what to install/configure before use.

**Fix**: Add prerequisites note to first tool in each family.

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

Include:
- Package installation command
- API key requirements
- Account creation instructions

### 3. Expand Critical Abbreviations

**Problem**: New users don't understand technical terms.

**Fix**: Expand on first use with format: "Abbreviation (Full Name)".

Common abbreviations to expand:
- H5AD → HDF5-based AnnData
- RPM → Reads Per Million
- TSS → Transcription Start Site
- TAD → Topologically Associating Domain
- DRS → Data Repository Service
- API names (MACS2, IUPAC, etc.)

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

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

## High-Priority Improvements

### 4. Enhance Filter Parameter Descriptions

**Problem**: Users don't know what fields are available or what syntax to use.

**Fix**: List operators, common fields, and provide multiple examples.

```json
"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\"]'."
}
```

Include:
- Syntax format
- Available operators
- List of 5-10 common fields
- 2-3 diverse examples

### 5. Improve Parameter Guidance

**Problem**: Users don't know which value to choose or what trade-offs exist.

**Fix**: Explain what each value means and provide recommendations.

```json
// 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."
```

For each parameter option, explain:
- What it means practically

From Zaoqu-Liu/ScienceClaw, MIT.

More from Zaoqu-Liu/ScienceClaw