Canonical Tool Model

# Canonical Tool Model

Use standard data models across the tool ecosystem.

## Category
Compositional

## Context
Multiple tools that deal with similar entities.

## Problem
Different tools use different schemas for the same concepts.

## Solution
Define canonical models:
- **Standard schemas**: User, Task, Event, etc.
- **Mapping layer**: Transform to/from canonical
- **Consistent naming**: Same fields, same names
- **Documented**: Schema reference available

## Example (Python)
```python
# Canonical models used across all tools
class CanonicalUser(BaseModel):
    """Standard user model for all tools."""
    user_id: str
    email: str
    display_name: str
    role: str | None

# Each tool transforms to canonical
@tool
def get_slack_user(user_id: str) -> CanonicalUser:
    slack_user = slack_api.get_user(user_id)
    return CanonicalUser(
        user_id=slack_user["id"],
        email=slack_user["profile"]["email"],
        display_name=slack_user["real_name"],
        role=slack_user.get("title")
    )

@tool
def get_github_user(username: str) -> CanonicalUser:
    gh_user = github_api.get_user(username)
    return CanonicalUser(
        user_id=gh_user["login"],
        email=gh_user["email"],
        display_name=gh_user["name"],
        role=None
    )
```

## Considerations
- Start with common entities (User, Document, Task)
- Document the canonical schema
- Allow extension for domain-specific fields

## Related Patterns
- response-shaper
- tool-adapter
- parameter-coercion

---
Source: https://arcade.dev/patterns/canonical-tool-model