tool-design
Create custom tools using the @tool decorator for domain-specific agents. Use when building agent-specific tools, implementing MCP servers, or creating in-memory tools with the Agent SDK.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for designing and implementing custom, domain-specific tools using the @tool decorator and Agent SDK. It enables developers to extend agent capabilities through specialized operations, robust error handling, and Model Context Protocol (MCP) server integration, ensuring agents can perform complex, real-world tasks with precision and reliability.
Use Cases
- Case 1: Developing domain-specific agents that require specialized operations like financial modeling, risk assessment, or scientific calculations beyond standard toolsets.
- Case 2: Building secure and scalable MCP servers to provide agents with controlled, schema-validated access to internal databases and proprietary enterprise APIs.
- Case 3: Implementing robust input validation and standardized error handling patterns to ensure agent-tool interactions are resilient and secure in production environments.
- Case 4: Creating reusable tool libraries and modular interfaces that allow agents to seamlessly switch between different operational contexts and specialized capabilities.
| name | tool-design |
|---|---|
| description | Create custom tools using the @tool decorator for domain-specific agents. Use when building agent-specific tools, implementing MCP servers, or creating in-memory tools with the Agent SDK. |
| allowed-tools | Read, Grep, Glob |
Tool Design Skill
Create custom tools for domain-specific agents using the @tool decorator.
Purpose
Design and implement custom tools that give agents specialized capabilities for domain-specific operations.
When to Use
- Agent needs capabilities beyond default tools
- Domain requires specialized operations
- Building focused, efficient agents
- Creating reusable tool libraries
Prerequisites
- Understanding of @tool decorator syntax
- Knowledge of MCP server creation
- Clear definition of tool purpose
Design Process
Step 1: Define Tool Purpose
Answer:
- What operation does this tool perform?
- What inputs does it need?
- What output does it produce?
- When should the agent use this tool?
Step 2: Design Tool Interface
Tool Signature:
@tool(
"tool_name", # Unique identifier
"Description for agent", # How agent knows when to use
{"param1": type, "param2": type} # Parameter schema
)
async def tool_implementation(args: dict) -> dict:
pass
Naming Convention:
- Use snake_case for tool names
- Be descriptive:
calculate_compound_interestnotcalc - Prefix with domain:
db_query,api_call
Description Guidelines:
- Explain WHEN to use the tool
- Explain WHAT it does
- Include any constraints
Step 3: Define Parameters
Parameter Types:
{
"text_param": str, # String
"number_param": int, # Integer
"decimal_param": float, # Float
"flag_param": bool, # Boolean
}
Required vs Optional:
async def my_tool(args: dict) -> dict:
# Required - must exist
required = args["required_param"]
# Optional - with default
optional = args.get("optional_param", "default")
Step 4: Implement Tool Logic
Basic Template:
@tool(
"tool_name",
"Description",
{"param1": str, "param2": int}
)
async def tool_name(args: dict) -> dict:
try:
# 1. Extract and validate inputs
param1 = args["param1"]
param2 = args.get("param2", 10)
# 2. Perform operation
result = perform_operation(param1, param2)
# 3. Return success
return {
"content": [{"type": "text", "text": str(result)}]
}
except Exception as e:
# 4. Handle errors
return {
"content": [{"type": "text", "text": f"Error: {str(e)}"}],
"is_error": True
}
Step 5: Add Error Handling
Validation Pattern:
async def my_tool(args: dict) -> dict:
# Validate required params
if "required" not in args:
return error_response("Missing required parameter")
# Validate types
if not isinstance(args["required"], str):
return error_response("Parameter must be string")
# Validate values
if args.get("limit", 0) < 0:
return error_response("Limit cannot be negative")
# Security validation
if is_dangerous(args["input"]):
return error_response("Security: Operation blocked")
Error Response Helper:
def error_response(message: str) -> dict:
return {
"content": [{"type": "text", "text": message}],
"is_error": True
}
def success_response(result: str) -> dict:
return {
"content": [{"type": "text", "text": result}]
}
Step 6: Create MCP Server
from claude_agent_sdk import create_sdk_mcp_server
# Create server with tools
my_server = create_sdk_mcp_server(
name="my_domain",
version="1.0.0",
tools=[
tool_one,
tool_two,
tool_three,
]
)
Step 7: Configure Agent
options = ClaudeAgentOptions(
mcp_servers={"my_domain": my_server},
allowed_tools=[
"mcp__my_domain__tool_one",
"mcp__my_domain__tool_two",
"mcp__my_domain__tool_three",
],
# Disable unused default tools
disallowed_tools=["WebFetch", "WebSearch", "TodoWrite"],
system_prompt=system_prompt,
model="opus",
)
Tool Categories
Data Processing Tools
@tool("parse_json", "Parse JSON string", {"json_str": str})
@tool("transform_data", "Transform data format", {"data": str, "format": str})
@tool("validate_schema", "Validate against schema", {"data": str, "schema": str})
Domain Operation Tools
@tool("calculate_metric", "Calculate business metric", {"values": str, "metric": str})
@tool("lookup_reference", "Look up reference data", {"key": str})
@tool("process_record", "Process domain record", {"record": str})
Integration Tools
@tool("query_database", "Execute DB query", {"query": str})
@tool("call_api", "Call external API", {"endpoint": str, "method": str})
@tool("send_notification", "Send notification", {"channel": str, "message": str})
Output Format
When designing a tool:
## Tool Design
**Name:** [tool_name]
**Purpose:** [what it does]
**Domain:** [where it's used]
### Interface
@tool( "tool_name", "Description for agent usage", {"param1": str, "param2": int} )
### Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| param1 | str | Yes | [description] |
| param2 | int | No | [description], default: 10 |
### Return Format
**Success:**
{"content": [{"type": "text", "text": "[result format]"}]}
**Error:**
{"content": [{"type": "text", "text": "Error: [message]"}], "is_error": true}
### Implementation
[Full implementation code]
### Usage Example
Agent prompt: "[example prompt that uses tool]"
Tool call: tool_name(param1="value", param2=20)
Result: "[expected result]"
Design Checklist
- Tool name is descriptive
- Description explains when to use
- Parameter types are defined
- Required vs optional is clear
- Input validation is complete
- Error handling is robust
- Security checks are in place
- Return format is consistent
Critical: Client vs Query
Warning: Custom tools require
ClaudeSDKClient, notquery()
# WRONG
async for message in query(prompt, options=options):
pass
# CORRECT
async with ClaudeSDKClient(options=options) as client:
await client.query(prompt)
async for message in client.receive_response():
pass
Cross-References
- @custom-tool-patterns.md - Tool creation patterns
- @core-four-custom.md - Tools in Core Four
- @custom-agent-design skill - Agent design workflow
Version History
- v1.0.0 (2025-12-26): Initial release
Last Updated
Date: 2025-12-26 Model: claude-opus-4-5-20251101