Confirmation Request

# Confirmation Request

Request clarification when input is ambiguous.

## Category
Tool Resilience

## Context
Tools with natural identifier inputs that may be ambiguous.

## Problem
Multiple matches or unclear input leads to wrong actions.

## Solution
Request confirmation:
- **Return matches**: Show what was found
- **Ask for selection**: Clarify which one
- **Provide details**: Enough to distinguish
- **Allow retry**: With more specific input

## Example (Python)
```python
@tool
def update_contact(
    contact_name: str,
    **updates
) -> UpdateResult | ConfirmationRequest:
    """Update a contact by name.
    
    If multiple matches found, returns options for confirmation.
    """
    matches = search_contacts(contact_name)
    
    if len(matches) == 0:
        raise ToolError("No contacts found matching '{}'".format(contact_name))
    
    if len(matches) == 1:
        return do_update(matches[0].id, **updates)
    
    # Multiple matches - request confirmation
    return ConfirmationRequest(
        message=f"Found {len(matches)} contacts matching '{contact_name}'",
        options=[
            {"id": m.id, "name": m.full_name, "email": m.email}
            for m in matches[:5]
        ],
        instruction="Call update_contact with contact_id instead of name"
    )
```

## Considerations
- Limit options to a reasonable number (5-10)
- Include distinguishing details
- Provide the exact call to make for each option

## Related Patterns
- natural-identifier
- fuzzy-match-threshold
- recovery-guide

---
Source: https://arcade.dev/patterns/confirmation-request