Mutual Exclusivity | Patterns for Agentic Tools

arcade.dev/patterns

Context

Tools where multiple input paths exist.

Problem

Agents may provide conflicting parameters, leading to undefined behavior.

Solution

Make constraints explicit:
- Document: "Provide exactly one of..."
- Validate early: Check before processing
- Clear error: Explain what went wrong
- Examples: Show valid combinations

Examples

Python

@tool
def get_conversation(
    conversation_id: str | None = None,
    channel_name: str | None = None,
    user_emails: list[str] | None = None
) -> Conversation:
    """Get a conversation.
    
    Provide exactly ONE of:
    - conversation_id: Direct lookup
    - channel_name: Find by channel
    - user_emails: Find DM with users
    """
    provided = sum(1 for x in [conversation_id, channel_name, user_emails] if x)
    if provided != 1:
        raise ToolError("Provide exactly one identifier type")

Considerations

List all valid combinations in description
Validate at the start of execution
Return clear error with valid options

Related Patterns

More in Tool Interface

Tool Description

Write descriptions optimized for LLM comprehension, not human reading.

Constrained Input

Use enums, ranges, and validation to limit inputs to valid values.

Smart Defaults

Reduce required parameters by providing sensible defaults.

LLM-Optimized View

# Mutual Exclusivity

Enforce 'exactly one of X or Y' parameter constraints.

## Category
Tool Interface

## Context
Tools where multiple input paths exist.

## Problem
Agents may provide conflicting parameters, leading to undefined behavior.

## Solution
Make constraints explicit:
- **Document**: "Provide exactly one of..."
- **Validate early**: Check before processing
- **Clear error**: Explain what went wrong
- **Examples**: Show valid combinations

## Example (Python)
```python
@tool
def get_conversation(
    conversation_id: str | None = None,
    channel_name: str | None = None,
    user_emails: list[str] | None = None
) -> Conversation:
    """Get a conversation.
    
    Provide exactly ONE of:
    - conversation_id: Direct lookup
    - channel_name: Find by channel
    - user_emails: Find DM with users
    """
    provided = sum(1 for x in [conversation_id, channel_name, user_emails] if x)
    if provided != 1:
        raise ToolError("Provide exactly one identifier type")
```

## Considerations
- List all valid combinations in description
- Validate at the start of execution
- Return clear error with valid options

## Related Patterns
- constrained-input
- recovery-guide
- tool-description

---
Source: https://arcade.dev/patterns/mutual-exclusivity