search_ads_by_names

Search for ads by name in the Metadata platform library, with pagination.

                   **USE THIS TOOL WHEN THE USER ASKS ABOUT:**
                   - Ad details, information, or status
                   - Finding an ad by name
                   - Getting ad IDs
                   - Checking if an ad exists
                   - Looking up ad creative assets (images, thumbnails)
                   - Ad type or channel information
                   - Any question containing words like: "ad", "creative", "show me", "find", "search", "image"

                   SEARCH FEATURES:
                   - Partial, case-insensitive matching on ad names
                   - Returns ad ID, name, channel type, ad type, status, and image URLs
                   - Three-state status filter via the `status` param (default
                     `"active"`, preserves the prior active-only behaviour):
                       * `"active"`   → active ads only
                       * `"archived"` → archived (soft-deleted) ads only; use
                                        this to find an ad id for `unarchive_ad`
                       * `"all"`      → both active and archived in one response

                   PAGINATION:
                   - Supports `page` and `size` parameters (defaults: page=0, size=25).
                   - Page numbering starts at 0.
                   - Recommended size: 5-25 to keep responses LLM-friendly. Use up
                     to 100 only when the caller needs a wider sweep — large pages
                     can blow your context budget.
                   - Returned `total_elements` and `total_pages` are taken from the
                     platform's PageResponse so callers can drive a paginator.
                   - When `ad_names` carries multiple entries, the platform endpoint
                     accepts only ONE name per request — this tool fires one paged
                     request per name and merges results. `page`/`size` apply
                     PER-NAME, `total_elements` is the SUM across names, and
                     `total_pages` is the MAX across names. Single-name searches
                     get clean pagination semantics; multi-name is best-effort.

                   PARAMETERS:
                   - ad_names: Array of ad name strings to search for (required, ≥1)
                   - page:     Zero-based page index (optional, default 0)
                   - size:     Results per page (optional, default 25)
                   - sort:     Spring sort clause (optional, default "createdDate,desc";
                               also valid: "id,desc", "name,asc", etc.)
                   - status:   "active" (default) / "archived" / "all". Pick the
                               bucket you want; "archived" is the unarchive
                               discovery path, "all" is the rare both-buckets case.

                   RETURNS:
                   {
                       "found_ads": [
                           {
                               "id": 190084,
                               "name": "AI_Marketing_Audit_Q4_2025_Demo_LI_LI",
                               "channelType": "LINKEDIN",
                               "adType": "IMAGE",
                               "completionStatus": "COMPLETED",
                               "status": true,
                               "thumbnail": "https://...",
                               "imageUrl": "https://..."
                           }
                       ],
                       "missing_names": ["NonExistent"],
                       "total_found": 1,
                       "page": 0,
                       "size": 25,
                       "sort": "createdDate,desc",
                       "total_elements": 1,
                       "total_pages": 1
                   }

                   CHANNEL TYPES: LINKEDIN, FACEBOOK, INSTAGRAM, GOOGLE, REDDIT, MICROSOFT_ADS
                   AD TYPES: IMAGE, VIDEO, CAROUSEL, TEXT
                   STATUS: true (active) or false (inactive)