tool-design

Build tools that agents can use effectively, including architectural reduction patterns. Use when creating new tools for agent systems, debugging tool-related failures or misuse, or optimizing existing tool sets for better agent performance.

Quality

51%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/tool-design/SKILL.md

Quality

Content

32%Scale 1-5

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

This skill reads more like a textbook chapter on tool design philosophy than an actionable skill for Claude. It is excessively verbose, repeatedly explaining concepts Claude already knows (what APIs are, why good naming matters, what contracts mean), while lacking concrete workflows with validation steps. The few code examples are helpful but insufficient to offset the large amount of abstract conceptual content that doesn't earn its token cost.

Suggestions

Cut the content by 60-70% by removing explanations of concepts Claude already knows (e.g., 'Tools are contracts between deterministic systems and non-deterministic agents' doesn't need multi-paragraph elaboration) and focus on the unique, non-obvious guidance like the consolidation principle decision framework and MCP naming requirements.

Add a concrete, step-by-step workflow for designing a tool with explicit validation checkpoints, e.g.: 1. Define the tool spec → 2. Validate against the 4-question checklist → 3. Test with sample agent requests → 4. Analyze failures → 5. Iterate on description.

Split detailed topics (architectural reduction, description engineering, response format optimization) into separate referenced files, keeping SKILL.md as a concise overview with clear navigation links.

Replace the abstract 'Tool Selection Framework' with a concrete decision tree or checklist that Claude can directly apply, including specific criteria for when to consolidate vs. separate tools.

Dimension	Reasoning	Score
Conciseness	The skill is severely verbose, extensively explaining concepts Claude already understands well (what tools are, what contracts mean, why consolidation works, basic API design principles). Multiple sections restate the same ideas in slightly different ways. The 'Tool-Agent Interface' section explains obvious concepts like 'tools are contracts' multiple times. The 'When to Use This Skill' section is duplicated at the top. Much of this content is general knowledge that doesn't need to be taught to Claude.	2 / 5
Actionability	The skill provides some concrete examples (the get_customer tool definition, the MCP naming format, the optimize_tool_description function), but much of the content is abstract guidance and principles rather than executable steps. The code examples are illustrative but not truly copy-paste ready for building tools. The 'poor tool design' example is useful but the overall content leans heavily toward conceptual explanation rather than concrete, actionable instructions.	3 / 5
Workflow Clarity	There is no clear multi-step workflow for actually designing or building a tool. The 'Tool Selection Framework' provides a numbered list but it's high-level and lacks validation checkpoints. The tool-testing agent pattern has a rough sequence but no verification steps. For a skill that involves designing tools (which can have significant downstream failure modes), there are no feedback loops or validation steps to ensure tool designs are correct before deployment.	2 / 5
Progressive Disclosure	The content is a monolithic wall of text (~300+ lines) with no bundle files to support it. References to 'Architectural Reduction Case Study', 'Best Practices Reference', and related skills are mentioned but no actual files are provided. The content that could be split into separate files (detailed topics like architectural reduction, description engineering, response format optimization) is all inlined, making the skill unwieldy.	2 / 5
	Total	9 / 20 Passed

Description

71%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 has strong completeness with a clear 'Use when' clause covering three distinct scenarios. However, it lacks specificity in the concrete actions it describes—terms like 'build tools' and 'optimizing' are broad. The trigger terms could be improved with more natural user language and common synonyms related to agent tool design.

Suggestions

Add more specific concrete actions such as 'design tool schemas', 'reduce tool count through composition', or 'structure tool parameters for reliable agent invocation' to improve specificity.

Include additional natural trigger terms users might say, such as 'function calling', 'tool use API', 'MCP tools', 'tool schema design', or 'too many tools' to improve discoverability.

Dimension	Reasoning	Score
Specificity	Names the domain (agent tool building) and mentions 'architectural reduction patterns' as a concrete concept, but the actions listed ('build tools', 'debugging', 'optimizing') are fairly generic and don't describe specific concrete techniques or outputs comprehensively.	3 / 5
Completeness	Clearly answers both 'what' (build tools for agents, including architectural reduction patterns) and 'when' (creating new tools, debugging tool failures/misuse, optimizing existing tool sets) with explicit trigger scenarios in a 'Use when' clause.	5 / 5
Trigger Term Quality	Includes some relevant keywords like 'tools', 'agents', 'agent systems', 'debugging', 'tool-related failures', and 'optimizing', but misses natural user phrases like 'function calling', 'tool use', 'API design for agents', 'tool schema', or 'MCP tools' that users might naturally say.	3 / 5
Distinctiveness Conflict Risk	The focus on agent tool design with 'architectural reduction patterns' is fairly distinctive and unlikely to overlap with general coding or debugging skills. However, 'debugging tool-related failures' could potentially overlap with general debugging skills, creating minor conflict risk.	4 / 5
	Total	15 / 20 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/tool-design/SKILL.md
Commit: debb2ec

Reviewed: 14 hours 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.