tool-design

tessl i github:muratcankoylan/Agent-Skills-for-Context-Engineering --skill 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.

51%

Overall

Validation — 88%

Implementation — 35%

Activation — 48%

SKILL.md

Review

Evals

Validation

88%

Warnings & errors only

Criteria	Description	Result
metadata_version	'metadata' field is not a dictionary	Warning
license_field	'license' field is missing	Warning

	Total	14 / 16 Passed

Implementation

35%

This skill suffers from significant verbosity, explaining foundational concepts Claude already knows while burying actionable guidance in prose. The content has useful examples and references but would benefit from aggressive trimming to focus on concrete patterns and executable code rather than conceptual explanations of tool design philosophy.

Suggestions

Cut 60-70% of explanatory prose - remove sections explaining what tools are, why consolidation works conceptually, and other concepts Claude already understands

Move detailed topics (Tool-Agent Interface, Consolidation Principle, Architectural Reduction) to reference files, keeping only actionable summaries in the main skill

Add more executable code examples showing complete tool definitions with before/after comparisons rather than prose descriptions of anti-patterns

Add explicit validation steps to the Tool Selection Framework (e.g., 'Test with 5 representative queries before deployment, verify <90% correct tool selection')

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 'poor tool design creates failure modes' and 'tools define contracts' that don't add actionable value.	1 / 3
Actionability	Contains some concrete code examples (the get_customer tool, the optimize_tool_description function), but much content is abstract guidance rather than executable patterns. The 'poor tool design' example shows what NOT to do but the fix isn't shown as executable code.	2 / 3
Workflow Clarity	The Tool Selection Framework provides a numbered sequence, and the Tool-Testing Agent Pattern shows a process, but there are no validation checkpoints or feedback loops for error recovery. The guidelines are listed but not sequenced as a workflow with verification steps.	2 / 3
Progressive Disclosure	References external files (best_practices.md, architectural_reduction.md) appropriately, but the main content is a monolithic wall of text with too much inline detail. The 'Detailed Topics' section contains content that should be in reference files rather than the main skill.	2 / 3
	Total	7 / 12 Passed

Activation

48%

This description is essentially a trigger-phrase 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'. A reader cannot understand the skill's capabilities or outputs from this description.

Suggestions

Add a clear 'what' statement at the beginning describing concrete capabilities, e.g., 'Designs and documents agent tool interfaces, creates tool schemas, and optimizes tool architectures for clarity and minimal complexity.'

Restructure to lead with capabilities, then follow with 'Use when...' clause - the current format inverts the expected pattern and omits essential information.

Specify concrete outputs or deliverables the skill produces (e.g., 'tool specifications', 'API schemas', 'documentation templates') to help Claude understand what this skill actually accomplishes.

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 actions are somewhat abstract rather than describing what the skill actually produces.	2 / 3
Completeness	The description only addresses 'when' (trigger conditions) but completely omits 'what' - there's no explanation of what the skill actually does, what outputs it produces, or what capabilities it provides. It's essentially just a list of trigger phrases.	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 realistic phrases a user would naturally use.	3 / 3
Distinctiveness Conflict Risk	The focus on 'agent tools' and 'MCP tools' provides some specificity, but terms like 'tool descriptions' and 'naming conventions' could overlap with general documentation or coding style skills. The niche is somewhat defined but not sharply bounded.	2 / 3
	Total	8 / 12 Passed

Reviewed

18 days ago

Table of Contents

Validation Implementation Activation

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.