yigityildiz0 Tool Design for AI Agents
Specialized expertise in designing tools, APIs, and function interfaces that AI agents can use effectively. Tools designed for human developers follow different principles than tools designed for LLM-powered agents; this skill bridges that gap.
When to Use This Skill
Use this skill for:
- Building MCP (Model Context Protocol) servers
- Creating custom Claude Code slash commands
- Designing APIs that AI agents will consume
- Optimizing tool descriptions for better agent selection
- Reducing tool confusion in multi-tool environments
- Building function-calling interfaces for LLM applications
Trigger phrases: "tool design", "MCP server", "design tools for agents", "tool descriptions", "agent tools", "function schema", "tool selection", "tool confusion", "API for AI"
What This Skill Does
Provides tool design expertise including:
- LLM-Oriented Design: Building tools agents can reason about effectively
- Description Engineering: Writing descriptions that guide correct tool selection
- Tool Consolidation: Managing tool count to avoid agent confusion
- Error Design: Structuring error responses for agent recovery
- Naming Conventions: Consistent naming that aids tool discovery
- Testing Methodology: Validating tools against actual agent interactions
Instructions
Step 1: Design Tools for LLM Consumption
The core insight: tools designed for AI agents differ fundamentally from tools designed for human developers. Humans read documentation, understand context from experience, and recover from cryptic errors through investigation. Agents have none of these advantages; they rely entirely on the tool's description, parameter names, and error messages to decide how to use it.
The Consolidation Principle:
If a human engineer cannot definitively say which tool should be used for a given task, an agent cannot be expected to do better.
Before creating multiple similar tools, ask: "Would a developer be confused about which one to use?" If yes, consolidate them.
Design Checklist for Each Tool:
- Single responsibility: The tool does exactly one thing well
- Self-documenting: Description + parameter names make usage obvious without external docs
- Predictable output: Same inputs always produce the same output structure
- Graceful errors: Errors tell the agent what to do next (not just what went wrong)
- Minimal parameters: Only require what is essential; use sensible defaults for everything else
- Structured output: Return structured data (JSON) rather than unstructured text
Anti-patterns to avoid:
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Vague description ("Utility tool for various operations") | Agent cannot determine when to use it | Be specific: "Read a file and return its contents as UTF-8 text" |
Cryptic parameter names (p1, opts, flags) |
Agent must guess parameter meanings | Use descriptive names: file_path, output_format, include_line_numbers |
Overlapping tools (both search_files and find_in_code search) |
Agent picks arbitrarily or uses the wrong one | Consolidate into one tool with clear parameters |
| Silent failures (returns empty on error) | Agent cannot distinguish "no results" from "error" | Always return explicit success/failure status |
Step 2: Engineer Tool Descriptions
Every tool description must answer four questions. An agent reads the description at selection time and must be able to determine:
- What does this tool do? (capability)
- When should I use it? (trigger conditions)
- What inputs does it need? (parameters)
- What will it return? (output format)
Description Template:
[One sentence: what the tool does]
Use this tool when [specific trigger conditions]. Do NOT use this tool when
[common confusion cases].
Parameters:
- [param_name] (required/optional): [Clear description with examples]
Returns: [Output format description with example]
Good vs. Bad Descriptions:
| Quality | Description |
|---|---|
| Bad | "Searches for stuff in files" |
| Good | "Search file contents for a regex pattern and return matching lines with file paths and line numbers. Use this tool when looking for code patterns, function definitions, or string occurrences across multiple files. Do NOT use this tool for finding files by name (use glob instead)." |
| Bad | "Runs a command" |
| Good | "Execute a shell command and return stdout, stderr, and exit code. Use for git operations, build commands, and system tasks. Do NOT use for reading files (use the read tool) or searching content (use the grep tool)." |
Parameter Description Guidelines:
- Include the type: "file_path (string, required): Absolute path to the file"
- Include examples: "output_format (string, optional): 'json' or 'text'. Default: 'json'"
- Include constraints: "max_results (integer, optional): Maximum results to return. Range: 1-1000. Default: 100"
- State what happens with invalid values: "If path does not exist, returns an error with suggested alternatives"
Step 3: Manage Tool Count
The 10-20 Tool Limit: Research and practice show that agents perform best with 10-20 active tools. Beyond this, selection accuracy degrades as the agent must evaluate more descriptions and distinguish between more options.
Strategies for Larger Tool Sets:
| Strategy | When to Use | How |
|---|---|---|
| Namespacing | Tools from multiple servers | Use ServerName:tool_name format (e.g., GitHub:create_pr, Jira:create_issue) |
| Dynamic loading | Domain-specific tools | Load only tools relevant to current task; unload when switching domains |
| Tool groups | Related tools that cluster naturally | Present as a single "toolkit" that the agent can expand when needed |
| Consolidation | Overlapping tools | Merge similar tools into one with mode/type parameters |
Consolidation Example:
Before (3 tools, confusing):
- search_files: Search for files by name
- search_content: Search file contents
- find_pattern: Find regex patterns in code
After (1 tool, clear):
- search:
mode: "files" | "content" | "regex"
query: string
path: string (optional, defaults to workspace root)
When NOT to consolidate: If the tools have genuinely different input/output schemas, different performance characteristics, or serve clearly distinct use cases, keep them separate. Forced consolidation creates tools that are hard to describe.
Step 4: Design Error Messages for Agent Recovery
Error messages for human developers say what went wrong. Error messages for AI agents must also say what to try next.
Error Message Structure:
{
"success": false,
"error": {
"code": "FILE_NOT_FOUND",
"message": "The file '/src/utils/helpers.ts' does not exist.",
"suggestion": "Did you mean '/src/utils/helper.ts' (without 's')? Use the glob tool with pattern '**/helper*' to find similar files.",
"recoverable": true
}
}
Error Design Principles:
| Principle | Example |
|---|---|
| State what happened | "File not found: /path/to/file.ts" |
| Suggest recovery action | "Try using glob to find the correct path" |
| Indicate recoverability | "recoverable": true (agent should retry) vs "recoverable": false (agent should stop) |
| Include context | "Permission denied for /etc/shadow. This file requires root access." |
| Avoid ambiguity | Not "Operation failed" but "Write failed: disk full (0 bytes remaining)" |
Common Error Categories and Recovery Hints:
| Error Category | Recovery Hint Pattern |
|---|---|
| Not found | "Use [discovery tool] to find the correct [resource]" |
| Permission denied | "This operation requires [permission]. Ask the user for access." |
| Invalid input | "Expected [format]. Example: [valid example]" |
| Rate limited | "Retry after [N] seconds" |
| Timeout | "Operation timed out after [N]s. Try with a smaller scope." |
Step 5: Test Against Agent Interactions
Tools should be tested with actual agent interactions, not just unit tests.
Testing Checklist:
## Tool Testing Protocol
### Selection Tests
- [ ] Given a task description, does the agent pick the right tool?
- [ ] Does the agent avoid using this tool for tasks it shouldn't handle?
- [ ] When multiple similar tools exist, does the agent distinguish correctly?
### Usage Tests
- [ ] Does the agent provide correct parameter values?
- [ ] Does the agent handle optional parameters appropriately?
- [ ] Does the agent interpret the output correctly?
### Error Recovery Tests
- [ ] When the tool returns an error, does the agent recover?
- [ ] Does the agent follow the suggested recovery action?
- [ ] Does the agent avoid retrying non-recoverable errors?
### Integration Tests
- [ ] Does the tool work correctly in multi-step workflows?
- [ ] Can the agent chain this tool's output into other tools?
- [ ] Does the tool's output format work well in context?
Confusion Indicators (signs your tool design needs improvement):
- Agent uses the wrong tool repeatedly for the same task type
- Agent passes incorrect parameter types or formats
- Agent ignores the tool and tries to accomplish the task through other means
- Agent calls the tool multiple times with slightly varied parameters (guessing)
- Agent misinterprets the output
Best Practices
- Write descriptions first, implement second: If you cannot write a clear description, the tool's scope is unclear
- Use the agent's vocabulary: Description language should match how agents naturally phrase tasks
- Test with naive prompts: If a user says "find that function", which tool does the agent pick?
- Version your schemas: Tool changes can break agent workflows; version schemas for backward compatibility
- Log tool usage patterns: Monitor which tools agents select to identify confusion
- Document negative cases: "Do NOT use this tool when..." is as important as "Use this tool when..."
Common Patterns
Pattern 1: MCP Server Tool Design
Situation: Building a new MCP server with multiple capabilities.
Solution:
- List all capabilities the server will provide
- Apply the consolidation principle (merge overlapping capabilities)
- Write descriptions for each tool following the 4-question template
- Implement with structured JSON output and recovery-oriented errors
- Test with agent interactions before deploying
Pattern 2: Claude Code Slash Command Design
Situation: Creating a custom slash command for a team workflow.
Solution:
- Define the single task the command accomplishes
- Write the description with trigger phrases
- Keep parameters minimal (commands should be zero-config where possible)
- Include clear examples in the command file
- Test by invoking the command with various phrasings
Pattern 3: Multi-Tool Consolidation
Situation: An existing tool set has too many overlapping tools causing agent confusion.
Solution:
- Audit current tool usage (which tools are picked for which tasks)
- Identify confusion pairs (tools the agent mixes up)
- Merge confused pairs into a single tool with a mode parameter
- Update descriptions to clearly delineate remaining tools
- Re-test with the same task prompts
Quality Checklist
- Each tool has a clear, specific description answering all 4 questions
- Total active tool count is within 10-20 range
- Parameter names are descriptive and self-documenting
- Error messages include recovery suggestions
- No two tools have overlapping use cases without clear differentiation
- Tools tested with actual agent interactions
- Negative cases documented ("Do NOT use when...")
Related Skills
create-custom-command- Creating Claude Code slash commandsapi-documentation- Documenting API interfacescontext-manager- Managing tool output impact on context budget
Version: 1.0.0 Last Updated: February 2026 Author: DevAI-Hub Attribution: Adapted from Agent-Skills-for-Context-Engineering (MIT License)
Iterative Refinement Strategy
This skill is optimized for an iterative approach:
- Execute: Perform the core steps defined above.
- Review: Critically analyze the output (coverage, quality, completeness).
- Refine: If targets aren't met, repeat the specific implementation steps with improved context.
- Loop: Continue until the definition of done is satisfied.