tool-design

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