tool-design_skill

Overview

This skill helps design, consolidate, and optimize tools that agents use to interact with systems. It focuses on creating unambiguous tool contracts, concise descriptions, and naming conventions that reduce agent confusion. Use it to improve agent reliability, reduce maintenance overhead, and enable more predictable tool selection.

How this skill works

The skill inspects tool collections and their descriptions, evaluates ambiguity, and recommends consolidation or architectural reduction where appropriate. It enforces a consistent schema: clear what/when/inputs/returns, default parameters, response formats, and actionable error messages. It also validates MCP naming rules and suggests namespacing to avoid cross-server collisions.

When to use it

• Designing new agent-facing APIs or tool descriptions from scratch
• Debugging agents that choose the wrong tool or misuse parameters
• Reducing tool count to eliminate overlapping functionality
• Converting many narrow tools into single comprehensive workflows
• Preparing tools for MCP deployments with fully qualified names

Best practices

• Write descriptions that explicitly answer: what the tool does, when to use it, inputs (types and defaults), and exact output shape
• Prefer consolidated, comprehensive tools for workflows unless behaviors are fundamentally different
• Provide concise and detailed response formats so agents can pick verbosity by task
• Design error messages for agent recovery: state the problem, indicate whether retry is valid, and show corrected input examples
• Use consistent naming conventions (verb-noun) and apply namespacing (Server:tool_name) for MCP

Example use cases

• Replace multiple narrow CRUD helpers with a single schedule_event tool that finds availability and books slots
• Audit a tool collection to remove redundant descriptions and reduce token load in agent context
• Convert vague search APIs into well-scoped retrieval tools with explicit query schemas and defaults
• Implement a file-system primitive tool (exec shell commands) to let agents chain Unix utilities for flexible data exploration
• Run an agent-driven tool-testing loop to collect failure examples and auto-generate improved descriptions