Response Shaper

# Response Shaper

Transform raw API responses into agent-friendly formats.

## Category
Tool Output

## Context
Returning data from external APIs.

## Problem
Raw API responses are often verbose, nested, or contain irrelevant data.

## Solution
Shape responses for agents:
- **Flatten**: Reduce nesting depth
- **Select**: Include only relevant fields
- **Rename**: Use meaningful field names
- **Summarize**: Add computed fields,
- **Convert**: Return human-friendly data types (e.g. UNIX timestamps vs. ISO datetimes)

## Example (Python)
```python
@tool
def get_user_summary(user_id: str) -> UserSummary:
    """Get user summary (shaped response).
    
    Returns a flattened, relevant subset of user data
    instead of the full raw API response.
    """
    raw = api.get_user(user_id)
    return UserSummary(
        id=raw["id"],
        name=f"{raw['first_name']} {raw['last_name']}",
        email=raw["contact"]["email"],
        role=raw["permissions"]["role"],
        active=raw["status"] == "active"
    )
```

## Considerations
- Keep what agents need, remove what they don't
- Flatten deeply nested structures
- Consider different shapes for different use cases

## Related Patterns
- token-efficient-response
- progressive-detail
- tool

---
Source: https://arcade.dev/patterns/response-shaper