tool-design

Overview of tool-design skill

What tool-design does

The tool-design skill helps you design agent-facing tools that models can choose and call correctly. It is most useful when you are building new tools, simplifying an overloaded tool set, or reviewing a third-party tool interface for agent use. The skill centers on a practical problem: making tool descriptions specific enough that an agent does not guess wrong.

When it is the right fit

Use the tool-design skill for Design Implementation work when the main challenge is tool selection, naming, scope overlap, or unclear behavior at the agent boundary. It is a strong fit for MCP tool design, tool consolidation, and debugging cases where an agent calls the wrong function or ignores the right one. It is less useful if you only need generic API documentation for humans.

What makes it different

This tool-design skill is opinionated about reduction: if tools overlap, agents will misuse them. It emphasizes unambiguous tool contracts, clear activation rules, and description engineering instead of broad prompt advice. That makes it useful when you need fewer, better tools rather than more instructions.

How to Use tool-design skill

Install and inspect the source

Install the tool-design skill with npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design. Then read skills/tool-design/SKILL.md first, followed by references/best_practices.md, references/architectural_reduction.md, and scripts/description_generator.py. Those files show the design logic, the reduction tradeoffs, and the helper patterns that matter most for output quality.

Feed it the right problem statement

The tool-design usage improves when your prompt names the tool boundary, not just the feature. Good inputs say what the tool must decide, what inputs it will receive, and where the current design fails. For example: “Design an agent tool for finding available meeting rooms from calendar data; it should not overlap with booking or search tools.” That is stronger than “create a room tool.”

Use a prompt that includes constraints

For best results, provide the skill with the tool’s purpose, intended caller, expected inputs, failure cases, and any limits on autonomy. If you are redesigning a set, include all candidate tools and ask for consolidation. If you are creating one tool, include parameter names, data types, and examples of valid and invalid calls. The tool-design guide works best when the model can compare alternatives, not infer them.

Practical workflow for design implementation

Start by listing every action the agent can take, then merge actions that share the same intent. Next, define one sentence per tool that states what it does and when it should be used. Finally, test the wording against likely confusion: if two tools sound interchangeable, the descriptions are not ready. For Design Implementation, this is the fastest way to reduce tool selection errors before you add more logic.

tool-design skill FAQ

Is tool-design only for new tools?

No. The tool-design skill is also useful when existing tools are too granular, inconsistently named, or frequently misused by agents. In many teams, the bigger win is redesigning a messy tool set than inventing another function.

How is this different from a normal prompt?

A normal prompt can ask for tool ideas, but the tool-design skill focuses on making tool contracts executable by agents. That means tighter scope, stronger descriptions, explicit activation rules, and attention to overlap. It is better when the output must survive real agent selection behavior, not just read well to a human.

Is it beginner-friendly?

Yes, if you can describe the user task and the tool’s expected inputs. You do not need deep agent-internals knowledge to use the tool-design skill well, but you do need to be specific about boundaries. Vague requests lead to vague tools.

When should I not use it?

Skip tool-design if you are writing end-user API docs, building a pure UI flow, or already have a minimal tool set with clear separation and stable calls. It is also the wrong choice if the main problem is model reasoning rather than tool design.

How to Improve tool-design skill

Give sharper source material

The best tool-design outputs come from concrete examples: the tool name, the exact action, the expected arguments, and two or three common misuse cases. If you only provide a feature name, the result will usually be too generic for agent use. Include the current tool list when you want consolidation, because overlap is the main failure mode this skill tries to prevent.

Ask for explicit tradeoffs

When you want better tool design, ask the skill to explain what was merged, what was dropped, and why. That produces more useful Design Implementation guidance than a simple rewrite. For example, request a before/after tool map, a recommended description, and a short note on the main ambiguity each change removes.

Iterate from bad calls, not guesses

If an agent is already failing, bring the failed tool call, the mistaken tool choice, or the ambiguous description into the next prompt. The tool-design skill is strongest when it can repair a real failure pattern. After the first pass, tighten the wording around the exact confusion the agent showed, then test again.