Paginated Result

# Paginated Result

Handle large result sets with cursor-based pagination.

## Category
Tool Output

## Context
Queries that may return many results.

## Problem
Returning thousands of results exhausts context windows and is slow.

## Solution
Implement pagination:
- **Cursor-based**: Use opaque cursor, not page numbers
- **Has-more flag**: Indicate if more results exist
- **Consistent order**: Same query, same order
- **Next-page hint**: How to get more results

## Example (Python)
```python
@tool
def list_contacts(
    limit: int = 50,
    cursor: str | None = None
) -> ContactPage:
    """List contacts with pagination.
    
    To get more results, call again with the returned cursor.
    """
    contacts, next_cursor = db.contacts.paginate(
        limit=limit,
        after=cursor
    )
    return ContactPage(
        contacts=contacts,
        count=len(contacts),
        has_more=next_cursor is not None,
        next_cursor=next_cursor,
        next_action="Call list_contacts(cursor='{}') for more".format(next_cursor) if next_cursor else None
    )
```

## Considerations
- Use cursors, not page numbers (more robust)
- Include has_more flag explicitly
- Set sensible default and max page sizes

## Related Patterns
- token-efficient-response
- batch-operation

---
Source: https://arcade.dev/patterns/paginated-result