Performance Hint | Patterns for Agentic Tools

arcade.dev/patterns

Context

Tools with multiple parameter options that have different costs.

Problem

Agents don't know which approach is faster or cheaper.

Solution

Include performance guidance:
- Prefer X: "conversation_id is faster than channel_name"
- Use Y for batch: "For multiple items, use batch_get"
- Warn about cost: "Large exports may take minutes"

Examples

Python

@tool
def get_messages(
    conversation_id: str | None = None,
    channel_name: str | None = None  # Note in docs
) -> list[Message]:
    """Get messages from a conversation.
    
    Args:
        conversation_id: Direct ID (faster, preferred)
        channel_name: Channel name (requires lookup)
    
    Performance: Prefer conversation_id when available.
    """

Considerations

Be specific about why one approach is better
Include performance notes in tool description
Consider separate tools for bulk vs single operations
When tool evaluation shows LLM adherence to the performance hint is flaky, consider applying prompt engineering techniques in the tool description

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

# Performance Hint

Guide agents toward efficient usage patterns.

## Category
Tool Interface

## Context
Tools with multiple parameter options that have different costs.

## Problem
Agents don't know which approach is faster or cheaper.

## Solution
Include performance guidance:
- **Prefer X**: "conversation_id is faster than channel_name"
- **Use Y for batch**: "For multiple items, use batch_get"
- **Warn about cost**: "Large exports may take minutes"

## Example (Python)
```python
@tool
def get_messages(
    conversation_id: str | None = None,
    channel_name: str | None = None  # Note in docs
) -> list[Message]:
    """Get messages from a conversation.
    
    Args:
        conversation_id: Direct ID (faster, preferred)
        channel_name: Channel name (requires lookup)
    
    Performance: Prefer conversation_id when available.
    """
```

## Considerations
- Be specific about why one approach is better
- Include performance notes in tool description
- Consider separate tools for bulk vs single operations
- When tool evaluation shows LLM adherence to the performance hint is flaky, consider applying prompt engineering techniques in the tool description

## Related Patterns
- tool-description
- batch-operation
- abstraction-ladder

---
Source: https://arcade.dev/patterns/performance-hint