tools-only Tool Design
Design effective tools for agent systems.
Consolidation Principle
Single comprehensive tools > multiple narrow tools. Target: 10-20 tools max.
Architectural Reduction Evidence
| Metric | 17 Tools | 2 Tools | Improvement |
|---|---|---|---|
| Time | 274.8s | 77.4s | 3.5x faster |
| Success | 80% | 100% | +20% |
| Tokens | 102k | 61k | 37% fewer |
Key: Good documentation replaces tool sophistication.
When Reduction Works
Prerequisites: High docs quality, capable model, navigable problem Avoid when: Messy systems, specialized domain, safety-critical
Description Engineering
Answer four questions:
- What does the tool do?
- When should it be used?
- What inputs does it accept?
- What does it return?
Good Example
{
"name": "get_customer",
"description": "Retrieve customer profile by ID. Use for order processing, support. Returns 404 if not found.",
"parameters": {
"customer_id": {"type": "string", "pattern": "^CUST-[0-9]{6}$"},
"format": {"enum": ["concise", "detailed"]}
}
}
Poor Example
{"name": "search", "description": "Search for things", "parameters": {"q": {}}}
Error Messages
def format_error(code, message, resolution):
return {
"error": {"code": code, "message": message,
"resolution": resolution, "retryable": code in RETRYABLE}
}
# "Use YYYY-MM-DD format, e.g., '2024-01-05'"
Response Formats
Offer concise vs detailed:
def get_data(id, format="concise"):
if format == "concise":
return {"name": data.name}
return data.full() # Detailed
Guidelines
- Consolidate tools (target 10-20)
- Answer all four questions
- Use full parameter names
- Design errors for recovery
- Offer concise/detailed formats
- Test with agents before deploy
- Start minimal, add when proven