{"id":88398,"plugin_id":"plugin_asdk_app_6af1f260676881919b1d3e10ab081e23","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-10T00:10:10.858Z","digest":"abba2c01c914c4bf859129022c3db324bd8a49fda5550cc7f8a4eda88889120d","against":null,"payload":{"description":"Look up Realize targeting metadata, audiences, publishers, conversion rules, time zones, and CTA types. Use when the user asks \"what X is available\" or needs an opaque ID before going to the Realize UI. Read-only — no campaign or item state is changed.","included_files":[],"name":"discovery","skill_md_contents":"---\nname: discovery\ndescription: Look up Realize targeting metadata, audiences, publishers, conversion rules, time zones, and CTA types. Use when the user asks \"what X is available\" or needs an opaque ID before going to the Realize UI. Read-only — no campaign or item state is changed.\nallowed-tools: [\"Read\", \"Grep\", \"AskUserQuestion\"]\n---\n\n# Discovery\n\nResolve opaque IDs and enumerate the catalogs that Realize's targeting / audience / publisher / conversion settings draw from. This skill wraps the nine read-only \"look it up\" tools the MCP exposes, so the user does not have to guess country codes, audience IDs, publisher IDs, segment IDs, conversion-rule IDs, CTA enum values, or IANA time zone names.\n\n## When to use\n\nTrigger on any of:\n\n- \"What countries / regions / DMAs / cities / postal codes can I target?\"\n- \"What operating systems / browsers does Realize support?\"\n- \"What audiences / lookalike audiences / contextual segments are available on account X?\"\n- \"List publishers on account X\" / \"Find publishers matching <name>\"\n- \"What conversion rules are configured on account X?\"\n- \"What time zones does Realize support?\"\n- \"What CTA button types are available for native items?\"\n- Any campaign-creation walkthrough where the user needs to paste an opaque ID rather than a display name.\n\nFor pulling **performance numbers**, route to the `reports` skill instead. For campaign/item lookup, route to the `campaigns` skill.\n\n## Prerequisites\n\n- `account_id` resolved via the `accounts` skill is required for every tool below **except** `search_geos`, `search_techno`, `list_time_zones`, and `list_cta_types` (those are global catalogs).\n\n## Tools this skill wraps\n\n| Tool | Required params | Optional params | Returns |\n|---|---|---|---|\n| `mcp__realize-mcp__search_geos` | `dimension` ∈ {`countries`, `regions`, `dma`, `cities`, `postal_codes`} | `country_code` (ISO-2 — **required** when `dimension` ≠ `countries`) | `{dimension, values: [{code, name}, ...]}` |\n| `mcp__realize-mcp__search_techno` | `dimension` ∈ {`operating_system_versions`, `browsers`} | `os_family` (**required** when `dimension=operating_system_versions`) | `{dimension, values: [...]}` |\n| `mcp__realize-mcp__search_audiences` | `account_id` | `country_codes` (comma-separated ISO-2), `country_targeting_type` ∈ {`ALL`, `INCLUDE`, `EXCLUDE`} | Audience list with `audience_id`, `name`, ... |\n| `mcp__realize-mcp__search_lookalike_audiences` | `account_id` | `country_code` (ISO-2) | Lookalike rules with `rule_id`, ... |\n| `mcp__realize-mcp__search_contextual_segments` | `account_id` | `country_codes`, `country_targeting_type` | Segments with `segment_id`, ... |\n| `mcp__realize-mcp__search_publishers` | `account_id`, `query` (use `\"*\"` for all) | `publisher_ids` (array of int), `page` (default 1), `page_size` (max **50**, default 10) | Paginated publisher list `{id, name, account_id, country, is_active}` |\n| `mcp__realize-mcp__get_conversion_rules` | `account_id` | `rule_id` (numeric id **as a string**, narrows to one rule), `page` (default 1), `page_size` (default 25, max **50**), `status` (`ACTIVE`/`DISABLED`/`ARCHIVED`), `search_text` (substring of `display_name`) | `{account_id, values: [...]}` — each rule in full, with `condition` and `effects`. **Paginated**, ordered by rule id; the response states the true `total`. `page`/`page_size` are ignored when `rule_id` is set. |\n| `mcp__realize-mcp__list_time_zones` | — | — | Array of IANA time zone names (e.g., `America/New_York`) |\n| `mcp__realize-mcp__list_cta_types` | — | — | Array of valid `cta_type` enum values |\n\n## Examples\n\n- *\"What DMAs are available in the US?\"* → `search_geos(dimension=\"dma\", country_code=\"US\")`.\n- *\"List regions in Brazil.\"* → `search_geos(dimension=\"regions\", country_code=\"BR\")`.\n- *\"All Windows OS versions I can target?\"* → `search_techno(dimension=\"operating_system_versions\", os_family=\"Windows\")`.\n- *\"Audiences on account advertiser_12345_prod for US/CA, include-mode.\"* → `search_audiences(account_id=\"advertiser_12345_prod\", country_codes=\"US,CA\", country_targeting_type=\"INCLUDE\")`.\n- *\"Lookalike audiences for account X in Canada.\"* → `search_lookalike_audiences(account_id=\"...\", country_code=\"CA\")`.\n- *\"Contextual segments for account X.\"* → `search_contextual_segments(account_id=\"...\")`.\n- *\"Publishers matching 'news' on account X.\"* → `search_publishers(account_id=\"...\", query=\"news\")`.\n- *\"All publishers on account X.\"* → `search_publishers(account_id=\"...\", query=\"*\")`. Paginate if needed — `page_size` is hard-capped at 50.\n- *\"Conversion rules on account X.\"* → `get_conversion_rules(account_id=\"...\")`.\n- *\"Show me conversion rule 3312.\"* → `get_conversion_rules(account_id=\"...\", rule_id=\"3312\")`.\n- *\"What time zones does Realize accept?\"* → `list_time_zones()`.\n- *\"What CTA button types exist?\"* → `list_cta_types()`.\n\n## Workflow\n\n1. **Resolve `account_id` first** (if the tool requires it) via the `accounts` skill — see the [`accounts`](../accounts/SKILL.md) skill.\n2. **Pick the narrowest tool** for the question. Don't pull all publishers when the user named one.\n3. **Honor the dimension prerequisites:**\n   - `search_geos` with `dimension` in {`regions`, `dma`, `cities`, `postal_codes`} requires `country_code` — ask the user for it before calling, or default to the user's stated geo if obvious.\n   - `search_techno` with `dimension=operating_system_versions` requires `os_family` (e.g., `Windows`, `iOS`, `Android`, `macOS`).\n4. **Summarize in prose, not raw JSON.** Pick the 3–5 most relevant rows, surface IDs alongside display names so the user can paste them downstream. If the list is long, offer to filter or paginate.\n   - **Conversion rules: ACTIVE by default, disclosed.** When listing or resolving conversion rules, work with `status: \"ACTIVE\"` rules only and always add one short line with exact counts — e.g., *\"showing 102 active rules — 176 disabled/archived skipped, say if you want them\"*. Include DISABLED / ARCHIVED rules only when the user explicitly asks (\"show all\", \"include disabled\"). Never skip silently: the disclosure line is mandatory whenever anything was filtered out. This default is for user-facing listings only — when the read feeds a pre-write collision check in `manage-campaigns`, all statuses count. Word any oversized-response disclosure without file paths or tool names (the internals bans in `os/guardrails.md` still apply).\n5. **Hand off the ID downstream.** When the user is mid-flow in the `manage-campaigns` skill (collecting create/update inputs), return the opaque ID(s) verbatim so they can be slotted into the write payload before the preview-and-confirm step.\n\n## Gotchas\n\n- **`country_code` is ISO-2, uppercase.** `US`, not `USA` or `us`. The MCP will reject other forms.\n- **`search_publishers` `page_size` cap is 50**, not 100 — different from report tools. Default is 10.\n- **`query=\"*\"` lists all** publishers, but the result is still paginated — don't assume page 1 is the full set.\n- **Audience country filters are passthrough.** `country_codes` and `country_targeting_type` are forwarded to the upstream API; verify the result actually narrowed by checking the row count.\n- **Catalogs change.** Time zones and CTA types are versioned upstream — don't cache them across sessions; re-pull when starting a new campaign-creation flow.\n- **`search_conversion_rules` is deprecated.** It was renamed to `get_conversion_rules`, and the old name is removed after **2026-11-01**. Behavior is identical and the old name also accepts `rule_id` now, but use `get_conversion_rules` everywhere.\n- **`get_conversion_rules` returns ACTION rules only.** Pixel *audience* rules are not in the response, so an empty result doesn't mean the account has no pixel activity.\n- **Narrow the read before you make it — rule-heavy accounts are the norm, not the exception.** The listing is paginated (`page` / `page_size`, default 25, **max 50**) and ordered by rule id, so pages are stable. The response states the true `total`: check it before assuming you have seen every rule. Prefer narrowing over paging — `status=\"ACTIVE\"` for a user-facing listing, `search_text` to find a rule by name (it matches `display_name` **only**, not `description` or `event_name`), `rule_id` when you already know the id (paging doesn't apply then). A rule-heavy / NETWORK account was observed at **278 rules / ~270 KB, only 102 ACTIVE** — that is 6 pages unfiltered at `page_size=50`, or 3 filtered to ACTIVE. **Filtering reduces the paging; it does not remove it.** Always read the response's `total` and keep paging until you hold that many rows.\n- **`status` does not partition the account.** `ARCHIVED` selects archived-*and*-disabled rules only, so an account can hold rules the listing labels `ARCHIVED` that the filter omits, and the three filtered counts need not sum to the unfiltered `total`. **Omit `status` whenever you need genuinely every rule** — in particular for the pre-write `display_name` collision check, which must run across all statuses. Never reconstruct \"all rules\" by calling the three statuses and concatenating.\n- **If a page still overflows the tool-result cap**, the call returns an error plus a **path to a dumped result file** rather than inline rules. Lower `page_size` and retry — that is the fix now that paging exists. If you do work from the dumped file, read it in slices (or search it with the `Grep` tool), build a slim projection per rule (`id`, `display_name`, `event_name`, `status`, `advertiser_id`), and state what was read. Never re-call unmodified at the same `page_size`, and never present a partial read as the account's full rule set.\n- **The account you query is often not the account that owns the rules.** Each rule's `advertiser_id` names its owner, and it runs both directions: a parent / NETWORK account returns its children's rules, **and a child account returns the network's rules**. Observed on a real account — querying a child returned 62 rules, all 62 owned by the parent network and none by the account queried. Always report ownership rather than presenting everything as \"this account's rules\", and check `advertiser_id` before handing an ID downstream to a write.\n- **Not everything readable here is writable.** The response includes `type: \"ENGAGEMENT\"` rules with `SESSION_DEPTH` / `TIME_ON_SITE` conditions; the create and update tools accept neither (`type` is `BASIC` / `EVENT_BASED` only). Surface them when listing, but route edit requests for them to the Realize UI.\n- **The read payload is not a valid update payload.** If the user wants a rule changed, hand off to `manage-campaigns` with the rule ID and the intended edits, not the object you just read.\n- **Pass IDs verbatim downstream — and respect their underlying type.** `account_id`, `campaign_id`, `item_id`, and publisher `id` are **opaque strings** returned by the API; do not coerce to int. `audience_id`, `segment_id`, and lookalike `rule_id` are **integers** — pass them as numbers, not stringified. Conversion-rule ids split by context: **integer** inside payloads that reference a rule (`conversion_rules.rules: [{id}]` on campaign writes), but the `rule_id` *parameter* on `get_conversion_rules` / `update_conversion_rule` takes that same id **as a string**. In all cases, do not strip or re-case the value returned by the search / list tool.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}