Name: tool-design
Rating: 51.2 (1 reviews)
Author: administrakt0r

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

56%

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 ./plugins/AI-Agents-Safe-Coding-Skills-claude/skills/tool-design/SKILL.md

The canonical home for this skill is tool-design in administrakt0r/AI-Agents-Safe-Coding-Skills

Quality

Content

42%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 covers real tool-design principles with some useful code examples, but suffers from redundancy, conceptual padding, and dangling references to non-existent files. It reads as a draft that needs tightening and de-duplication.

Suggestions

Remove the duplicated/garbled 'When to Use This Skill' opening block and the repeated 'Tools are contracts...' statements to cut padding.

Either provide the referenced 'Best Practices Reference' and 'Architectural Reduction Case Study' as files under references/ or drop the dangling references.

Trim conceptual exposition Claude already knows (e.g., what tools are, how agents infer contracts) and lead with the actionable framework and examples.

Dimension	Reasoning	Score
Conciseness	Noticeably verbose with redundant padding: the opening 'When to Use This Skill' block duplicates and garbles the title line, 'Tools are contracts between deterministic systems and non-deterministic agents' is restated across Core Concepts and Detailed Topics, and several passages restate concepts Claude already knows.	2 / 5
Actionability	Offers concrete code (the get_customer example, the optimize_tool_description function, MCP naming blocks) and a numbered Tool Selection Framework, but a large share of the body is abstract principle and restated doctrine rather than directly executable guidance.	3 / 5
Workflow Clarity	A 5-step Tool Selection Framework and Testing Tool Design criteria provide a sequence, but there are no validation checkpoints or feedback loops; this is a principles skill rather than a fragile multi-step operation, so 3 rather than lower.	3 / 5
Progressive Disclosure	Section headers organize the body, but it is a single ~300-line monolith and references files that do not exist ('Architectural Reduction Case Study', 'Best Practices Reference') with no bundle files present in references/, scripts/, or assets/.	3 / 5
	Total	11 / 20 Passed

Description

70%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.

A solid description with an explicit 'Use when' trigger clause covering several natural scenarios. Its main weakness is a slightly generic 'what' lead phrase that blunts specificity.

Suggestions

Tighten the 'what' clause to name concrete actions, e.g. 'Design, debug, and consolidate agent tool APIs including architectural reduction patterns.'

Add a couple of natural synonyms (e.g., 'agent tool APIs', 'tooling') to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and a few concrete activities ('creating new tools', 'debugging tool-related failures', 'optimizing existing tool sets') but the lead 'Build tools that agents can use effectively' is generic; not the comprehensive action list of a 4 or 5.	3 / 5
Completeness	Explicitly answers both what ('Build tools that agents can use effectively, including architectural reduction patterns') and when ('Use when creating new tools... debugging... optimizing...'); the 'what' clause is somewhat vague, keeping it below 5.	4 / 5
Trigger Term Quality	'creating new tools', 'debugging tool-related failures or misuse', 'optimizing existing tool sets' are natural phrases users would say; a few common synonyms (e.g., 'agent APIs', 'tooling') are missing, so not a 5.	4 / 5
Distinctiveness Conflict Risk	Tool design for agents is a clear niche with distinct triggers (building/debugging/optimizing agent tools), with only minor overlap risk against a general 'context-fundamentals' or 'multi-agent-patterns' skill.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

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

	Total	15 / 16 Passed

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

Reviewed: 1 day 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.