Abstraction Ladder | Patterns for Agentic Tools

arcade.dev/patterns

Context

Capabilities that need both fine-grained and coarse-grained access.

Problem

One-size-fits-all tools are either too limiting or too complex.

Solution

Offer multiple abstraction levels:
- Low-level: create_file(path, content)
- Mid-level: create_document(title, format, content)
- High-level: draft_report(topic) - handles everything

Examples

Python

# Low-level: Full control
@tool
def execute_query(sql: str) -> QueryResult:
    """Execute raw SQL query."""

# Mid-level: Structured
@tool  
def search_records(table: str, filters: dict) -> list[Record]:
    """Search with structured filters."""

# High-level: Intent-based
@tool
def find_customers_like(description: str) -> list[Customer]:
    """Find customers matching natural language description."""

Considerations

Each level should have clear use cases
Higher levels should use lower levels internally
Document when to use which level

Related Patterns

More in Tool Composition

Task Bundle

Combine multiple operations into a single tool.

Batch Operation

Process multiple items in a single tool call.

Operation Mode

Provide different modes for different access patterns.

LLM-Optimized View

# Abstraction Ladder

Provide tools at multiple levels of granularity for the same capability.

## Category
Tool Composition

## Context
Capabilities that need both fine-grained and coarse-grained access.

## Problem
One-size-fits-all tools are either too limiting or too complex.

## Solution
Offer multiple abstraction levels:
- **Low-level**: create_file(path, content)
- **Mid-level**: create_document(title, format, content)
- **High-level**: draft_report(topic) - handles everything

## Example (Python)
```python
# Low-level: Full control
@tool
def execute_query(sql: str) -> QueryResult:
    """Execute raw SQL query."""

# Mid-level: Structured
@tool  
def search_records(table: str, filters: dict) -> list[Record]:
    """Search with structured filters."""

# High-level: Intent-based
@tool
def find_customers_like(description: str) -> list[Customer]:
    """Find customers matching natural language description."""
```

## Considerations
- Each level should have clear use cases
- Higher levels should use lower levels internally
- Document when to use which level

## Related Patterns
- task-bundle
- operation-mode
- tool-description

---
Source: https://arcade.dev/patterns/abstraction-ladder