Devtu Optimize Descriptions

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

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.

// 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.

"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.)

// 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.

"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.

// 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
• When to use it
• Trade-offs involved
• Recommended default

6. Number Mutually Exclusive Options

Problem: Users provide multiple options when only one is allowed.

Fix: Label options as "Option 1", "Option 2", etc.

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

Medium-Priority Improvements

7. Add File Size Warnings

For tools that download or return large files:

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

8. Clarify Web Form vs API Results

When tool returns submission URL instead of direct results:

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

9. Explain File Type Differences

For tools with multiple format options:

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

Description Structure Template

{
  "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]."
      }
    }
  }
}

Description Quality Checklist

Clarity Checks

• [ ] Purpose clear in first sentence
• [ ] Technical terms expanded
• [ ] Prerequisites stated upfront
• [ ] Examples show realistic usage
• [ ] "Use for:" section lists 3-5 concrete use cases

Completeness Checks

• [ ] Required inputs clearly marked
• [ ] Parameter choices explained
• [ ] Limitations noted (file size, web form, etc.)
• [ ] Available fields listed for filters
• [ ] Default values recommended

Usability Checks

• [ ] New users can understand without external docs
• [ ] Users know what to provide
• [ ] Users can make informed parameter choices
• [ ] Error prevention (mutually exclusive options labeled)

Testing Description Quality

To verify description quality, ask:

1. Can a new user understand what the tool does?

• Read only the description (no docs)
• Should be clear within 30 seconds

2. Can a user provide correct inputs on first try?

• Required inputs obvious
• Format/syntax clear
• Mutually exclusive options labeled

3. Can a user choose appropriate parameters?

• Trade-offs explained
• Recommendations provided
• Defaults justified

4. Are prerequisites obvious?

• Installation instructions
• API keys/accounts
• File size warnings

Common Patterns by Tool Type

API Query Tools

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

Key elements:

• What you're querying
• How to filter
• What you get back
• Scale of data
• Prerequisites

Data Download Tools

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

Key elements:

• File formats available
• Size warning
• Authentication needs
• What's in the files

Enrichment/Analysis Tools

"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]."

Key elements:

• Input requirements clear
• Options numbered
• What gets compared
• What you learn

Validation Commands

After updating descriptions, validate JSON syntax:

# 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

Example: Before and After

Before (Unclear):

{
  "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"}
    }
  }
}

After (Clear):

{
  "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."
      }
    }
  }
}

Summary

Priority order for optimization:

1. Critical (fix immediately):

• Clarify required inputs
• Add prerequisites
• Expand abbreviations

2. High (fix soon):

• Enhance filter descriptions
• Improve parameter guidance
• Number mutually exclusive options

3. Medium (nice to have):

• Add file size warnings
• Clarify web form vs API
• Explain file type differences

Expected impact: 50-75% reduction in user errors, 50-67% faster time to first successful use.

Tool Description Quick Reference Checklist

Use this checklist when reviewing or creating tool descriptions.

Per-Tool Review Checklist

Copy and check off for each tool:

Tool: ___________________________

CRITICAL FIXES:
[ ] Required inputs clearly marked ("**Required: Provide ONE input type**")
[ ] Mutually exclusive options numbered (**Option 1**, **Option 2**)
[ ] Prerequisites stated if first tool in family
[ ] Critical abbreviations expanded on first use

HIGH PRIORITY:
[ ] Filter parameters list available fields
[ ] Filter parameters show operators (==, !=, in, etc.)
[ ] Filter parameters include 2-3 examples
[ ] Parameters with choices explain trade-offs
[ ] Default values recommended with reasoning

MEDIUM PRIORITY:
[ ] File size warnings where relevant ("Files can be large (GBs)")
[ ] Web form vs API results clarified
[ ] File types explained ("cooler (multi-resolution matrices)")
[ ] "Use for:" section with 3-5 concrete use cases

VALIDATION:
[ ] JSON syntax validated (python3 -m json.tool)
[ ] Description 30-60 words (not too short, not too long)
[ ] No time-sensitive information
[ ] Consistent terminology throughout

Common Abbreviations to Expand

First use only - expand as "Abbreviation (Full Name)":

Bioinformatics:

• [ ] H5AD → HDF5-based AnnData
• [ ] RPM → Reads Per Million
• [ ] TPM → Transcripts Per Million
• [ ] FPKM → Fragments Per Kilobase Million
• [ ] TSS → Transcription Start Site
• [ ] TAD → Topologically Associating Domain
• [ ] QTL → Quantitative Trait Locus
• [ ] GWAS → Genome-Wide Association Study

Technical:

• [ ] API → Application Programming Interface
• [ ] REST → Representational State Transfer
• [ ] DRS → Data Repository Service
• [ ] URI → Uniform Resource Identifier
• [ ] UUID → Universally Unique Identifier

Methods:

• [ ] MACS2 → Model-based Analysis of ChIP-Seq
• [ ] IUPAC → International Union of Pure and Applied Chemistry (nucleotide codes)
• [ ] QC → Quality Control

Parameter Description Templates

Filter Parameters

"Filter using SQL-like syntax. Format: 'field == \"value\"'. 
Operators: ==, !=, in, <, >, <=, >=. Combine with 'and'/'or'. 
Common fields: [list 5-10 fields]. 
Examples: [3 diverse examples]."

Threshold/Stringency Parameters

"[Purpose]. Options: 'X'=[value] ([outcome], [when to use]), 
'Y'=[value] ([outcome], [when to use]), 'Z'=[value] ([outcome], [when to use]). 
Default 'X' suitable for most analyses. [Trade-off principle]."

Version/Selection Parameters

"[Purpose]. 'option1' (recommended, [characteristic]), 
'option2' ([characteristic], [caveat]), or [format] ([use case]). 
Default 'option1' is best for [scenario]."

Input Data Parameters

"**Option N**: [Format description]. [When to use]. 
Example: [concrete example with actual values]."

Description Structure Formula

[Action verb] to [purpose]. [Prerequisites if first tool]. 
[Key data/scale]. [Required inputs if mutually exclusive]. 
[Note about limitations]. Use for: [use case 1], [use case 2], 
[use case 3].

Quick Fixes Reference

Validation Commands

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

# Validate all tools
for f in src/tooluniverse/data/*_tools.json; do
  python3 -m json.tool "$f" > /dev/null && echo "✓ $(basename $f) valid"
done

# Count tools per file
grep -c '"name":' src/tooluniverse/data/*_tools.json

# Check for common issues
grep -n "TODO\|FIXME\|XXX" src/tooluniverse/data/*_tools.json

Quality Thresholds

Minimum Acceptable

• [ ] Purpose stated
• [ ] Parameters described
• [ ] JSON valid

Good

• [ ] Prerequisites mentioned
• [ ] Examples provided
• [ ] Use cases listed
• [ ] Abbreviations expanded

Excellent

• [ ] All critical items checked
• [ ] Filter fields listed
• [ ] Parameter trade-offs explained
• [ ] Mutually exclusive options numbered
• [ ] File size warnings where needed
• [ ] 30-second test passes
• [ ] First-try test passes

Before/After Metrics

Track improvements:

Before:
- Description length: ___ words
- Abbreviations unexpanded: ___
- Parameters without guidance: ___
- Missing prerequisites: Yes/No
- Mutually exclusive clarity: Yes/No

After:
- Description length: ___ words
- Abbreviations expanded: ___
- Parameters with guidance: ___
- Prerequisites stated: Yes/No
- Mutually exclusive clarity: Yes/No

Expected impact:
- Error rate reduction: ~___% 
- Time to first success: ~___% faster

Tool Description Optimization - Detailed Examples

This file contains comprehensive examples of description improvements organized by issue type.

Example Set 1: Clarifying Required Inputs

ChIP-Atlas Enrichment Analysis

Original (Unclear):

{
  "description": "Perform enrichment analysis with ChIP-Atlas to find transcription factors and histone modifications bound to genomic regions, sequence motifs, or gene lists.",
  "parameter": {
    "properties": {
      "bed_data": {"description": "BED format genomic regions"},
      "motif": {"description": "DNA sequence motif"},
      "gene_list": {"description": "Gene symbols"}
    }
  }
}

Problem: Users don't know if they should provide all three or just one.

Improved:

{
  "description": "Perform enrichment analysis to identify transcription factors and histone modifications 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 your input against 433,000+ ChIP-seq/ATAC-seq/Bisulfite-seq experiments to identify significant enrichment. Returns ranked list of proteins bound to your regions/motif or regulating your genes.",
  "parameter": {
    "properties": {
      "bed_data": {
        "description": "**Option 1**: BED format genomic regions (tab-separated: chr, start, end). For finding proteins bound to specific genomic regions. Example: 'chr1\\t1000\\t2000\\nchr2\\t3000\\t4000'."
      },
      "motif": {
        "description": "**Option 2**: DNA sequence motif in IUPAC notation. Use: A/T/G/C (bases), W=A|T, S=G|C, M=A|C, K=G|T, R=A|G, Y=C|T. Example: 'CANNTG' (E-box motif)."
      },
      "gene_list": {
        "description": "**Option 3**: Gene symbols (HGNC for human, MGI for mouse). Provide as array or single gene. Example: ['TP53', 'MDM2', 'CDKN1A']."
      }
    }
  }
}

Key Changes:

• Added "Required: Provide ONE input type" in bold
• Numbered options (1), (2), (3)
• Used "Option X" labels in parameters
• Added format details and examples to each option

---

Example Set 2: Adding Prerequisites

CELLxGENE Census Tools

Original (Missing Prerequisites):

{
  "name": "CELLxGENE_get_census_versions",
  "description": "Get list of available CELLxGENE Census versions with release dates and descriptions. The Census contains single-cell RNA-seq data from 50M+ cells."
}

Improved:

{
  "name": "CELLxGENE_get_census_versions",
  "description": "Get list of available CELLxGENE Census versions with release dates and descriptions. The Census contains single-cell RNA-seq data from 50M+ cells (human, mouse, non-human primates). Prerequisites: Requires 'cellxgene-census' package (install: pip install tooluniverse[singlecell]). Use for: checking available data versions, selecting stable vs latest builds."
}

4DN Data Portal Tools

Original:

{
  "name": "FourDN_get_download_url",
  "description": "Get download URL and DRS API endpoint for 4DN files. All downloads require authentication."
}

Improved:

{
  "name": "FourDN_get_download_url",
  "description": "Get download URL and DRS (Data Repository Service) API endpoint for 4DN files. Prerequisites: Requires free 4DN account - create at data.4dnucleome.org, then generate access key in your profile settings. Returns download URL and instructions for command-line access with curl."
}

---

Example Set 3: Expanding Abbreviations

Various Tools

Original Examples:

"Download H5AD files from datasets"
"BigWig contains coverage scores in RPM"
"Distance from TSS for gene analysis"
"Access TAD boundaries and loop calls"
"Supports GA4GH DRS standard"

Improved Examples:

"Download H5AD (HDF5-based AnnData) files from datasets"
"BigWig contains coverage scores in RPM (Reads Per Million)"
"Distance from Transcription Start Site (TSS) for gene analysis"
"Access TAD (Topologically Associating Domain) boundaries and loop calls"
"Supports GA4GH DRS (Data Repository Service) standard"

Pattern: "Abbreviation (Full Name)" on first use

---

Example Set 4: Enhanced Filter Descriptions

CELLxGENE Filters

Original (Minimal):

{
  "obs_value_filter": {
    "description": "SOMA value filter string (e.g., 'tissue == \"lung\" and cell_type == \"T cell\"')"
  }
}

Improved (Comprehensive):

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

Key Additions:

• Syntax description ("SQL-like")
• Format pattern
• List of operators
• 8-10 common field names
• 3 diverse examples

Gene Filters

Original:

{
  "var_value_filter": {
    "description": "SOMA value filter string (e.g., 'feature_name == \"CD4\"')"
  }
}

Improved:

{
  "var_value_filter": {
    "description": "Filter genes using SQL-like syntax. Format: 'field == \"value\"'. Common fields: feature_name (gene symbol), feature_id (Ensembl ID), feature_biotype. Examples: 'feature_name == \"TP53\"', 'feature_name in [\"CD4\", \"CD8A\"]', 'feature_biotype == \"protein_coding\"'."
  }
}

---

Example Set 5: Parameter Guidance with Trade-offs

Threshold Parameters

Original (Unclear):

{
  "threshold": {
    "description": "MACS2 Q-value threshold (05=1e-5, 10=1e-10, 20=1e-20)",
    "enum": ["05", "10", "20"],
    "default": "05"
  }
}

Improved (Actionable):

{
  "threshold": {
    "description": "Peak calling stringency (MACS2 Q-value). Options: '05'=1e-5 (permissive, more peaks, broader features), '10'=1e-10 (moderate, balanced), '20'=1e-20 (strict, high confidence only, narrow peaks). Default '05' suitable for most analyses. Higher values = fewer but more confident peaks.",
    "enum": ["05", "10", "20"],
    "default": "05"
  }
}

Elements Added:

• What each value means (permissive, moderate, strict)
• Practical outcome (more/fewer peaks)
• When to use each (broad vs narrow features)
• Clear recommendation (default suitable for most)
• General principle (higher = fewer but confident)

Version Selection

Original:

{
  "census_version": {
    "description": "Census version ('stable', 'latest', or 'YYYY-MM-DD')",
    "default": "stable"
  }
}

Improved:

{
  "census_version": {
    "description": "Census version to query. 'stable' (recommended, Long-Term Support release), 'latest' (newest data, may change), or specific date 'YYYY-MM-DD' (for reproducibility). Default 'stable' is best for production analyses.",
    "default": "stable"
  }
}

Distance/Range Parameters

Original:

{
  "distance": {
    "description": "Distance from TSS for gene list analysis (bp)",
    "default": "5000"
  }
}

Improved:

{
  "distance": {
    "description": "Distance from Transcription Start Site (TSS) in base pairs for gene-TF association. Defines promoter region. Default 5000 (±5kb, captures typical promoters). Use 1000-2000 for narrow promoters, 10000+ for enhancer regions.",
    "default": "5000"
  }
}

---

Example Set 6: File Type Explanations

4DN File Types

Original (Cryptic):

{
  "file_type": {
    "description": "Filter by file type (e.g., 'contact list', 'pairs', 'cooler')"
  }
}

Improved (Explanatory):

{
  "file_type": {
    "description": "Filter by file type. Common types: 'contact list' (processed contact matrices), 'pairs' (aligned read pairs), 'cooler' (multi-resolution contact matrices), 'mcool' (multi-resolution cooler), 'hic' (Juicer format)."
  }
}

Pattern: "type_name (what it contains/represents)"

---

Example Set 7: Complete Tool Description Makeover

Before: Minimal Description

{
  "name": "API_query_data",
  "type": "APITool",
  "description": "Query data from API. Returns results.",
  "parameter": {
    "properties": {
      "query": {"description": "Query string"},
      "limit": {"description": "Result limit"},
      "version": {"description": "API version"}
    }
  }
}

After: Comprehensive Description

{
  "name": "API_query_cell_data",
  "type": "SingleCellAPITool",
  "description": "Query single-cell RNA-seq data from Census database containing 50M+ cells (human, mouse, non-human primate). Prerequisites: Requires 'census-api' package (install: pip install tooluniverse[singlecell]). Filter by tissue, cell type, disease, or metadata fields. Returns cell metadata and gene expression summaries. Note: Large queries require 8GB+ RAM. Use for: finding cells matching criteria, exploring cell type distributions, quality filtering, cohort selection for analysis.",
  "parameter": {
    "properties": {
      "query": {
        "description": "Filter cells using SQL-like syntax. Format: 'field == \"value\"'. Operators: ==, !=, in, <, >, <=, >=. Common fields: tissue, cell_type, disease, assay, sex. Examples: 'tissue == \"lung\"', 'disease == \"COVID-19\" and tissue == \"lung\"'."
      },
      "limit": {
        "description": "Maximum cells to return. Default 1000. Use 100-1000 for exploration, 10000+ for analysis. Note: Higher limits require more memory.",
        "default": 1000
      },
      "version": {
        "description": "Census version. 'stable' (recommended, Long-Term Support), 'latest' (newest data, may change), or date 'YYYY-MM-DD' (reproducibility). Default 'stable' best for production.",
        "default": "stable"
      }
    }
  }
}

Improvements Made: 1. ✅ Specific tool name (not generic "API") 2. ✅ Data scale mentioned (50M+ cells) 3. ✅ Prerequisites stated upfront 4. ✅ Filter syntax explained 5. ✅ Common fields listed 6. ✅ Multiple examples provided 7. ✅ Memory requirements noted 8. ✅ "Use for:" with 4 specific cases 9. ✅ Parameter guidance with trade-offs 10. ✅ Recommendations for each parameter 11. ✅ Practical ranges explained

---

Common Description Anti-Patterns

Anti-Pattern 1: Vague Purpose

Bad:

"Process data from database"

Good:

"Query single-cell RNA-seq metadata from Census containing 50M+ cells. Filter by tissue, cell type, disease. Returns cell annotations and QC metrics."

Anti-Pattern 2: Missing Context

Bad:

"threshold": "Threshold value (05, 10, 20)"

Good:

"threshold": "Peak stringency. '05'=permissive (more peaks), '10'=moderate, '20'=strict (high confidence). Default '05' for most analyses."

Anti-Pattern 3: Assuming Knowledge

Bad:

"Filter using SOMA syntax"

Good:

"Filter using SQL-like syntax. Format: 'field == \"value\"'. Operators: ==, !=, in. Examples: 'tissue == \"lung\"', 'cell_type in [\"T cell\", \"B cell\"]'."

Anti-Pattern 4: No Examples

Bad:

"gene_list": "List of gene symbols"

Good:

"gene_list": "Gene symbols as array. Example: ['TP53', 'MDM2', 'CDKN1A']. Use HGNC symbols for human, MGI for mouse."

Anti-Pattern 5: Hidden Prerequisites

Bad:

"Download H5AD files..."

Good:

"Download H5AD files... Prerequisites: Requires 'package-name' (install: pip install tooluniverse[extra]). Files can be large (GBs)."

---

Description Length Guidelines

Too Short (Unhelpful)

"description": "Query data. Returns results."

Length: 6 words Problem: No context, no guidance

Optimal (Clear and Concise)

"description": "Query single-cell data from 50M+ cell Census. Prerequisites: Requires 'census-api' package. Filter by tissue, cell type, disease. Returns cell metadata. Use for: finding cells, cohort selection, quality filtering."

Length: 35 words Sweet spot: 30-60 words for main description

Too Long (Verbose)

"description": "This tool provides functionality to query single-cell RNA sequencing data from the comprehensive Census database which contains over 50 million cells from various organisms including humans, mice, and non-human primates. Users can filter the data using multiple criteria such as tissue type, cell type classification, disease status, and various other metadata fields. The tool requires the 'census-api' Python package to be installed, which can be done using pip with the command 'pip install tooluniverse[singlecell]'. The results returned include detailed cell metadata information. This tool is particularly useful for researchers who need to find cells matching specific criteria, explore cell type distributions across tissues, perform quality filtering on datasets, or select cohorts for downstream analysis tasks."

Length: 120 words Problem: Too verbose, reader fatigue

---

Testing Your Descriptions

The 30-Second Test

Give someone unfamiliar with the tool just the description. After 30 seconds, can they answer:

1. What does this tool do? 2. What do I need to provide? 3. What will I get back? 4. Do I need anything installed/configured?

If no to any = description needs improvement.

The First-Try Test

Can a user successfully call the tool on their first attempt without:

• Reading external documentation
• Trial and error with parameters
• Asking for help

If no = improve parameter descriptions.

The Decision Test

For parameters with options, can a user confidently choose which option is right for their use case?

If no = add trade-off explanations and recommendations.