Natural Identifier | Patterns for Agentic Tools

arcade.dev/patterns

Context

Designing parameters that reference entities.

Problem

Requiring system IDs (UUIDs) forces agents to make extra lookup calls.

Solution

Accept natural identifiers:
- Email: john@example.com
- Username: @johndoe
- Display name: "John Doe"
- Resolve internally: Map to system ID
- Handle ambiguity: Return matches if unclear

Examples

Python

@tool
def send_message(
    recipient: str,  # email, username, or display name
    message: str
) -> SendResult:
    """Send message to a user.
    
    Args:
        recipient: User's email, @username, or name.
                  Will be resolved automatically.
    """
    user_id = resolve_user(recipient)  # Internal resolution
    if not user_id:
        return suggest_matches(recipient)
    return _send(user_id, message)

Considerations

Document which natural identifiers are accepted
Return suggestions when resolution is ambiguous
Cache resolution results for performance, always minding for terms of service and data privacy policies.

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

# Natural Identifier

Accept human-friendly identifiers and resolve them internally.

## Category
Tool Interface

## Context
Designing parameters that reference entities.

## Problem
Requiring system IDs (UUIDs) forces agents to make extra lookup calls.

## Solution
Accept natural identifiers:
- **Email**: john@example.com
- **Username**: @johndoe
- **Display name**: "John Doe"
- **Resolve internally**: Map to system ID
- **Handle ambiguity**: Return matches if unclear

## Example (Python)
```python
@tool
def send_message(
    recipient: str,  # email, username, or display name
    message: str
) -> SendResult:
    """Send message to a user.
    
    Args:
        recipient: User's email, @username, or name.
                  Will be resolved automatically.
    """
    user_id = resolve_user(recipient)  # Internal resolution
    if not user_id:
        return suggest_matches(recipient)
    return _send(user_id, message)
```

## Considerations
- Document which natural identifiers are accepted
- Return suggestions when resolution is ambiguous
- Cache resolution results for performance, always minding for terms of service and data privacy policies.

## Related Patterns
- fuzzy-match-threshold
- confirmation-request
- recovery-guide

---
Source: https://arcade.dev/patterns/natural-identifier