Parameter Coercion | Patterns for Agentic Tools

arcade.dev/patterns

Context

Handling varied input formats.

Problem

Strict input requirements cause failures when agents provide valid but differently-formatted data.

Solution

Coerce inputs to canonical form:
- Dates: Accept ISO, relative ("yesterday"), natural
- Numbers: Accept string or numeric
- Lists: Accept single item or array
- Case: Normalize case for strings

Examples

Python

@tool
def search_events(
    start_date: str,  # Accepts multiple formats
    end_date: str | None = None
) -> list[Event]:
    """Search calendar events.
    
    Args:
        start_date: ISO date, relative ("today", "yesterday"),
                   or natural ("last Monday")
        end_date: Optional end date in same formats
    """
    start = parse_flexible_date(start_date)  # Internal normalization
    end = parse_flexible_date(end_date) if end_date else None

Considerations

Document all accepted formats
Normalize early, use canonical form internally
Log what format was received for debugging

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

# Parameter Coercion

Accept flexible input formats and normalize internally.

## Category
Tool Interface

## Context
Handling varied input formats.

## Problem
Strict input requirements cause failures when agents provide valid but differently-formatted data.

## Solution
Coerce inputs to canonical form:
- **Dates**: Accept ISO, relative ("yesterday"), natural
- **Numbers**: Accept string or numeric
- **Lists**: Accept single item or array
- **Case**: Normalize case for strings

## Example (Python)
```python
@tool
def search_events(
    start_date: str,  # Accepts multiple formats
    end_date: str | None = None
) -> list[Event]:
    """Search calendar events.
    
    Args:
        start_date: ISO date, relative ("today", "yesterday"),
                   or natural ("last Monday")
        end_date: Optional end date in same formats
    """
    start = parse_flexible_date(start_date)  # Internal normalization
    end = parse_flexible_date(end_date) if end_date else None
```

## Considerations
- Document all accepted formats
- Normalize early, use canonical form internally
- Log what format was received for debugging

## Related Patterns
- natural-identifier
- constrained-input
- tool-description

---
Source: https://arcade.dev/patterns/parameter-coercion