Tool Versioning

# Tool Versioning

Support multiple tool versions coexisting.

## Category
Compositional

## Context
Evolving tools while maintaining backward compatibility.

## Problem
Changing tool signatures breaks existing integrations.

## Solution
Version tools explicitly:
- **Version in name**: tool_v2 or tool@2.0
- **Parallel support**: Old and new coexist
- **Deprecation path**: Mark old as deprecated
- **Migration guide**: How to update

## Example (Python)
```python
# Version 1: Original API
@tool(deprecated="Use create_user_v2 for better error handling")
def create_user(name: str, email: str) -> User:
    """Create a user. DEPRECATED: Use create_user_v2."""
    return _create_user_legacy(name, email)

# Version 2: Improved API
@tool
def create_user_v2(
    email: str,  # Required first (breaking change)
    name: str,
    team_id: str | None = None  # New optional param
) -> UserResult:
    """Create a user with team assignment.
    
    Improvements over v1:
    - Better error messages
    - Optional team assignment
    - Returns full UserResult
    """
    return _create_user_new(email, name, team_id)
```

## Considerations
- Support old versions during migration period
- Document breaking changes clearly
- Provide migration guidance

## Related Patterns
- tool-adapter
- tool-description
- tool-registry

---
Source: https://arcade.dev/patterns/tool-versioning