Optimize tool descriptions in ToolUniverse JSON configs for clarity and usability. Reviews descriptions for missing prerequisites, unexpanded abbreviations, unclear parameters, and missing usage guidance. Use when reviewing tool descriptions, improving API documentation, or when user asks to check i

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 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. 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. 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.) 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. 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. 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. Medium Priority Improvements 7. Add File Size Warnings For tools that download or return large files: 8. Clarify Web Form vs API Results When tool returns submission URL instead of direct results: 9. Explain File Type Differences For tools with multiple format options: Description Structure Template 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 Key elements: What you're querying How to filter What you get back Scale of data Prerequisites Data Download Tools Key elements: File formats available Size warning Authentication needs What's in the files Enrichment/Analysis Tools Key elements: Input requirements clear Options numbered What gets compared What you learn Validation Commands After updating descriptions, validate JSON syntax: Example: Before and After Before (Unclear): After (Clear): 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.

devtu-optimize-descriptions