Scope Declaration

# Scope Declaration

Declare required OAuth scopes per tool.

## Category
Tool Security

## Context
Tools using OAuth-authenticated APIs.

## Problem
Tools may fail due to missing scopes, with unclear errors.

## Solution
Declare scopes upfront:
- **Required scopes**: Minimum for function
- **Optional scopes**: For enhanced features
- **Pre-check**: Validate before execution
- **Clear errors**: Missing scope message

## Example (Python)
```python
@tool(
    requires_scopes=["gmail.send"],
    optional_scopes=["gmail.compose"]  # For drafts
)
def send_email(
    context: Context,
    recipient: str,
    subject: str,
    body: str
) -> SendResult:
    """Send an email via Gmail.
    
    Required scopes: gmail.send
    Optional scopes: gmail.compose (for draft functionality)
    """
    if not context.has_scope("gmail.send"):
        raise ScopeMissing(
            scope="gmail.send",
            instruction="Re-authenticate with Gmail send permission"
        )
    return gmail_api.send(recipient, subject, body)
```

## Considerations
- Document required scopes in tool description
- Check scopes before making API calls
- Request minimum necessary scopes

## Related Patterns
- permission-gate
- secret-injection
- identity-anchor

---
Source: https://arcade.dev/patterns/scope-declaration