Tool Design

1---
2name: tool-design
3description: This skill should be used when the user asks to "design agent tools", "create tool descriptions", "reduce tool complexity", "implement MCP tools", or mentions tool consolidation, architectural reduction, tool naming conventions, or agent-tool interfaces.
4---
5 
6# Tool Design for Agents
7 
8Tools are the primary mechanism through which agents interact with the world. They define the contract between deterministic systems and non-deterministic agents. Unlike traditional software APIs designed for developers, tool APIs must be designed for language models that reason about intent, infer parameter values, and generate calls from natural language requests. Poor tool design creates failure modes that no amount of prompt engineering can fix. Effective tool design follows specific principles that account for how agents perceive and use tools.
9 
10## When to Activate
11 
12Activate this skill when:
13- Creating new tools for agent systems
14- Debugging tool-related failures or misuse
15- Optimizing existing tool sets for better agent performance
16- Designing tool APIs from scratch
17- Evaluating third-party tools for agent integration
18- Standardizing tool conventions across a codebase
19 
20## Core Concepts
21 
22Tools are contracts between deterministic systems and non-deterministic agents. The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. Effective tool descriptions are prompt engineering that shapes agent behavior.
23 
24Key principles include: clear descriptions that answer what, when, and what returns; response formats that balance completeness and token efficiency; error messages that enable recovery; and consistent conventions that reduce cognitive load.
25 
26## Detailed Topics
27 
28### The Tool-Agent Interface
29 
30**Tools as Contracts**
31Tools are contracts between deterministic systems and non-deterministic agents. When humans call APIs, they understand the contract and make appropriate requests. Agents must infer the contract from descriptions and generate calls that match expected formats.
32 
33This fundamental difference requires rethinking API design. The contract must be unambiguous, examples must illustrate expected patterns, and error messages must guide correction. Every ambiguity in tool definitions becomes a potential failure mode.
34 
35**Tool Description as Prompt**
36Tool descriptions are loaded into agent context and collectively steer behavior. The descriptions are not just documentation—they are prompt engineering that shapes how agents reason about tool use.
37 
38Poor descriptions like "Search the database" with cryptic parameter names force agents to guess. Optimized descriptions include usage context, examples, and defaults. The description answers: what the tool does, when to use it, and what it produces.
39 
40**Namespacing and Organization**
41As tool collections grow, organization becomes critical. Namespacing groups related tools under common prefixes, helping agents select appropriate tools at the right time.
42 
43Namespacing creates clear boundaries between functionality. When an agent needs database information, it routes to the database namespace. When it needs web search, it routes to web namespace.
44 
45### The Consolidation Principle
46 
47**Single Comprehensive Tools**
48The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. This leads to a preference for single comprehensive tools over multiple narrow tools.
49 
50Instead of implementing list_users, list_events, and create_event, implement schedule_event that finds availability and schedules. The comprehensive tool handles the full workflow internally rather than requiring agents to chain multiple calls.
51 
52**Why Consolidation Works**
53Agents have limited context and attention. Each tool in the collection competes for attention in the tool selection phase. Each tool adds description tokens that consume context budget. Overlapping functionality creates ambiguity about which tool to use.
54 
55Consolidation reduces token consumption by eliminating redundant descriptions. It eliminates ambiguity by having one tool cover each workflow. It reduces tool selection complexity by shrinking the effective tool set.
56 
57**When Not to Consolidate**
58Consolidation is not universally correct. Tools with fundamentally different behaviors should remain separate. Tools used in different contexts benefit from separation. Tools that might be called independently should not be artificially bundled.
59 
60### Architectural Reduction
61 
62The consolidation principle, taken to its logical extreme, leads to architectural reduction: removing most specialized tools in favor of primitive, general-purpose capabilities. Production evidence shows this approach can outperform sophisticated multi-tool architectures.
63 
64**The File System Agent Pattern**
65Instead of building custom tools for data exploration, schema lookup, and query validation, provide direct file system access through a single command execution tool. The agent uses standard Unix utilities (grep, cat, find, ls) to explore, understand, and operate on your system.
66 
67This works because:
681. File systems are a proven abstraction that models understand deeply
692. Standard tools have predictable, well-documented behavior
703. The agent can chain primitives flexibly rather than being constrained to predefined workflows
714. Good documentation in files replaces the need for summarization tools
72 
73**When Reduction Outperforms Complexity**
74Reduction works when:
75- Your data layer is well-documented and consistently structured
76- The model has sufficient reasoning capability to navigate complexity
77- Your specialized tools were constraining rather than enabling the model
78- You're spending more time maintaining scaffolding than improving outcomes
79 
80Reduction fails when:
81- Your underlying data is messy, inconsistent, or poorly documented
82- The domain requires specialized knowledge the model lacks
83- Safety constraints require limiting what the agent can do
84- Operations are truly complex and benefit from structured workflows
85 
86**Stop Constraining Reasoning**
87A common anti-pattern is building tools to "protect" the model from complexity. Pre-filtering context, constraining options, wrapping interactions in validation logic. These guardrails often become liabilities as models improve.
88 
89The question to ask: are your tools enabling new capabilities, or are they constraining reasoning the model could handle on its own?
90 
91**Build for Future Models**
92Models improve faster than tooling can keep up. An architecture optimized for today's model may be over-constrained for tomorrow's. Build minimal architectures that can benefit from model improvements rather than sophisticated architectures that lock in current limitations.
93 
94See [Architectural Reduction Case Study](./references/architectural_reduction.md) for production evidence.
95 
96### Tool Description Engineering
97 
98**Description Structure**
99Effective tool descriptions answer four questions:
100 
101What does the tool do? Clear, specific description of functionality. Avoid vague language like "helps with" or "can be used for." State exactly what the tool accomplishes.
102 
103When should it be used? Specific triggers and contexts. Include both direct triggers ("User asks about pricing") and indirect signals ("Need current market rates").
104 
105What inputs does it accept? Parameter descriptions with types, constraints, and defaults. Explain what each parameter controls.
106 
107What does it return? Output format and structure. Include examples of successful responses and error conditions.
108 
109**Default Parameter Selection**
110Defaults should reflect common use cases. They reduce agent burden by eliminating unnecessary parameter specification. They prevent errors from omitted parameters.
111 
112### Response Format Optimization
113 
114Tool response size significantly impacts context usage. Implementing response format options gives agents control over verbosity.
115 
116Concise format returns essential fields only, appropriate for confirmation or basic information. Detailed format returns complete objects with all fields, appropriate when full context is needed for decisions.
117 
118Include guidance in tool descriptions about when to use each format. Agents learn to select appropriate formats based on task requirements.
119 
120### Error Message Design
121 
122Error messages serve two audiences: developers debugging issues and agents recovering from failures. For agents, error messages must be actionable. They must tell the agent what went wrong and how to correct it.
123 
124Design error messages that enable recovery. For retryable errors, include retry guidance. For input errors, include corrected format. For missing data, include what's needed.
125 
126### Tool Definition Schema
127 
128Use a consistent schema across all tools. Establish naming conventions: verb-noun pattern for tool names, consistent parameter names across tools, consistent return field names.
129 
130### Tool Collection Design
131 
132Research shows tool description overlap causes model confusion. More tools do not always lead to better outcomes. A reasonable guideline is 10-20 tools for most applications. If more are needed, use namespacing to create logical groupings.
133 
134Implement mechanisms to help agents select the right tool: tool grouping, example-based selection, and hierarchy with umbrella tools that route to specialized sub-tools.
135 
136### MCP Tool Naming Requirements
137 
138When using MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
139 
140Format: `ServerName:tool_name`
141 
142```python
143# Correct: Fully qualified names
144"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
145"Use the GitHub:create_issue tool to create issues."
146 
147# Incorrect: Unqualified names
148"Use the bigquery_schema tool..."  # May fail with multiple servers
149```
150 
151Without the server prefix, agents may fail to locate tools, especially when multiple MCP servers are available. Establish naming conventions that include server context in all tool references.
152 
153### Using Agents to Optimize Tools
154 
155Claude can optimize its own tools. When given a tool and observed failure modes, it diagnoses issues and suggests improvements. Production testing shows this approach achieves 40% reduction in task completion time by helping future agents avoid mistakes.
156 
157**The Tool-Testing Agent Pattern**:
158 
159```python
160def optimize_tool_description(tool_spec, failure_examples):
161    """
162    Use an agent to analyze tool failures and improve descriptions.
163    
164    Process:
165    1. Agent attempts to use tool across diverse tasks
166    2. Collect failure modes and friction points
167    3. Agent analyzes failures and proposes improvements
168    4. Test improved descriptions against same tasks
169    """
170    prompt = f"""
171    Analyze this tool specification and the observed failures.
172    
173    Tool: {tool_spec}
174    
175    Failures observed:
176    {failure_examples}
177    
178    Identify:
179    1. Why agents are failing with this tool
180    2. What information is missing from the description
181    3. What ambiguities cause incorrect usage
182    
183    Propose an improved tool description that addresses these issues.
184    """
185    
186    return get_agent_response(prompt)
187```
188 
189This creates a feedback loop: agents using tools generate failure data, which agents then use to improve tool descriptions, which reduces future failures.
190 
191### Testing Tool Design
192 
193Evaluate tool designs against criteria: unambiguity, completeness, recoverability, efficiency, and consistency. Test tools by presenting representative agent requests and evaluating the resulting tool calls.
194 
195## Practical Guidance
196 
197### Anti-Patterns to Avoid
198 
199Vague descriptions: "Search the database for customer information" leaves too many questions unanswered.
200 
201Cryptic parameter names: Parameters named x, val, or param1 force agents to guess meaning.
202 
203Missing error handling: Tools that fail with generic errors provide no recovery guidance.
204 
205Inconsistent naming: Using id in some tools, identifier in others, and customer_id in some creates confusion.
206 
207### Tool Selection Framework
208 
209When designing tool collections:
2101. Identify distinct workflows agents must accomplish
2112. Group related actions into comprehensive tools
2123. Ensure each tool has a clear, unambiguous purpose
2134. Document error cases and recovery paths
2145. Test with actual agent interactions
215 
216## Examples
217 
218**Example 1: Well-Designed Tool**
219```python
220def get_customer(customer_id: str, format: str = "concise"):
221    """
222    Retrieve customer information by ID.
223    
224    Use when:
225    - User asks about specific customer details
226    - Need customer context for decision-making
227    - Verifying customer identity
228    
229    Args:
230        customer_id: Format "CUST-######" (e.g., "CUST-000001")
231        format: "concise" for key fields, "detailed" for complete record
232    
233    Returns:
234        Customer object with requested fields
235    
236    Errors:
237        NOT_FOUND: Customer ID not found
238        INVALID_FORMAT: ID must match CUST-###### pattern
239    """
240```
241 
242**Example 2: Poor Tool Design**
243 
244This example demonstrates several tool design anti-patterns:
245 
246```python
247def search(query):
248    """Search the database."""
249    pass
250```
251 
252**Problems with this design:**
253 
2541. **Vague name**: "search" is ambiguous - search what, for what purpose?
2552. **Missing parameters**: What database? What format should query take?
2563. **No return description**: What does this function return? A list? A string? Error handling?
2574. **No usage context**: When should an agent use this versus other tools?
2585. **No error handling**: What happens if the database is unavailable?
259 
260**Failure modes:**
261- Agents may call this tool when they should use a more specific tool
262- Agents cannot determine correct query format
263- Agents cannot interpret results
264- Agents cannot recover from failures
265 
266## Guidelines
267 
2681. Write descriptions that answer what, when, and what returns
2692. Use consolidation to reduce ambiguity
2703. Implement response format options for token efficiency
2714. Design error messages for agent recovery
2725. Establish and follow consistent naming conventions
2736. Limit tool count and use namespacing for organization
2747. Test tool designs with actual agent interactions
2758. Iterate based on observed failure modes
2769. Question whether each tool enables or constrains the model
27710. Prefer primitive, general-purpose tools over specialized wrappers
27811. Invest in documentation quality over tooling sophistication
27912. Build minimal architectures that benefit from model improvements
280 
281## Integration
282 
283This skill connects to:
284- context-fundamentals - How tools interact with context
285- multi-agent-patterns - Specialized tools per agent
286- evaluation - Evaluating tool effectiveness
287 
288## References
289 
290Internal references:
291- [Best Practices Reference](./references/best_practices.md) - Detailed tool design guidelines
292- [Architectural Reduction Case Study](./references/architectural_reduction.md) - Production evidence for tool minimalism
293 
294Related skills in this collection:
295- context-fundamentals - Tool context interactions
296- evaluation - Tool testing patterns
297 
298External resources:
299- MCP (Model Context Protocol) documentation
300- Framework tool conventions
301- API design best practices for agents
302- Vercel d0 agent architecture case study
303 
304---
305 
306## Skill Metadata
307 
308**Created**: 2025-12-20
309**Last Updated**: 2025-12-23
310**Author**: Agent Skills for Context Engineering Contributors
311**Version**: 1.1.0
312