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

2.0 KiB Raw Blame History