Skip to content
Get packs

Guide · Agent skill

How to use the Tool Design for Agents skill (tool-design)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The tool-design skill gives an AI agent guidance on the tool-interface layer: the descriptions, parameter formats, names, error messages and tool sets that the agent uses to choose and call tools. It is aimed at developers building agents or MCP servers, and at teams reviewing tools before adding them. After this guide you will know how to install the skill, how to phrase requests that trigger it, and what it does and does not cover.

Tool Design for Agentsmuratcankoylan/Agent-Skills-for-Context-Engineering · MIT

Quick start

  1. 1Download the skill. Get the ZIP for skills/tool-design from the directory page.
  2. 2Unzip it into the right folder. Use ~/.claude/skills/ for personal use or the project's .claude/skills/ for one project.
  3. 3Or upload it in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill.
  4. 4Ask a tool-level question. Describe the tool, its current description or the problem you see, such as wrong tool choice or malformed calls.
  5. 5Review the output against your catalog. Check that each tool has one clear purpose and that descriptions say what it does, when to use it and what it returns.

What the tool-design skill makes the agent do

The skill treats each tool as a contract between deterministic code and a language model. The agent infers how to use a tool from its description alone, so the skill focuses on making that description, its schema and its response format unambiguous.

Its guidance covers writing descriptions the agent can route on, designing schemas and response formats, naming conventions, actionable error recovery messages, MCP server design, consolidating overlapping tools, and deciding when to add or remove an individual tool.

  • Write descriptions that say what the tool does, when to use it, and what it returns.
  • Define parameter formats and namespaces such as db_* or web_* so the agent can group tools.
  • Write error messages that tell the agent how to correct a malformed call.
  • Merge overlapping tools into fewer tools with one clear purpose each.

Install the tool-design skill

Download the ZIP for skills/tool-design from the directory page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the skill

Trigger the skill with natural requests

You do not need a special command. Describe the tool-design task in plain language and the agent should apply the skill when the work is about a single tool or a set of tools.

The skill is meant for requests about the interface layer. For project structure, pipeline architecture or whether to use sub-agents, the skill directs you to other skills, so ask those questions separately.

  • Why does my agent keep picking the wrong tool? Here is the tool list.
  • Rewrite this tool description so the agent knows when to call it and what it returns.
  • These three tools overlap. Should I merge them?
  • Write error messages that help the agent fix malformed calls to this tool.
  • Review this third-party MCP tool before I add it to my agent.

Use the description generator and vagueness check

The package includes a Python helper script, scripts/description_generator.py. According to the skill's description, it generates tool descriptions, scores descriptions for vagueness and produces error message templates. Python is required to run it.

The script runs locally, and the skill does not use the network. Read the script before running it so you know what it will do on your machine.

  • Requires Python.
  • Runs scripts: yes.
  • Uses network: no.

Reference files for deeper detail

The package includes two reference documents. references/architectural_reduction.md covers production evidence for replacing specialized tools with a small set of general-purpose ones, including when reduction helps and when it does not. references/best_practices.md collects description engineering principles.

Read the reference files when you are making a larger decision about tool reduction rather than a quick rewrite of one description.

  • references/architectural_reduction.md
  • references/best_practices.md
  • SKILL.md (the main instructions)

What people use it for

  • Rewriting vague tool descriptions so an agent chooses the right tool more often.
  • Consolidating a catalog of overlapping tools into fewer tools with clear purposes.
  • Writing error messages that let an agent correct a malformed call on its own.
  • Reviewing an MCP server's tool names, parameters and namespaces before release.
  • Assessing a third-party tool before adding it to an agent's toolset.

Frequently asked questions

Is the tool-design skill free to use?

The skill is listed under the MIT licence. Check the licence file in the source repository for the full terms before you redistribute it.

What do I need to run the tool-design skill?

You need a Claude setup that supports agent skills, either through the ~/.claude/skills/ or .claude/skills/ folders or the Settings → Capabilities → Skills upload. To run the included description_generator.py script you need Python. The skill does not use the network.

How do I install the tool-design skill?

Download the ZIP for skills/tool-design from the directory page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Does this skill design my whole agent or project?

No. It covers the tool-interface layer only. Project structure, pipeline architecture and sub-agent decisions are handled by other skills, which the skill names as project-development and multi-agent-patterns.

Is it safe to run the included script?

The skill runs scripts and includes a Python helper. Read scripts/description_generator.py before running it. The skill uses no network access according to its listing.

How is this different from just prompting the model about tools?

This skill packages guidance specific to tool design, such as consolidation, namespacing and error recovery messages, plus reference material and a helper script. It is narrower than a general prompt and targets tool selection and call formatting.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building agents or MCP servers and need help with tool descriptions, schemas, error messages or consolidating overlapping tools. Pick something else if you have no tool-based agent to configure or need help with project architecture or sub-agent decisions, since the skill routes those to other skills.

Download the skill