# Tool Design

Should be used for the tool-interface layer of an agent system specifically: writing...

- Repository: https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering (18272 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-12
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design -g -a claude-code -y`
Codex: `npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design -g -a codex -y`
Cursor: `npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design -g -a cursor -y`
Gemini CLI: `npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add muratcankoylan/Agent-Skills-for-Context-Engineering`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Tool Design for Agents

Design every tool as a contract between a deterministic system and a non-deterministic agent. Unlike human-facing APIs, agent-facing tools must make the contract unambiguous through the description alone: agents infer intent from descriptions and generate calls that must match expected formats. Every ambiguity becomes a potential failure mode that no amount of prompt engineering can fix.

The unit of work for this skill is a single tool or a tool catalog. Project-shape, pipeline architecture, task-model-fit, and cost-at-the-project-level decisions belong to `project-development`. Deciding whether to introduce sub-agents belongs to `multi-agent-patterns`. This skill owns the interface layer that connects deterministic code to the agent.

## When to Activate

Activate this skill when the unit of work is a tool:

- Writing a new tool description, schema, or response format.
- Debugging cases where the agent picked the wrong tool or generated malformed calls.
- Consolidating an overlapping tool catalog (the classic "we have 17 tools, the agent picks wrong half the time" case).
- Designing actionable error messages so the agent can self-correct.
- Naming tools and parameters consistently across a catalog (MCP namespacing, verb-noun naming).
- Evaluating a third-party tool against the consolidation principle before adding it.

Do not activate this skill for adjacent work owned by other skills:

- Deciding whether the project should use LLMs at all, or what the pipeline stages should be: `project-development`.
- Deciding whether to split work across sub-agents or run a single agent with more tools: `multi-agent-patterns`.
- Reducing the token weight of tool outputs at the trajectory level (observation masking, format-option choice at scale): `context-optimization`.

## Core Concepts

The rest: https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/blob/HEAD/skills/tool-design/SKILL.md