1086 Tool Design 91d38658

# 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:
1. **What** does the tool do?
2. **When** should it be used?
3. **What inputs** does it accept?
4. **What** does it return?

### Good Example

```json
{
  "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

```json
{"name": "search", "description": "Search for things", "parameters": {"q": {}}}
```

## Error Messages

```python
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:

```python
def get_data(id, format="concise"):
    if format == "concise":
        return {"name": data.name}
    return data.full()  # Detailed
```

## Guidelines

1. Consolidate tools (target 10-20)
2. Answer all four questions
3. Use full parameter names
4. Design errors for recovery
5. Offer concise/detailed formats
6. Test with agents before deploy
7. Start minimal, add when proven

## Related

- [Context Fundamentals](./context-fundamentals.md)
- [Multi-Agent Patterns](./multi-agent-patterns.md)