Individual skill

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.

skills/tool-design/SKILL.md

Read pinned source

Source commit b436d6bb494c8731c8181783f75fdc5c28013912

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: No
Repository scan complete: No
Skill scan complete: No
Observed behavior: Not checked yet
Last checked: Nov 4, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 991
Repository last updated: Nov 8, 2026
License: MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

ai-skills Repository topic
workflows Repository topic
skills Repository topic
anthropic-skills Repository topic
planning Repository topic
superpowers Repository topic
context-engineering Repository topic
ui-ux-design Repository topic
ai-agents Repository topic
claude-code Repository topic
engineering Derived category
design Derived category
writing Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

SKILL.mdcore · 20,089 bytes
SKILL.mdcore · 20,089 bytes
SKILL.mdcore · 20,089 bytes
SKILL.mdcore · 20,089 bytes
SKILL.mdcore · 20,089 bytes
references/architectural_reduction.mddoc · 8,138 bytes
references/best_practices.mddoc · 10,510 bytes
scripts/description_generator.pyruns · 18,057 bytes

Read excerpt


# 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.