tool-design

This skill should be used for the tool-interface layer of an agent system specifically: writing tool descriptions agents can route on, designing tool schemas and response formats, naming conventions, actionable error recovery messages, MCP server design, tool-set consolidation, and deciding when to add or remove an individual tool. Use this when the unit of work is a single tool or a set of tools. Route project-shape, pipeline architecture, and task-model-fit decisions to project-development; route deciding whether to introduce sub-agents to multi-agent-patterns.

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

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

Quality

Content

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

A well-structured, largely actionable skill body that suffers from notable repetition across sections and an unreferenced bundled script. Tightening the redundant routing/what-when-returns material and wiring up the script reference would materially improve it.

Suggestions

Consolidate the cross-skill routing that currently appears in the intro, "When to Activate", and "Integration" into a single section to cut repetition and raise conciseness.

Reference scripts/description_generator.py from the body (e.g. in the Tool Description Engineering or Using Agents to Optimize Tools section) so the bundled script is discoverable.

Trim the overlap between the Tool Audit Checklist, the Guidelines list, and the Gotchas list — fold shared points into one canonical location.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but padded with repetition — the what/when/returns framing recurs in Core Concepts, Description Structure, Guidelines, and Gotchas, and the cross-skill routing appears in the intro, "When to Activate", and again verbatim in "Integration"; the Tool Audit Checklist and Guidelines also overlap heavily.	3 / 5
Actionability	Provides mostly executable guidance — a concrete MCP naming example, a well-designed tool docstring (Example 1), a poor-design contrast (Example 2), and checklists — but the optimize_tool_description function is a template with an undefined get_agent_response rather than copy-paste-ready code.	4 / 5
Workflow Clarity	The Tool Selection Framework and Testing section give a clear numbered sequence with concrete criteria; this is an instruction-only skill with no destructive or batch operations, so absent validation checkpoints are not penalizing, though a couple of minor sequencing gaps remain.	4 / 5
Progressive Disclosure	Good structure with one-level-deep references clearly signaled by "Read when:" guidance (architectural_reduction.md, best_practices.md), but scripts/description_generator.py exists in the bundle yet is never referenced from the body, leaving a navigation gap.	4 / 5
	Total	15 / 20 Passed

Description

83%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 strong, specific description with a clear niche and explicit routing to adjacent skills. It could push higher on trigger terms and completeness by adding concrete natural-language trigger phrases users would actually say.

Suggestions

Add concrete natural trigger phrases (e.g. "Use when the user asks to write, name, or consolidate agent tools") alongside the abstract "unit of work" condition to lift completeness and trigger-term quality.

Include a couple of common synonyms ("agent tooling", "tool naming") to broaden natural-term coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "writing tool descriptions agents can route on, designing tool schemas and response formats, naming conventions, actionable error recovery messages, MCP server design, tool-set consolidation, and deciding when to add or remove an individual tool" — giving comprehensive coverage of the skill's scope.	5 / 5
Completeness	Clearly answers "what" (the enumerated tool-interface tasks) and "when" ("Use this when the unit of work is a single tool or a set of tools"), but the trigger side is a single abstract condition rather than the concrete trigger phrases the anchor-5 example uses.	4 / 5
Trigger Term Quality	Good natural-term coverage ("tool descriptions", "tool schemas", "MCP server design", "tool-set consolidation", "single tool or a set of tools") but a few natural phrasings users might say (e.g. "tool naming", "agent tooling") are missing; not comprehensive enough for a 5.	4 / 5
Distinctiveness Conflict Risk	Has a clear niche (the tool-interface layer) and explicitly routes overlapping work elsewhere — "Route project-shape, pipeline architecture, and task-model-fit decisions to project-development; route deciding whether to introduce sub-agents to multi-agent-patterns" — minimizing conflict risk.	5 / 5
	Total	18 / 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: muratcankoylan/Agent-Skills-for-Context-Engineering
Path: skills/tool-design/SKILL.md
Commit: 6dbe1a1

Reviewed: 19 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.