devtu-optimize-descriptions

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 if tools are easy to understand.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable, with concrete before/after examples, exact fix patterns, and executable validation commands organized by fix priority. Its weaknesses are redundancy across the three checklists and testing sections, and a monolithic all-inline structure with no reference files for content that would benefit from being split out.

Suggestions

Merge the 'Quick Optimization Checklist', 'Description Quality Checklist', and 'Testing Description Quality' sections into a single checklist to remove the repeated items (prerequisites, abbreviations, examples, mutually exclusive options).

Move the 'Common Patterns by Tool Type' templates and the 'Description Structure Template' into a references/ file (e.g., references/patterns.md) and link to them from SKILL.md to reduce inline bulk and enable progressive disclosure.

Add an explicit validation feedback loop after the 'Validation Commands' section, e.g., 'If a file fails validation, fix the JSON syntax error reported and re-run the check before proceeding'.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient but has several redundant sections — the "Quick Optimization Checklist" and "Description Quality Checklist" repeat the same items, and "Testing Description Quality" plus the "Summary" restate points already made — which could be tightened into one checklist, fitting anchor 3's 'some unnecessary explanation or could be tightened' rather than anchor 4's 'minor instances'.	3 / 5
Actionability	Guidance is fully executable: concrete before/after JSON diffs, exact fix formats ("Required: Provide ONE input type - (1) BED regions, (2) DNA motif, or (3) gene list"), a reusable structure template, and copy-paste validation commands ("python3 -m json.tool src/tooluniverse/data/your_tools.json"), matching anchor 5's 'copy-paste ready' with examples covering the common cases.	5 / 5
Workflow Clarity	The priority ordering (Critical → High → Medium) provides a clear fix sequence and the "Validation Commands" section checks the batch JSON edits, but there is no explicit error-recovery loop (what to do when a file fails validation), placing it at anchor 4's 'most checkpoints present; minor validation gaps' rather than anchor 5's explicit feedback loop.	4 / 5
Progressive Disclosure	The ~330-line body is well-sectioned but entirely inline with no bundle files or references; content such as the "Common Patterns by Tool Type" templates and duplicated checklists would fit better in separate reference files, matching anchor 3's 'content that should be separate is inline' rather than anchor 4's 'most content appropriately placed'.	3 / 5
	Total	15 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, complete, and distinctive: it states concrete review actions in a clearly named domain and provides an explicit, natural 'Use when' clause. The only weakness is modest trigger-term coverage that omits some common synonyms for documentation and clarity review.

Dimension	Reasoning	Score
Specificity	The description names the domain ("ToolUniverse JSON configs") and enumerates four concrete review actions — "missing prerequisites, unexpanded abbreviations, unclear parameters, and missing usage guidance" — giving comprehensive coverage within its niche, matching the anchor 5 example's breadth rather than anchor 4's 'minor gaps'.	5 / 5
Completeness	It explicitly answers both 'what' ("Optimize tool descriptions... Reviews descriptions for...") and 'when' ("Use when reviewing tool descriptions, improving API documentation, or when user asks to check if tools are easy to understand") with concrete trigger phrases, matching the anchor 5 example structure; not 4 because the 'when' clause is already explicit and specific rather than improvable.	5 / 5
Trigger Term Quality	"Use when reviewing tool descriptions, improving API documentation, or when user asks to check if tools are easy to understand" includes several natural user phrases, but misses common synonyms and variations (e.g., 'tool docs', 'make descriptions clearer'), so it fits anchor 4's 'a few natural terms missing' rather than anchor 5's comprehensive synonym coverage.	4 / 5
Distinctiveness Conflict Risk	"ToolUniverse JSON configs" pins the skill to a clear niche with distinct triggers (tool description review, API documentation improvement), minimizing overlap with generic documentation skills; this matches anchor 5's 'clear niche with distinct triggers'.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mims-harvard/ToolUniverse
Path: skills/devtu-optimize-descriptions/SKILL.md
Commit: 164aaf1

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.