MCP tools
Search the reference library
Find the winning public image ads closest to a brand: ads that ran long for top advertisers, matched on what they sell and show.
Tool name: search-reference-library.
Find the winning public image ads closest to a brand: ads that ran long for top advertisers, matched on what they sell and show. Closest first, one per advertiser, fewer when few are close; the images are shown to you after this call. Read-only.
When to use
Pick references before making ad images: describe the brand in brief and read why each ad works. Borrow layout and craft only: never copy another brand's name, logo, product or claims.
Access
| Property | Value |
|---|---|
| Required scope | read |
| Publishes | No |
| Read-only | Yes |
| Destructive | No |
| Idempotent | Yes |
| Open world | No |
Input
| Field | Type | Required | Description |
|---|---|---|---|
brief | string | No | What the brand sells, to whom, and how its ads should look, in a few sentences. The ads closest to it come back. Defaults to the brand's saved style guide. At most 1200 characters. |
format | string | No | The layout device the ad is built on. Only ads with this format come back. One of native_mockup, quiz_or_form, event_webinar, lead_magnet_mockup, before_after, comparison, problem_solution, advertorial, meme, note_or_letter, testimonial_quote, founder_expert, offer_banner, big_number, feature_callout, infographic, listicle, product_ui_screen, collection_grid, ugc_photo, text_statement, scene_photo, product_hero, other. |
excludeRiskFlags | string[] | No | Leave out ads carrying any of these policy risks. One of before_after_body, health_claim, income_claim, named_competitor, third_party_logos, government_lookalike, fake_ui_element, personal_attribute_callout, shock_imagery, money_imagery. At most 10 items. |
minTier | string | No | Lowest winner tier to include. Defaults to STRONG. One of TOP, STRONG, AVERAGE. |
limit | integer | No | Ads to return, 1-12. Defaults to 4. Fewer come back when few are close to the brief. Minimum 1, maximum 12. |
Output
| Field | Type | Required | Description |
|---|---|---|---|
ads | object[] | Yes | |
modelImages | object[] | No | Images shown to you after this call. At most 12 items. |
REST equivalent
GET /v1/brands/{brandId}/reference-library, Search the reference library. CLI: koast search-reference-library.