tool-design
This skill should be used when the user asks to "design agent tools", "create tool descriptions", "reduce tool complexity", "implement MCP tools", or mentions tool consolidation, architectural reduction, tool naming conventions, or agent-tool interfaces.
Install with Tessl CLI
npx tessl i github:muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design60
Quality
41%
Does it follow best practices?
Impact
89%
0.98xAverage score across 3 eval scenarios
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/tool-design/SKILL.mdDiscovery
47%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is essentially a trigger-term list masquerading as a skill description. While it excels at providing natural keywords users might say, it completely fails to explain what the skill actually does - there's no 'what' component, only 'when'. This inverted structure makes it difficult for Claude to understand the skill's actual capabilities.
Suggestions
Add a clear capability statement at the beginning explaining what this skill does (e.g., 'Designs and optimizes tool interfaces for AI agents, including schema creation, parameter design, and documentation generation.').
Restructure to lead with 'what' before 'when' - describe concrete actions like 'creates tool schemas', 'writes tool descriptions', 'consolidates redundant tools' before listing trigger phrases.
Convert the trigger phrase list into a proper 'Use when...' clause that follows the capability description rather than replacing it.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (agent tools, MCP tools) and mentions some actions like 'design', 'create', 'reduce', 'implement', but doesn't list concrete specific capabilities or outcomes. The description focuses more on trigger terms than explaining what the skill actually does. | 2 / 3 |
Completeness | The description only addresses 'when' (trigger conditions) but completely omits 'what' - there's no explanation of what capabilities this skill provides or what it actually does. It's essentially just a list of trigger phrases without describing the skill's functionality. | 1 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'design agent tools', 'create tool descriptions', 'reduce tool complexity', 'implement MCP tools', 'tool consolidation', 'architectural reduction', 'tool naming conventions', 'agent-tool interfaces'. These are specific, varied, and realistic user phrases. | 3 / 3 |
Distinctiveness Conflict Risk | The focus on 'agent tools' and 'MCP tools' provides some distinctiveness, but terms like 'tool descriptions' and 'naming conventions' could overlap with general documentation or coding style skills. The lack of concrete capability description makes it harder to distinguish from related skills. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill contains valuable concepts about tool design for agents but suffers from significant verbosity, explaining foundational concepts Claude already knows. The actionable content (code examples, naming conventions) is buried in extensive prose. The skill would benefit from aggressive trimming to focus on concrete patterns and executable examples rather than theoretical explanations.
Suggestions
Cut 60-70% of conceptual prose (e.g., 'Tools are contracts between deterministic systems...' explanations) and lead with executable tool definition templates
Move detailed topics like 'The Consolidation Principle' theory and 'Architectural Reduction' philosophy to reference files, keeping only actionable summaries in the main skill
Replace the pseudocode optimize_tool_description function with a complete, executable example or remove it entirely
Add a validation checklist for tool designs (e.g., 'Before deploying: verify description answers what/when/returns, test with 3 representative queries, confirm error messages are actionable')
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is extremely verbose at ~2000+ words, explaining concepts Claude already understands (what tools are, what contracts mean, basic API design). Extensive prose explains obvious principles like 'tools define contracts' and 'poor design creates failure modes' that don't add actionable value. | 1 / 3 |
Actionability | Contains some concrete examples (the get_customer tool definition, MCP naming format), but much content is conceptual rather than executable. The optimize_tool_description function is pseudocode with placeholder get_agent_response(). Missing copy-paste ready templates for common tool design scenarios. | 2 / 3 |
Workflow Clarity | The 'Tool Selection Framework' provides a 5-step sequence, but lacks validation checkpoints. The tool-testing agent pattern describes a process but without explicit verification steps. No feedback loops for catching tool design errors before deployment. | 2 / 3 |
Progressive Disclosure | References external files (best_practices.md, architectural_reduction.md) appropriately, but the main document is a monolithic wall of text. Content that could be in reference files (detailed consolidation theory, architectural reduction philosophy) is inline, bloating the overview. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Reviewed
Table of Contents
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.