tool-design

1# Tool Design for Agents
2 
3Design 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.
4 
5The 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.
6 
7## When to Activate
8 
9Activate this skill when the unit of work is a tool:
10 
11- Writing a new tool description, schema, or response format.
12- Debugging cases where the agent picked the wrong tool or generated malformed calls.
13- Consolidating an overlapping tool catalog (the classic "we have 17 tools, the agent picks wrong half the time" case).
14- Designing actionable error messages so the agent can self-correct.
15- Naming tools and parameters consistently across a catalog (MCP namespacing, verb-noun naming).
16- Evaluating a third-party tool against the consolidation principle before adding it.
17 
18Do not activate this skill for adjacent work owned by other skills:
19…