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.