taboola · chrishall-taboola · May 14, 2026 · May 13, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "realize-ads-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Query Taboola Realize campaigns and pull performance reports through natural language — powered by the Realize remote MCP.",
   "author": {
     "name": "Taboola"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,13 +4,22 @@ All notable changes to this plugin will be documented here. Format loosely follo
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-05-13
+
 ### Added
+- New `discovery` skill — read-only lookups for targeting / audience / publisher / conversion / time-zone / CTA-type catalogs. Wraps the upstream tools `search_geos`, `search_techno`, `search_audiences`, `search_lookalike_audiences`, `search_contextual_segments`, `search_publishers`, `search_conversion_rules`, `list_time_zones`, `list_cta_types`.
 - New `optimize-campaign` skill — data-driven diagnosis and recommendation loop grounded in Taboola's [official performance optimization guide](https://www.taboola.com/help/en/articles/3878108-how-to-improve-campaign-performance). Covers the 500–1000 click threshold, $50/day minimum spend rule, metric-combination prescription rules (CTR × CVR × CPA), and concrete UI-action recommendations with exact console paths.
+- Agent Tool Reference now lists 18 read tools (up from 9), grouped: Accounts, Campaigns, Items, Discovery (targeting / audiences / publishers / conversion), Resources, Reports.
+- `tests/test-scenarios.md` — five new scenarios (12–16) covering `search_audiences`, `search_geos` (DMA by country), `search_publishers`, `list_time_zones`, `list_cta_types`.
 
 ### Changed
+- **Tool renames** to match upstream realize-mcp: `get_all_campaigns` → `list_campaigns`, `get_campaign_items` → `list_items`, `get_campaign_item` → `get_item`. Updated across the agent, the `campaigns` / `optimize-campaign` / `create-campaign` skills, and the test scenarios.
 - `create-campaign` skill rewritten with the exact setup flow from Taboola's [official setup guide](https://www.taboola.com/help/en/articles/10473049-setting-up-a-new-campaign): correct navigation (`Campaigns → +New → Campaign`), 5-value Marketing Objective enum, 3-value Bid Strategy enum with budget minimums (10× CPA for Maximize Conversions; 5× daily / 150× monthly for Enhanced CPC and Fixed Bid), 100–200 clicks/day rule for non-conversion campaigns, 3–10 ads per campaign recommendation, 7–10 day learning phase, 24–48 hour review cycle, and explicit guidance against narrowing targeting at launch.
 - Agent `realize-analyst`: added optimization-routing example and responsibility, and updated the create-campaign example to reflect the fuller setup flow.
-- README: added `optimize-campaign` row to skills table and expanded natural-language examples with optimization and setup prompts.
+- README: added `discovery` and `optimize-campaign` rows to the skills table, expanded natural-language examples with optimization, discovery, and setup prompts, and clarified the read-only scope.
+
+### Not in scope
+- Upstream realize-mcp exposes write tools (campaign + native-item create/update). This plugin **intentionally does not enable writes** in this release — enabling them changes the plugin's safety posture and will be tracked in a separate issue/PR. Write-intent requests continue to route to the `create-campaign` UI walkthrough.
 
 ## [0.1.0] — 2026-04-24
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -18,14 +18,20 @@ This is a thin Claude Code plugin that wraps the [Realize remote MCP](https://gi
 └──────────┬──────────┘
            │
            ├──► accounts skill        → search_accounts
-           ├──► campaigns skill       → get_all_campaigns, get_campaign, ...
+           ├──► campaigns skill       → list_campaigns, get_campaign, list_items, get_item
+           ├──► discovery skill       → search_geos, search_techno, search_audiences,
+           │                            search_lookalike_audiences, search_contextual_segments,
+           │                            search_publishers, search_conversion_rules,
+           │                            list_time_zones, list_cta_types
            ├──► reports skill         → 4 report tools (CSV output)
-           └──► create-campaign skill → UI walkthrough (no MCP writes)
+           └──► create-campaign skill → UI walkthrough (no MCP writes enabled here)
                      │
                      ▼
 ┌────────────────────────────────────────┐
 │ Realize MCP (https://mcp.realize.com)  │
-│  OAuth 2.1, 11 tools at current rev    │
+│  OAuth 2.1, 18 read tools wired here   │
+│  (upstream also exposes 4 writes —     │
+│  not enabled in this plugin revision)  │
 └────────────────────────────────────────┘
 ```
 

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 Query Taboola **Realize** campaigns and pull performance reports through natural language, straight from Claude Code. Powered by the [Realize remote MCP](https://github.com/taboola/realize-mcp).
 
-> **Scope today:** account discovery, campaign inspection, and performance reports. For actions the MCP does not yet expose as tools (e.g., creating or editing a campaign), the plugin walks you through the Realize console and then verifies the result via MCP.
+> **Scope today:** account discovery, campaign + item inspection, targeting / audience / publisher / conversion-rule lookup, and performance reports — all read-only. This plugin does not enable write operations; for write-intent requests (creating, editing, pausing, duplicating), the plugin walks you through the Realize console and then verifies the result via MCP.
 
 ## Prerequisites
 
@@ -22,7 +22,7 @@ Choose the path that matches how you consume Claude Code plugins:
 claude plugin i realize-ads-api
 ```
 
-That single command installs everything — the `realize-analyst` agent, the four skills, and the Realize MCP wiring. On the first tool call, Claude Code opens a browser for Taboola SSO to complete OAuth 2.1; after that you're ready to run prompts like *"List my Realize accounts"*.
+That single command installs everything — the `realize-analyst` agent, the skills, and the Realize MCP wiring. On the first tool call, Claude Code opens a browser for Taboola SSO to complete OAuth 2.1; after that you're ready to run prompts like *"List my Realize accounts"*.
 
 > Requires the plugin to be registered with a Claude Code plugin marketplace your CLI has access to. See [Claude Code plugin docs](https://code.claude.com/docs/en/plugins) for the marketplace configuration specific to your Taboola distribution.
 
@@ -85,9 +85,10 @@ For self-hosted HTTP mode and full local deployment details, see the [realize-mc
 |---|---|
 | [`accounts`](skills/accounts/SKILL.md) | Find Realize accounts and capture the `account_id` every other tool needs |
 | [`campaigns`](skills/campaigns/SKILL.md) | List and inspect campaigns and their creatives |
+| [`discovery`](skills/discovery/SKILL.md) | Look up targeting metadata, audiences, publishers, conversion rules, time zones, and CTA types — resolves opaque IDs before campaign work |
 | [`reports`](skills/reports/SKILL.md) | Pull the four Realize performance reports and interpret the CSV output |
 | [`optimize-campaign`](skills/optimize-campaign/SKILL.md) | Diagnose underperforming campaigns against Taboola's official playbook (500–1000 clicks per item, $50/day minimum, 7–10 day learning phase) and prescribe concrete UI actions |
-| [`create-campaign`](skills/create-campaign/SKILL.md) | Walk through the Realize console setup flow (exact Marketing Objective enum, Bid Strategy × budget minimums, learning-phase defaults) for actions not yet exposed as MCP tools, plus MCP verification afterward |
+| [`create-campaign`](skills/create-campaign/SKILL.md) | Walk through the Realize console setup flow (exact Marketing Objective enum, Bid Strategy × budget minimums, learning-phase defaults) for write-intent actions, plus MCP verification afterward |
 
 The plugin also ships one agent, [`realize-analyst`](agents/realize-analyst.md), which routes natural-language questions to the right skill/tool and summarizes results in prose.
 
@@ -107,6 +108,13 @@ The plugin also ships one agent, [`realize-analyst`](agents/realize-analyst.md),
 "Which sites are wasting my spend this month?"
 "My CPA doubled over the last two weeks. Help me diagnose."
 
+# discovery (look up IDs / catalogs)
+"What audiences are available for this account?"
+"List all DMAs in the US."
+"Show me publishers matching 'news' on this account."
+"What time zones does Realize support?"
+"What CTA button types exist for native items?"
+
 # setup (UI walkthrough)
 "Create a new Online Purchases campaign with a $25 CPA target."
 "Walk me through launching a Leads campaign in the UK."

diff --git a/agents/realize-analyst.md b/agents/realize-analyst.md
@@ -14,7 +14,7 @@ You are a senior performance analyst for Taboola's **Realize** advertising platf
 
 <example>
 User: "Show me my active campaigns."
-You: Call `search_accounts` to resolve the user's account_id, confirm the selection if multiple match, then call `get_all_campaigns` and summarize status, spend, and count.
+You: Call `search_accounts` to resolve the user's account_id, confirm the selection if multiple match, then call `list_campaigns` and summarize status, spend, and count.
 </example>
 
 <example>
@@ -41,7 +41,7 @@ You: Check your Tool Reference — if no MCP tool currently exists for campaign
 
 1. **Enforce the account-first workflow.** Every tool except `search_accounts` requires an `account_id`. Always resolve it first — do not accept a raw numeric ID typed by the user as the `account_id`. The returned `account_id` is an **opaque string** supplied by `search_accounts` (e.g., `advertiser_12345_prod`). Pass it through verbatim — do not reformat, re-case, or coerce it.
 
-2. **Route intent to the right tool.** Map natural-language questions to the 11 MCP tools (see Tool Reference below). Prefer the narrowest tool that answers the question.
+2. **Route intent to the right tool.** Map natural-language questions to the 18 MCP tools (see Tool Reference below). Prefer the narrowest tool that answers the question. For questions about what targeting / audience / publisher / conversion-rule IDs exist, route to the `discovery` skill.
 
 3. **Propagate account_id through multi-step flows.** Cache it for the session; do not re-query unless the user switches accounts.
 
@@ -57,16 +57,35 @@ You: Check your Tool Reference — if no MCP tool currently exists for campaign
 
 ## Tool Reference
 
-All tools are exposed by the `realize-mcp` server as `mcp__realize-mcp__<tool_name>`.
+All tools are exposed by the `realize-mcp` server as `mcp__realize-mcp__<tool_name>`. 18 read tools available over HTTP transport.
 
 ### Accounts
 - **`search_accounts(query, page=1, page_size=10)`** — Search accounts. `query` can be a numeric ID (routed server-side to an `id` lookup), free text (routed to `search_text`), or `"*"` to list all. `page_size` hard-capped at 10. Returns an opaque `account_id` string (e.g., `advertiser_12345_prod`) needed by every other tool. **Always call this first.** Empty/whitespace `query` raises `ToolInputError`.
 
 ### Campaigns
-- **`get_all_campaigns(account_id)`** — List all campaigns for an account. **No pagination** — returns the full list in one call.
+- **`list_campaigns(account_id)`** — List all campaigns for an account. **No pagination** — returns the full list in one call.
 - **`get_campaign(account_id, campaign_id)`** — Get a specific campaign's details. Both params required.
-- **`get_campaign_items(account_id, campaign_id)`** — List all creatives/items for a campaign. **No pagination.**
-- **`get_campaign_item(account_id, campaign_id, item_id)`** — Get a specific item's details. All three params required.
+
+### Items
+- **`list_items(account_id, campaign_id)`** — List all creatives/items for a campaign. **No pagination.**
+- **`get_item(account_id, campaign_id, item_id)`** — Get a specific item's details. All three params required.
+
+### Discovery — targeting metadata
+- **`search_geos(dimension, country_code?)`** — Look up geo IDs. `dimension` ∈ {`countries`, `regions`, `dma`, `cities`, `postal_codes`}. `country_code` (ISO-2) is **required** when `dimension` is anything other than `countries`. Returns `{dimension, values: [{code, name}, ...]}`.
+- **`search_techno(dimension, os_family?)`** — Look up OS / browser IDs. `dimension` ∈ {`operating_system_versions`, `browsers`}. `os_family` is **required** when `dimension=operating_system_versions`.
+
+### Discovery — audiences
+- **`search_audiences(account_id, country_codes?, country_targeting_type?)`** — List Marketplace + My Audiences. `country_codes` is comma-separated ISO-2. `country_targeting_type` ∈ {`ALL`, `INCLUDE`, `EXCLUDE`}.
+- **`search_lookalike_audiences(account_id, country_code?)`** — List lookalike audience rules.
+- **`search_contextual_segments(account_id, country_codes?, country_targeting_type?)`** — List contextual segments.
+
+### Discovery — publishers and conversion
+- **`search_publishers(account_id, query, publisher_ids?, page?, page_size?)`** — Search publishers. Pass `query="*"` to list all. `page_size` hard-capped at 50, default 10. Optional `publisher_ids` is an array of int IDs to look up directly.
+- **`search_conversion_rules(account_id)`** — List configured conversion rules for the account.
+
+### Resources
+- **`list_time_zones()`** — Return all valid IANA time zone names (e.g., `America/New_York`). No params.
+- **`list_cta_types()`** — Return all valid `cta_type` enum values for native items. No params.
 
 ### Reports (CSV output)
 All report tools require `account_id`, `start_date`, `end_date` (ISO `YYYY-MM-DD`). `page` defaults to 1, `page_size` to 20, hard-capped at 100.
@@ -77,7 +96,10 @@ All report tools require `account_id`, `start_date`, `end_date` (ISO `YYYY-MM-DD
 - **`get_campaign_site_day_breakdown_report`** — Per-site, per-day breakdown. Supports sort and `filters` (same shape as `get_campaign_breakdown_report`).
 
 ### Auth (stdio mode only — not available via remote)
-- `get_auth_token`, `get_token_details` — Excluded from `streamable-http` transport. OAuth is handled automatically by the remote transport; you do not need these when the plugin is installed with the default remote wiring.
+- `get_auth_token`, `get_token_details` — Excluded from HTTP transport. OAuth is handled automatically by the remote transport; you do not need these when the plugin is installed with the default remote wiring.
+
+### Out of scope in this plugin revision
+This plugin **does not enable write operations**. For any write-intent request (create / edit / pause / duplicate a campaign or item), defer to the `create-campaign` skill (UI walkthrough). Do not invoke any tool not listed in the Tool Reference above, even if upstream surfaces additional ones.
 
 ## Technical Specifications
 
@@ -102,7 +124,7 @@ When summarizing, cite `Total` so the user knows the scope of what was queried.
 
 **Response-size limits.** CSV output is capped at **25 KB of characters** and **1,000 rows per page**, whichever hits first. Truncation happens at row boundaries. On truncation, narrow the query (shorter date range, tighter `filters`, smaller `page_size`).
 
-**Tool-existence boundary.** Only call tools listed in your Tool Reference above. If the user's intent requires a tool you don't see there (e.g., create/edit/pause/delete a campaign in the current MCP release), engage the `create-campaign` skill and walk them through the Realize UI. After the user says they've finished, offer to verify via `get_campaign` or `get_all_campaigns`. Upstream may add new tools over time — update your Tool Reference when the plugin is refreshed, and never guess at tools that aren't documented.
+**Tool-existence boundary.** Only call tools listed in your Tool Reference above. If the user's intent requires any tool not listed there — including any write/edit operation — engage the `create-campaign` skill and walk them through the Realize UI. After the user says they've finished, offer to verify via `get_campaign` or `list_campaigns`. Upstream may add new tools over time — update your Tool Reference when the plugin is refreshed, and never guess at tools that aren't documented.
 
 **Error handling.**
 - Invalid `account_id` → re-run `search_accounts` and confirm selection with the user.

diff --git a/docs/realize-best-practices-gap.md b/docs/realize-best-practices-gap.md
@@ -32,16 +32,21 @@ This document serves three jobs, in order of size:
 
 ## Current MCP capability baseline
 
-The MCP exposes **11 tools at the current release**, all read-only:
+This plugin wires **18 read tools** from the upstream MCP, all read-only:
 
 | Area | Tools |
 |---|---|
 | Accounts | `search_accounts` |
-| Campaigns | `get_all_campaigns`, `get_campaign`, `get_campaign_items`, `get_campaign_item` |
+| Campaigns | `list_campaigns`, `get_campaign` |
+| Items | `list_items`, `get_item` |
+| Discovery — targeting | `search_geos`, `search_techno` |
+| Discovery — audiences | `search_audiences`, `search_lookalike_audiences`, `search_contextual_segments` |
+| Discovery — publishers / conversion | `search_publishers`, `search_conversion_rules` |
+| Resources | `list_time_zones`, `list_cta_types` |
 | Reports (CSV) | `get_top_campaign_content_report`, `get_campaign_breakdown_report`, `get_campaign_history_report`, `get_campaign_site_day_breakdown_report` |
 | Auth (stdio only) | `get_auth_token`, `get_token_details` |
 
-No create, update, delete, pause, conversion-tracking, audience, or configuration tools.
+Write operations (campaign + item create/edit) are not enabled in this plugin revision — see Part 3 for the catalog of write capabilities still routed through the `create-campaign` UI walkthrough.
 
 ---
 
@@ -61,7 +66,7 @@ No create, update, delete, pause, conversion-tracking, audience, or configuratio
 | Audience targeting (skip for new; use suppression) | `create-campaign` Step 7 |
 | 3–10 ads per campaign; "pre-qualify the click"; avoid generic CTAs | `create-campaign` Step 8 |
 | Dynamic Keyword Insertion mention | `create-campaign` Step 8 |
-| Post-launch MCP verification via `get_campaign` + `get_campaign_items` | `create-campaign` Step 10 |
+| Post-launch MCP verification via `get_campaign` + `list_items` | `create-campaign` Step 10 |
 
 ### From "How to Improve Campaign Performance"