[Feature Request]: Add Pagination Metadata (Breaking)

[carlosmmatos]

Summary

Wrap search tool responses with pagination metadata to help AI agents understand result set state and efficiently retrieve complete data.

Problem

Current search tools return raw result lists without pagination context:

• AI agents don't know if more results exist
• No indication of total count or current position
• Difficult to implement efficient pagination workflows
• Agents may miss data or make unnecessary API calls

Proposed Solution

Wrap search responses with pagination metadata:

{
    "data": [...],  # Actual results
    "pagination": {
        "returned_count": 50,
        "limit": 50,
        "offset": 0,
        "has_more": true,
        "next_offset": 50,
        "total_count": 1523  # If available from API
    }
}

Metadata Fields

Field	Description
returned_count	Number of items in current response
limit	Requested limit
offset	Starting position
has_more	Boolean indicating more results available
next_offset	Suggested offset for next page (if has_more)
total_count	Total matching items (if API provides)

Breaking Change Notice

⚠️ This is a breaking change - return type changes from List[Dict] to Dict[str, Any].

Clients must access results via response["data"] instead of response directly.

Migration Path:

• v0.x: Current behavior (List returns)
• v1.0: New behavior with pagination metadata

Files Affected

• falcon_mcp/common/utils.py - Add add_pagination_metadata() function
• All search tools across 11 modules - Apply pagination wrapper

Acceptance Criteria

• add_pagination_metadata() utility function created
• All search tools return pagination-wrapped responses
• has_more correctly indicates if additional pages exist
• next_offset calculated correctly
• total_count included when API provides it
• Unit tests for pagination metadata
• Breaking change documented in CHANGELOG
• Migration guide provided