tool-design

This skill provides a systematic methodology for creating robust, agent-facing tools. It treats every tool as a strict contract between a deterministic system and a non-deterministic agent, ensuring that descriptions act as critical prompt engineering to minimize selection errors and hallucinations. It is essential for developers building production-grade agent systems who struggle with tool confusion, redundant capabilities, or poor routing performance.

The framework centers on the Consolidation Principle, which advocates for reducing tool complexity by merging narrow, overlapping tools into comprehensive, unambiguous functions. By refining tool namespaces, parameter formats, and usage context, the skill helps developers achieve higher reliability and lower context budget consumption, directly addressing common issues like the 'lost-in-the-middle' phenomenon during tool selection.

• Designing agent-specific APIs that function as clear, self-contained contracts.

• Optimizing tool descriptions to serve as high-signal prompt inputs for reasoning models.

• Implementing architectural reduction by replacing complex, specialized tooling with standardized primitives like filesystem operations.

• Applying namespacing and hierarchical organization to improve agent routing efficiency.

• Debugging tool-related failures, including misuse, parameter formatting errors, and selection ambiguity.

• Standardizing tool conventions to ensure consistent behavior across heterogeneous model backends.

• Best for: AI engineers, platform architects, and developers building agentic workflows in Claude Code, Cursor, or custom MCP (Model Context Protocol) implementations.

• Inputs: Needs definition of tool goals, expected inputs/outputs, and potential failure modes.

• Outputs: Highly structured, unambiguous tool definitions that minimize guessing and maximize success rates.

• Usage Tip: Focus on answering 'what the tool does,' 'when to use it,' and 'what it returns' to align with internal agent reasoning processes.

• Constraint: Avoid over-consolidation that creates overly complex single tools with too many modes; focus on balance and maintainability.