Titan AI Connect Skill

# TitanConnect — Actions Reference (Amazon Ads writes — REAL MONEY)

**⚠️ Read this entire file before calling any `propose_*` tool. ⚠️**

Action tools modify the user's Amazon Advertising account. Every call may spend real money or change live ads. There is no automatic rollback.

## How approval works

Before any `propose_*` tool runs, your host (Claude.ai, Claude Desktop, Claude Code, Cowork) prompts the user to Approve or Deny:

| Host | Approval surface |
|------|------------------|
| Claude.ai web custom connector | "Allow this tool call?" dialog with tool name + JSON args |
| Claude Desktop | Similar dialog |
| Claude Code plugin | Permission prompt unless user pre-allowlisted in `~/.claude/settings.json` |
| Cowork | Per-tool prompt |
| OpenClaw | **NO PROMPT.** OpenClaw runs tools unattended. The skill's narration is the only safeguard. |

**Bundling on OpenClaw**: when multiple writes are bundled in a single response, OpenClaw runs each tool unattended — there's no per-call gate. The user reviews the batch retroactively. Narrate fully before bundled writes since OpenClaw cannot prompt the user mid-batch.

## DANGER: "Always Allow" is your enemy

Most hosts let the user toggle "Always Allow" per-tool or per-connector. **Once toggled, the human-in-the-loop is gone.** A single misread sales report could spawn 10 campaigns at $500/day each, draining the user's ad budget overnight.

**Always tell users**: "I recommend reviewing every action call. Do NOT enable Always Allow for the propose_* tools."

## Action execution mode (`dryRun` field)

**Every `propose_*` call writes to Amazon for real by default. Production does NOT run in dry-run mode.** There is an env var `ACTIONS_FORCE_DRY_RUN=true` that forces simulation, but it is **not set in production**, so every propose_* call landing on prod spends real money or changes live ads.

**Never mention dry-run mode in user-facing prose.** Whether `dryRun` is true (staging / non-prod env) or false (production), the post-call message is the same: a one-or-two sentence natural-prose description of the change. The dry-run flag is environment-level plumbing — internal testers already know they're in a non-prod env; production users will never see dry-run; mentioning it adds confusion in both cases.

Forbidden post-call phrases include but are not limited to:
- "this was a simulation"
- "no Amazon-side change was made"
- "the call hit Nexus but was NOT pushed to Amazon"
- "the dryRun flag is true / false"
- "production runs LIVE" / any framing that compares this run to a hypothetical other run

Just describe what changed — same wording in either env. See the "Result presentation" section below.

Never assume dry-run mode is on. The user's narration + their explicit approval are the only safeguards before real spend.

## Multi-status responses

Every action returns:

```json
{
  "dryRun": true,
  "correlationId": "uuid",
  "success": [{ "index": 0, "<entityIdField>": "..." }],
  "error":   [{ "index": 1, "code": "...", "details": "..." }],
  "entityType": "sp.campaign"
}
```

The `<entityIdField>` name varies per tool — see `WIRE_FORMATS.md`. Partial-failure batches leave some items live on Amazon and others not. Narrate per-item: "Created campaign A (id 12345). Item 2 failed: duplicate name."

In dry-run mode most tools echo `dry-run-<index>` as the entity id. `propose_update_sd_campaign` is an exception — it echoes the actual `campaignId` you passed (different dry-run shape upstream). Either is fine; the narration is the same.

## Result presentation

Write-tool responses come back as a programmatic envelope: `{ dryRun, correlationId, success: [...], error: [...], entityType }`. **The user never sees this envelope.** Field names, raw API enums, post-read confirmations, and correlation IDs are diagnostic plumbing — they belong in audit logs, not in chat.

The post-call message is **one or two sentences of natural prose** describing what changed on the user's account. Nothing else.

### Good

- "Top of Search modifier raised to 25%. Product Pages stays at 10%."
- "Top of Search modifier removed. The campaign now uses the default bid for that placement."
- "Bid raised from $1.50 to $1.75."
- "Paused 3 keywords; 2 succeeded, 1 failed (duplicate name)."
- "Created campaign 'Brand Defense'."

These read identically whether the call ran in dry-run or live mode — see the dry-run section above for why.

### Forbidden — never appears in user-facing prose

| Don't write | Why | Write instead |
|---|---|---|
| `dryRun: false ✓ real write` | Field-name leak with checklist framing — looks like a debug dump | "The change has been applied to your campaign." |
| `error: [] ✓ no failures` | Same | (omit — silence implies success) |
| `success: [...]`, "the success array shows..." | Field-name leak | Describe the change in plain English |
| `correlationId: 8e827507-...` | Diagnostic ID — only surface if user asks how to escalate | Omit by default. If they ask, frame as "support reference: 8e827507". |
| `PLACEMENT_TOP`, `PLACEMENT_PRODUCT_PAGE`, `PLACEMENT_REST_OF_SEARCH` | Raw API enum | "Top of Search", "Product Pages", "Rest of Search" |
| `LEGACY_FOR_SALES`, `AUTO_FOR_SALES`, `MANUAL` | Raw bidding-strategy enum | "the campaign's current bidding strategy" / "automatic for sales" / "manual bidding" |
| `ENABLED`, `PAUSED`, `ARCHIVED` | Raw state enum | "active", "paused", "archived" (lowercase, prose form) |
| "Post-read confirms ..." / "verified against Amazon's response" / "the multi-status response shows..." | Internal verification plumbing — the user does not need to know there's a post-read | Just state the new value: "Top of Search is now 25%." |
| `entityType: sp.campaign` | Internal taxonomy | (omit) |
| "envelope returned..." / "dispatch result was..." | Internal jargon | Describe the outcome |

**The shape of every post-call message:** [what changed in user-visible terms], [optional: what stayed the same if they asked you not to touch it], [if dry-run: "this was a simulation"]. Stop there.

**Errors get the same treatment.** If the response carries `error: 'CAMPAIGN_NOT_FOUND'`, the user reads "I couldn't find that campaign in your account — can you double-check the id?" — not "tool returned `error: 'CAMPAIGN_NOT_FOUND'`".

This section governs the *post-call* prose. For pre-call prose, briefly acknowledge what you're about to do (one sentence is fine), then call the tool.

## Placement bid modifiers — use the dedicated tool

Placement bid modifiers — the percentage adjustments for Top of Search, Product Pages, and Rest of Search — write through the dedicated tool **`propose_update_sp_campaign_placement_modifiers`** (re-enabled 2026-05-07). Do **NOT** try to use `propose_update_sp_campaign` for these — its schema rejects any `bidding`/`dynamicBidding` fields and routes you to the dedicated tool instead.

When a user asks to change a placement modifier:

1. Source the campaign's current `biddingStrategy` (and current placement values for context) from `search_for_ppc_campaigns({campaignIds: [id]})`.
2. Call `propose_update_sp_campaign_placement_modifiers` with `{campaignId, dynamicBidding: {strategy, placementBidding: [...]}}`. **Strategy is REQUIRED** by Amazon — pass the existing one unless you intend to change it.
3. Trust Amazon's merge-by-placement-key semantic: send only the placements you want to change; placements not mentioned are preserved (verified 2026-05-07). Send `{placement, percentage: 0}` to **remove** a single placement. `placementBidding: []` and omitting the key entirely are both no-ops — to clear all modifiers, send `0` for each currently-set placement.

The tool reads the campaign before and after the write and only records SUCCESS in `action_logs` when the post-read confirms the change landed (D2 mitigation). Watch for `ARCHIVED_NOT_EDITABLE` (unarchive first via `propose_update_sp_campaign`) or `WRITE_VERIFICATION_FAILED` (Nexus 200 but post-read disagrees — forensics in `action_logs`).

**Forbidden:**

- Do **NOT** route users to Seller Central for placement-modifier changes. The dedicated tool is live.
- Do **NOT** propose creative workarounds like encoding the modifier value in the campaign name (e.g. renaming to "...100 TOS"). The encoded name does not affect bidding behavior.
- Do **NOT** put placement fields on `propose_update_sp_campaign`. Use `propose_update_sp_campaign_placement_modifiers`.

## Marketplace handling

Do NOT pass `marketplace` in `propose_*` or `get_sp_bid_recommendations` calls. It is auto-resolved from the active seller's `mainSalesChannel` (e.g. `"Amazon.com"`, `"Amazon.co.uk"`). Passing it is silently ignored. If you need the registered marketplace list, call `get_marketplaces`.

## Verified status (post-audit, 2026-05-05 — adds 9 negative-keyword UPDATE + negative-target CRUD tools)

| Tool | Result | Notes |
|------|--------|-------|
| `propose_create_sp_portfolio` | ✅ | State ∈ {ENABLED, PAUSED} only (no ARCHIVED). |
| `propose_update_sp_portfolio` | ✅ | State ∈ {ENABLED, PAUSED} only. |
| `propose_create_sp_campaign` | ✅ | Use `budget.budget`, not `budget.amount`. State ∈ {ENABLED, PAUSED}. |
| `propose_update_sp_campaign` | ✅ | **No `startDate` and no `tags` on update** (verified rejected with 400). For placement bid modifiers, use `propose_update_sp_campaign_placement_modifiers`. |
| `propose_update_sp_campaign_placement_modifiers` | ✅ | **NEW 2026-05-07.** Single-campaign target. Full upstream `dynamicBidding` shape — `strategy` REQUIRED, `placementBidding[]` optional. Amazon merges by placement key; `percentage: 0` removes the placement; `placementBidding: []` and omitting the key are no-ops. Pre-read rejects ARCHIVED + captures `oldValue`; post-read verifies the modifier landed. action_logs row written with both pre/post snapshots; `WRITE_VERIFICATION_FAILED` if observed ≠ requested (D2 mitigation). |
| `propose_create_sp_campaign_neg_keyword` | ✅ | State must be `"ENABLED"` only. success.campaignNegativeKeywordId. |
| `propose_update_sp_campaign_neg_keyword` | ✅ | **NEW 2026-05-05.** UPPERCASE 3-value state. success.campaignNegativeKeywordId. State-only update. |
| `propose_create_sp_ad_group` | ✅ | State ∈ {ENABLED, PAUSED}. |
| `propose_update_sp_ad_group` | ✅ | UPPERCASE state. Pause / change defaultBid / change name. |
| `propose_create_sp_keyword` | ✅ | State must be `"ENABLED"` only — use update to pause after create. |
| `propose_update_sp_keyword` | ✅ | UPPERCASE state. Pause / change bid. |
| `propose_create_sp_ad_group_neg_keyword` | ✅ | State must be `"ENABLED"` only. success.keywordId. |
| `propose_update_sp_ad_group_neg_keyword` | ✅ | **NEW 2026-05-05.** UPPERCASE 3-value state. success.**negativeKeywordId** (NOT keywordId). State-only. |
| `propose_create_sp_campaign_neg_target` | ✅ | **NEW 2026-05-05.** Wrapper key `campaignNegativeTargetingClauses`. UPPERCASE_SNAKE expression types (`ASIN_SAME_AS`/`ASIN_BRAND_SAME_AS`); expression SINGULAR. State `ENABLED` only. success.**campaignNegativeTargetingClauseId** (long-form). |
| `propose_update_sp_campaign_neg_target` | ✅ | **NEW 2026-05-05.** UPPERCASE 3-value state. State-only. |
| `propose_create_sp_ad_group_neg_target` | ✅ | **NEW 2026-05-05.** Wrapper key `negativeTargetingClauses`. UPPERCASE_SNAKE expression types; expression SINGULAR. State `ENABLED` only. success.targetId (short-form). |
| `propose_update_sp_ad_group_neg_target` | ✅ | **NEW 2026-05-05.** UPPERCASE 3-value state. State-only. |
| `propose_create_sp_target` | ✅ | State must be `"ENABLED"` only. |
| `propose_update_sp_target` | ✅ | ASIN/category targets only — keyword IDs go through `propose_update_sp_keyword`. |
| `propose_create_sp_product_ad` | ✅ | State ∈ {ENABLED, PAUSED}. |
| `propose_update_sp_product_ad` | ✅ | UPPERCASE state. |
| `propose_update_sb_campaign` | ✅ | UPPERCASE state. **No `startDate` on update** (verified rejected). |
| `propose_update_sb_ad_group` | ✅ | UPPERCASE state ∈ {ENABLED, PAUSED} only (no ARCHIVED). **No `defaultBid`** (verified rejected). |
| `propose_update_sb_ad` | ✅ | UPPERCASE state ∈ {ENABLED, PAUSED} only. |
| `propose_update_sb_keyword` | ✅ | **lowercase** state. Items require `keywordId` + `adGroupId` + `campaignId`. |
| `propose_update_sb_target` | ✅ | **NEW 2026-05-02. lowercase** state. Items require `targetId` + `adGroupId` + `campaignId`. |
| `propose_create_sb_ad_group_neg_keyword` | ✅ | **NEW 2026-05-02. matchType is camelCase** (`negativeExact`/`negativePhrase`) — DIFFERENT from SP. No `state` field. |
| `propose_update_sb_ad_group_neg_keyword` | ✅ | **NEW 2026-05-05. lowercase** state. Items require `keywordId` + `adGroupId` + `campaignId`. Flat-array response (same shape as SB keyword UPDATE). |
| `propose_create_sb_ad_group_neg_target` | ✅ | **NEW 2026-05-05.** Body key `negativeTargets`; per-item field `expressions` (PLURAL). camelCase types (`asinSameAs`/`asinBrandSameAs`). No `state` field — implicit ENABLED. Envelope shape `{createTargetSuccessResults, createTargetErrorResults}` — adapter normalizes to canonical multi-status. |
| `propose_update_sb_ad_group_neg_target` | ✅ | **NEW 2026-05-05. lowercase** state. Items require `targetId` + `adGroupId`. Envelope shape `{updateTargetSuccessResults, updateTargetErrorResults}` — same adapter as create. |
| `propose_update_sd_campaign` | ✅ | **lowercase** state — fixed 2026-05-02 (was incorrectly UPPERCASE in our schema). **No `startDate` on update**. |
| `propose_update_sd_ad_group` | ✅ | **lowercase** state. Flat-array response. |
| `propose_update_sd_product_ad` | ✅ | **lowercase** state. Flat-array response. |
| `propose_update_sd_target` | ✅ | **NEW 2026-05-02. lowercase** state. Just `targetId` + optional state/bid. |
| `get_sp_bid_recommendations` | ✅ | Read-only; p50 ≈ 40s |

### State case quirks (read this carefully)

State casing varies by route. Mismatch fails at Zod validation before any network call.

| Tools | State case |
|-------|------------|
| **lowercase** | `propose_update_sb_keyword`, `propose_update_sb_target`, `propose_update_sb_ad_group_neg_keyword`, `propose_update_sb_ad_group_neg_target`, `propose_update_sd_campaign`, `propose_update_sd_ad_group`, `propose_update_sd_product_ad`, `propose_update_sd_target` |
| UPPERCASE 3 values (ENABLED/PAUSED/ARCHIVED) | All SP routes, `propose_update_sb_campaign` |
| UPPERCASE 2 values (ENABLED/PAUSED only) | `propose_create_sp_portfolio`, `propose_update_sp_portfolio`, `propose_create_sp_campaign`, `propose_create_sp_ad_group`, `propose_create_sp_product_ad`, `propose_update_sb_ad_group`, `propose_update_sb_ad` |
| `"ENABLED"` only on create | `propose_create_sp_keyword`, `propose_create_sp_target`, `propose_create_sp_campaign_neg_keyword`, `propose_create_sp_ad_group_neg_keyword`, `propose_create_sp_campaign_neg_target`, `propose_create_sp_ad_group_neg_target` |
| No `state` field at all (state implicit ENABLED) | `propose_create_sb_ad_group_neg_keyword`, `propose_create_sb_ad_group_neg_target` |

### Negative-keyword matchType case quirk

| Tool | `matchType` case |
|------|------------------|
| `propose_create_sp_campaign_neg_keyword` | UPPERCASE: `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` |
| `propose_create_sp_ad_group_neg_keyword` | UPPERCASE: `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` |
| `propose_create_sb_ad_group_neg_keyword` | **camelCase**: `negativeExact` / `negativePhrase` |

> The matchType case-quirk only applies to CREATE — UPDATEs are state-only and do not carry `matchType`.

### Negative-target expression-type case quirk

| Tool | `expression[].type` case | Field name |
|------|--------------------------|-----------|
| `propose_create_sp_campaign_neg_target` | UPPERCASE_SNAKE: `ASIN_SAME_AS` / `ASIN_BRAND_SAME_AS` | `expression` (singular) |
| `propose_create_sp_ad_group_neg_target` | UPPERCASE_SNAKE: `ASIN_SAME_AS` / `ASIN_BRAND_SAME_AS` | `expression` (singular) |
| `propose_create_sb_ad_group_neg_target` | **camelCase**: `asinSameAs` / `asinBrandSameAs` | **`expressions`** (PLURAL) |

## Failure modes

| Result | Meaning | What to do |
|--------|---------|-----------|
| `MUST_SET_ACTIVE_ACCOUNT` | No Titan Tools account active | Call `list_accounts` → `switch_account` first |
| `NO_ACTIVE_SELLER` | No seller selected | Call `list_seller_accounts` → `set_active_seller` |
| `OAUTH_REFRESH_FAILED` | Refresh token rotated/expired | Tell the user to reconnect at <https://titanconnect.titannetwork.com> |
| `OAUTH_REFRESH_REVOKED` | Upstream rejected the refresh as invalid/expired | Same as above — re-link |
| `OAUTH_REFRESH_NETWORK` | Transient network/5xx during refresh | Retry once; if persists, surface error to user |
| `INSUFFICIENT_SCOPE` | OAuth grant lacks `tools:write` | Ask the user to re-link with that scope |
| `NEXUS_CALL_FAILED` | Nexus 5xx or transport error | Surface the error message; do NOT retry without LIST-ing first to verify state |
| `error.length > 0` | Partial multi-status failure | Narrate per-item; some items succeeded, some failed |

## Common rollback recipes

| Action | How to undo |
|--------|-------------|
| Created campaign | `propose_update_sp_campaign` with `state: ARCHIVED` |
| Created keyword | `propose_update_sp_target` with `state: ARCHIVED` (or per-entity equivalent) |
| Updated budget | Re-`propose_update_sp_campaign` with the prior budget value |
| Added neg keyword | `propose_update_sp_*_neg_keyword` (or `propose_update_sb_ad_group_neg_keyword`) with `state: ARCHIVED` (or `archived` for SB). |
| Added neg target | `propose_update_sp_*_neg_target` (or `propose_update_sb_ad_group_neg_target`) with `state: ARCHIVED` (or `archived` for SB). |

The user must approve each rollback call too.

## Critical rules summary (in priority order)

1. **Knowledge before action.** Even action requests trigger the source-of-truth principle — call `titan_lessons` for the strategic rationale before proposing the write. The action narration must cite the Titan source.
2. **Bundle freely.** Multiple `propose_*` calls in one response are fine — the host approves each call individually. Use bundling for batch negation / batch pausing / multi-step plans.
3. **Acknowledge before acting.** Briefly say what you're about to do (one sentence is fine), then proceed.
4. **No "Always Allow" nudge.**
5. **Inspect the multi-status `error[]`.** Empty `error` is the only success.
6. **No fabricated IDs** — campaignId, adGroupId, keywordId, targetId all come only from this turn's tool results.
7. **No marketplace param.**
8. **Inspect `dryRun` on every response.** Production runs with `dryRun: false` — every call is real. `dryRun: true` only appears in non-prod environments and means simulation. Say which one occurred explicitly.

If a `propose_*` tool returns `MUST_SET_ACTIVE_ACCOUNT`, call `switch_account` first, then `set_active_seller`, then re-attempt the propose call.

# TitanConnect — Wire Format Reference (`propose_*` body shapes)

Verified 2026-04-26 against staging Nexus. Wrong shape = 400 with a misleading error.

## `propose_create_sp_campaign`

Budget is doubly-nested. `currencyCode` is NOT accepted (currency comes from the seller's main currency).

```json
{
  "campaigns": [{
    "name": "...",
    "targetingType": "MANUAL",
    "state": "ENABLED",
    "startDate": "2026-04-26",
    "budget": { "budget": 10, "budgetType": "DAILY" }
  }]
}
```

**Common mistake:** passing `budget.amount` or `budget.currencyCode`. Nexus rejects with `campaigns.0.budget.budget must not be less than 1`.

## `propose_update_sp_campaign`

Pause is the most common use:

```json
{ "campaigns": [{ "campaignId": "12345", "state": "PAUSED" }] }
```

To change budget (same shape as create):

```json
{ "campaigns": [{ "campaignId": "12345", "budget": { "budget": 25, "budgetType": "DAILY" } }] }
```

For placement bid modifiers, do **NOT** use this tool — use `propose_update_sp_campaign_placement_modifiers` (below). It carries the read-after-write verification baked in.

## `propose_update_sp_campaign_placement_modifiers`

Re-enabled 2026-05-07. Single-campaign target. Full upstream `dynamicBidding` shape — `strategy` is REQUIRED by Amazon (`@IsNotEmpty()` on the upstream Nexus DTO), `placementBidding[]` is optional.

Body shape:

```json
{
  "campaignId": "12345",
  "dynamicBidding": {
    "strategy": "MANUAL",
    "placementBidding": [
      { "placement": "PLACEMENT_TOP", "percentage": 25 }
    ]
  }
}
```

`placement` must be one of `PLACEMENT_TOP` (Top of Search), `PLACEMENT_PRODUCT_PAGE` (Product Pages), `PLACEMENT_REST_OF_SEARCH` (Rest of Search). `percentage` is `0..900`.

`strategy` must be one of `LEGACY_FOR_SALES`, `AUTO_FOR_SALES`, `MANUAL`. Pass the campaign's current `biddingStrategy` (sourced from `search_for_ppc_campaigns` or `get_account_ppc_metrics_by_campaign`) unless you intend to change it.

**Amazon merges `placementBidding` by placement key — verified 2026-05-07.** Placements not mentioned in the request are preserved. So to "set TOS to 30 without touching PP", just send TOS:

```json
{ "dynamicBidding": { "strategy": "MANUAL", "placementBidding": [{ "placement": "PLACEMENT_TOP", "percentage": 30 }] } }
```

**To clear a single placement, send `percentage: 0` for it.** Verified 2026-05-07: this REMOVES the placement entry from the campaign's array. To clear TOS but keep PP at its current value of 10:

```json
{ "dynamicBidding": { "strategy": "<existing>", "placementBidding": [{ "placement": "PLACEMENT_TOP", "percentage": 0 }] } }
```

**Empty `placementBidding: []` is a NO-OP.** It does not clear any modifiers — Amazon ignores it. To clear ALL placements, pass `percentage: 0` for each currently-set placement.

**Omitting `placementBidding` entirely is a NO-OP.** Use this only if you want to change `strategy` alone without touching modifiers.

**Errors specific to this tool:**

| `error` | Meaning | What to do |
|---------|---------|-----------|
| `CAMPAIGN_NOT_FOUND` | The campaignId is not in this seller's SP campaign list | Verify the id (search_for_ppc_campaigns) |
| `ARCHIVED_NOT_EDITABLE` | Campaign is ARCHIVED — Amazon won't accept placement-modifier writes on archived campaigns | Unarchive first via `propose_update_sp_campaign` (state: ENABLED), then retry |
| `WRITE_VERIFICATION_FAILED` | Nexus returned 200 but the post-read does not reflect the requested change | Check Seller Central; forensics in `action_logs.errorMessage` (JSON with `requested` / `observed` / `mismatches`) |

## `propose_create_sp_campaign_neg_keyword`

Success items carry `campaignNegativeKeywordId` (NOT `keywordId`).

```json
{
  "negativeKeywords": [{
    "campaignId": "12345",
    "keywordText": "irrelevant search term",
    "matchType": "NEGATIVE_EXACT"
  }]
}
```

`matchType` is `"NEGATIVE_EXACT"` or `"NEGATIVE_PHRASE"`.

## `propose_create_sp_ad_group_neg_keyword`

Success items carry `keywordId`. Body uses `adGroupId` instead of `campaignId`:

```json
{
  "negativeKeywords": [{
    "adGroupId": "67890",
    "keywordText": "irrelevant search term",
    "matchType": "NEGATIVE_EXACT"
  }]
}
```

## `propose_create_sp_keyword`

Promote keywords to a specific match type:

```json
{
  "keywords": [{
    "adGroupId": "67890",
    "keywordText": "camp towels quick dry",
    "matchType": "EXACT",
    "bid": 1.25,
    "state": "ENABLED"
  }]
}
```

`matchType` is `"EXACT"`, `"PHRASE"`, or `"BROAD"`.

## `propose_create_sp_ad_group`

```json
{
  "adGroups": [{
    "campaignId": "12345",
    "name": "...",
    "defaultBid": 1.00,
    "state": "ENABLED"
  }]
}
```

## `propose_create_sp_target`

For product / category targets:

```json
{
  "targets": [{
    "adGroupId": "67890",
    "expression": [{ "type": "ASIN_SAME_AS", "value": "B0XXXXXXXX" }],
    "bid": 1.00,
    "state": "ENABLED"
  }]
}
```

## `propose_update_sp_target`

State or bid update:

```json
{ "targets": [{ "targetId": "T1", "state": "PAUSED" }] }
```

## `propose_create_sp_product_ad`

**Required fields**: `campaignId`, `adGroupId`, `state`, AND exactly one of `asin` OR `sku` (not both).

**By ASIN** (most common — for parent listings without variations):

```json
{
  "productAds": [{
    "campaignId": "12345",
    "adGroupId": "67890",
    "asin": "B0XXXXXXXX",
    "state": "ENABLED"
  }]
}
```

**By SKU** (use when the listing has variations and you need to disambiguate):

```json
{
  "productAds": [{
    "campaignId": "12345",
    "adGroupId": "67890",
    "sku": "MY-SKU-001",
    "state": "ENABLED"
  }]
}
```

**Never send both `asin` and `sku` in the same item** — Amazon Ads API rejects redundant identifiers. Send the one that matches how the listing is configured. If unsure, ASIN works for the majority of cases.

## `propose_create_sp_portfolio` / `propose_update_sp_portfolio`

```json
{
  "portfolios": [{
    "name": "...",
    "state": "ENABLED",
    "budget": { "amount": 1000, "policy": "MONTHLY_RECURRING" }
  }]
}
```

Note: portfolio budget uses `amount + policy`, NOT the campaign-level `budget.budget + budgetType` shape. This is one of the few tools where the spec deviates.

## `propose_update_sb_campaign` / `propose_update_sd_campaign`

```json
{ "campaigns": [{ "campaignId": "...", "state": "PAUSED" }] }
```

`propose_update_sd_campaign` dry-run echoes the actual `campaignId` (not `dry-run-0`).

## `propose_update_sp_ad_group` (NEW 2026-05-01)

UPPERCASE state. Pause / change defaultBid / change name. Wrapped multi-status response under `adGroups`.

```json
{ "adGroups": [{ "adGroupId": "67890", "state": "PAUSED" }] }
```

## `propose_update_sp_keyword` (NEW 2026-05-01 — un-stubbed)

UPPERCASE state. Pause / change bid.

```json
{ "keywords": [{ "keywordId": "K1", "state": "PAUSED" }] }
```

## `propose_update_sp_product_ad` (NEW 2026-05-01)

UPPERCASE state. Wrapped multi-status response under `productAds`.

```json
{ "productAds": [{ "adId": "A1", "state": "PAUSED" }] }
```

## `propose_update_sb_ad_group` / `propose_update_sb_ad` (NEW 2026-05-01)

UPPERCASE state. Wrapped multi-status response.

```json
{ "adGroups": [{ "adGroupId": "67890", "state": "PAUSED" }] }
{ "ads":      [{ "adId":      "A1",    "state": "PAUSED" }] }
```

## `propose_update_sb_keyword` (NEW 2026-05-01 — lowercase state)

⚠️  **lowercase** state values: `enabled`/`paused`/`archived`. Items require **both** `keywordId` AND parent `adGroupId`+`campaignId` (per upstream SB contract).

```json
{
  "keywords": [{
    "keywordId": "K1",
    "adGroupId": "67890",
    "campaignId": "12345",
    "state": "paused"
  }]
}
```

## `propose_update_sd_campaign` (FIXED 2026-05-02 — lowercase state)

⚠️  **lowercase** state — earlier wrapper sent UPPERCASE incorrectly. No `startDate` on update (rejected by API).

```json
{ "campaigns": [{ "campaignId": "...", "state": "paused" }] }
```

## `propose_update_sd_ad_group` / `propose_update_sd_product_ad` / `propose_update_sd_target` (lowercase state, flat-array response)

⚠️  **lowercase** state values: `enabled`/`paused`/`archived`. Response is a **flat array**, not the wrapped `{ adGroups: { success, error } }` shape — `parseMultiStatus` branches on whether the response is an array. The wrapper handles both shapes; you (the LLM) just see the normalized `{ success, error }` envelope.

```json
{ "adGroups":   [{ "adGroupId": "67890", "state": "paused" }] }
{ "productAds": [{ "adId":      "A1",    "state": "paused" }] }
{ "targets":    [{ "targetId":  "T1",    "state": "paused", "bid": 1.5 }] }
```

## `propose_update_sb_target` (NEW 2026-05-02 — lowercase state, requires parent IDs)

⚠️  **lowercase** state. Each item must include the `targetId` AND its parent `adGroupId` + `campaignId`.

```json
{
  "targets": [{
    "targetId":   "T1",
    "adGroupId":  "67890",
    "campaignId": "12345",
    "state":      "paused"
  }]
}
```

## `propose_create_sb_ad_group_neg_keyword` (NEW 2026-05-02 — camelCase matchType)

⚠️  `matchType` is **camelCase** for SB: `negativeExact` | `negativePhrase`. DIFFERENT from SP's UPPERCASE `NEGATIVE_EXACT`. No `state` field.

```json
{
  "negativeKeywords": [{
    "campaignId":  "12345",
    "adGroupId":   "67890",
    "keywordText": "irrelevant search term",
    "matchType":   "negativeExact"
  }]
}
```

## `propose_update_sp_campaign_neg_keyword` (NEW 2026-05-05)

State-only update. UPPERCASE 3-value state. Wrapper key matches the create
counterpart (`campaignNegativeKeywords`); success-id is `campaignNegativeKeywordId`.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "campaignNegativeKeywords": [{
    "keywordId": "12345678901234",
    "state":     "PAUSED"
  }]
}
```

## `propose_update_sp_ad_group_neg_keyword` (NEW 2026-05-05)

State-only update. UPPERCASE 3-value state. Wrapper key `negativeKeywords`. ⚠️
Response success-id is **`negativeKeywordId`**, NOT `keywordId` — verified
empirically 2026-05-05 against Brendan's account.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "negativeKeywords": [{
    "keywordId": "12345678901234",
    "state":     "ARCHIVED"
  }]
}
```

## `propose_update_sb_ad_group_neg_keyword` (NEW 2026-05-05 — lowercase state, requires parent IDs)

⚠️  **lowercase** state for SB. Each item must include `keywordId` AND its
parent `adGroupId` + `campaignId`. Response is flat-array (same shape as SB
keyword UPDATE).

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "negativeKeywords": [{
    "keywordId":  "12345678901234",
    "adGroupId":  "67890",
    "campaignId": "12345",
    "state":      "paused"
  }]
}
```

## `propose_create_sp_campaign_neg_target` (NEW 2026-05-05 — campaign-level ASIN/brand block)

⚠️  Wrapper key is `campaignNegativeTargetingClauses` (long-form). Expression
types are UPPERCASE_SNAKE; per-item field is `expression` (singular). State
must be `"ENABLED"` (omit to default). Response success-id is the long-form
**`campaignNegativeTargetingClauseId`**.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "campaignNegativeTargetingClauses": [{
    "campaignId": "12345",
    "expression": [
      { "type": "ASIN_SAME_AS",       "value": "B0XXXXXXXX" },
      { "type": "ASIN_BRAND_SAME_AS", "value": "CompetitorBrand" }
    ],
    "state": "ENABLED"
  }]
}
```

## `propose_update_sp_campaign_neg_target` (NEW 2026-05-05 — state-only)

State-only update. UPPERCASE 3-value state. Wrapper key matches the create
counterpart; success-id is the long-form `campaignNegativeTargetingClauseId`.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "campaignNegativeTargetingClauses": [{
    "targetId": "12345678901234",
    "state":    "PAUSED"
  }]
}
```

## `propose_create_sp_ad_group_neg_target` (NEW 2026-05-05 — ad-group-level ASIN/brand block)

⚠️  Wrapper key is `negativeTargetingClauses` (different from the campaign-level tool!).
Expression types are UPPERCASE_SNAKE; per-item field is `expression` (singular).
State must be `"ENABLED"`. Response success-id is the **short-form `targetId`**.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "negativeTargetingClauses": [{
    "campaignId": "12345",
    "adGroupId":  "67890",
    "expression": [{ "type": "ASIN_SAME_AS", "value": "B0XXXXXXXX" }],
    "state":      "ENABLED"
  }]
}
```

## `propose_update_sp_ad_group_neg_target` (NEW 2026-05-05 — state-only)

State-only update. UPPERCASE 3-value state.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "negativeTargetingClauses": [{
    "targetId": "12345678901234",
    "state":    "ARCHIVED"
  }]
}
```

## `propose_create_sb_ad_group_neg_target` (NEW 2026-05-05 — camelCase, expressions PLURAL, no state)

⚠️  Two simultaneous quirks vs SP:
1. **camelCase** expression types: `asinSameAs` / `asinBrandSameAs` (DIFFERENT from SP's UPPERCASE_SNAKE).
2. Per-item field is **`expressions`** (PLURAL — DIFFERENT from SP's `expression`).
3. **No `state` field** at all — state is implicit `ENABLED`. Use the UPDATE tool to pause / archive.

The response uses a non-canonical envelope:
`{createTargetSuccessResults, createTargetErrorResults}` (per-item index field
is `targetRequestIndex`, not `index`). The wrapper normalizes to the standard
multi-status shape.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "negativeTargets": [{
    "campaignId": "12345",
    "adGroupId":  "67890",
    "expressions": [{ "type": "asinSameAs", "value": "B0XXXXXXXX" }]
  }]
}
```

## `propose_update_sb_ad_group_neg_target` (NEW 2026-05-05 — lowercase state, requires parent adGroupId)

⚠️  **lowercase** state for SB. Each item must include `targetId` AND its
parent `adGroupId`. Response uses
`{updateTargetSuccessResults, updateTargetErrorResults}` envelope, normalized
by the wrapper.

```json
// VERIFIED 2026-05-05 against Brendan's account (dry-run)
{
  "negativeTargets": [{
    "targetId":  "12345678901234",
    "adGroupId": "67890",
    "state":     "paused"
  }]
}
```

## Update-body fields per endpoint (allowlist)

For each `propose_update_*` tool, here are exactly the per-item fields the API accepts. Anything outside this list 400s (verified live 2026-05-02). Required fields are bold.

| Tool | Per-item fields |
|------|-----------------|
| `propose_update_sp_portfolio` | **`portfolioId`**, `name?`, `state?` (UPPERCASE 2-value), `budget?` |
| `propose_update_sp_campaign` | **`campaignId`**, `name?`, `portfolioId?`, `state?` (UPPERCASE 3-value), `budget?`, `endDate?` |
| `propose_update_sp_campaign_placement_modifiers` | **`campaignId`**, **`dynamicBidding.strategy`** (`LEGACY_FOR_SALES`/`AUTO_FOR_SALES`/`MANUAL`), `dynamicBidding.placementBidding[]?` (`{placement, percentage}` — `percentage: 0` removes; merges by key) |
| `propose_update_sp_ad_group` | **`adGroupId`**, `name?`, `state?` (UPPERCASE 3-value), `defaultBid?` |
| `propose_update_sp_keyword` | **`keywordId`**, `state?` (UPPERCASE 3-value), `bid?` |
| `propose_update_sp_target` | **`targetId`**, `state?` (UPPERCASE 3-value), `bid?` (ASIN/category targets only — keyword IDs go through `propose_update_sp_keyword`) |
| `propose_update_sp_product_ad` | **`adId`**, `state?` (UPPERCASE 3-value) |
| `propose_update_sb_campaign` | **`campaignId`**, `name?`, `state?` (UPPERCASE 3-value), `budget?`, `endDate?` |
| `propose_update_sb_ad_group` | **`adGroupId`**, `name?`, `state?` (UPPERCASE 2-value) |
| `propose_update_sb_ad` | **`adId`**, `state?` (UPPERCASE 2-value) |
| `propose_update_sb_keyword` | **`keywordId`**, **`adGroupId`**, **`campaignId`**, `state?` (lowercase 3-value), `bid?` |
| `propose_update_sb_target` | **`targetId`**, **`adGroupId`**, **`campaignId`**, `state?` (lowercase 3-value), `bid?` |
| `propose_update_sd_campaign` | **`campaignId`**, `name?`, `state?` (lowercase 3-value), `budget?`, `endDate?` |
| `propose_update_sd_ad_group` | **`adGroupId`**, `name?`, `state?` (lowercase 3-value), `defaultBid?` |
| `propose_update_sd_product_ad` | **`adId`**, `state?` (lowercase 3-value) |
| `propose_update_sd_target` | **`targetId`**, `state?` (lowercase 3-value), `bid?` |
| `propose_update_sp_campaign_neg_keyword` | **`keywordId`**, `state?` (UPPERCASE 3-value) |
| `propose_update_sp_ad_group_neg_keyword` | **`keywordId`**, `state?` (UPPERCASE 3-value) |
| `propose_update_sb_ad_group_neg_keyword` | **`keywordId`**, **`adGroupId`**, **`campaignId`**, `state?` (lowercase 3-value) |
| `propose_create_sp_campaign_neg_target` | **`campaignId`**, **`expression[]`** (UPPERCASE_SNAKE types — `ASIN_SAME_AS`/`ASIN_BRAND_SAME_AS`), `state?` (`"ENABLED"` only) |
| `propose_update_sp_campaign_neg_target` | **`targetId`**, `state?` (UPPERCASE 3-value) |
| `propose_create_sp_ad_group_neg_target` | **`campaignId`**, **`adGroupId`**, **`expression[]`** (UPPERCASE_SNAKE types), `state?` (`"ENABLED"` only) |
| `propose_update_sp_ad_group_neg_target` | **`targetId`**, `state?` (UPPERCASE 3-value) |
| `propose_create_sb_ad_group_neg_target` | **`campaignId`**, **`adGroupId`**, **`expressions[]`** (PLURAL; camelCase types — `asinSameAs`/`asinBrandSameAs`). No `state` field. |
| `propose_update_sb_ad_group_neg_target` | **`targetId`**, **`adGroupId`**, `state?` (lowercase 3-value) |

## `get_ppc_ams_metrics` — read-tool wire quirk (Amazon Marketing Stream)

The only read tool with wire semantics worth calling out — every other read tool's response matches its swagger.

**Request body** (POST `/ppc/metrics/ams`):

- `sellerId` (string, required) — auto-resolved from session.
- `currencyCode` (string, required) — pass any ISO code (USD/EUR/GBP/…); server-side conversion via daily mid-rate snapshotted at UTC midnight.
- `startDate`, `endDate` (YYYY-MM-DD, required). `endDate` can be today; AMS is near-real-time (~4–5h lag), NOT subject to the 2-day daily-PPC-metrics lag.
- `marketplaces` (array of marketplace storefront enums, optional in our Zod; auto-resolved from session). Filter narrows by marketplace ID server-side. Omit / `[]` = unfiltered (all of seller's marketplaces).
- `groupBy` (`'hour'` | `'day'`, required). Bad enum values 400 with `{message: ["groupBy must be one of the following values: hour, day"], error: "Bad Request", statusCode: 400}`.
- `campaignIds`, `portfolioIds`, `asins` (array of strings, optional) — server-side filters. **AND across fields** (intersection — verified live 2026-05-20 against Brendan's account: `campaignIds=[A] + asins=[Y]` where A does not advertise Y returns $0, vs. `campaignIds=[A]` alone returning $1,150.26 and `asins=[Y]` alone returning $91.60). **OR within array** (`campaignIds: [A, B]` matches campaigns A or B). No upstream caps on array lengths.

**Region availability**: AMS is available for all regions where the seller is subscribed via Amazon Ads (confirmed by upstream owner 2026-05-19). No NA-only restriction.

**Response wire shape**:

- `groupBy='hour'` → `{ hours: [...] }` only. The `days` key is **omitted**, NOT returned as `[]`.
- `groupBy='day'` → `{ days: [...] }` only. The `hours` key is omitted.
- Treat both keys as optional / one-of-required in any TypeScript narrowing.
- `groupBy='hour'` ALWAYS returns 24 buckets (missing hours filled with zero metrics).
- `groupBy='day'` returns only the weekday rows that have ANY data. A weekday with literally zero ad activity won't appear — rare for active sellers but watch for it on edge cases.

**Bucket shape**:

```json
{ "hour": "7", "formattedHour": "7:00 AM", "metrics": { "spend": 12.34, "sales": 56.78, "clicks": 9, "orders": 1, "units": 1, "impressions": 100, "cvr": 11.11, "ctr": 9.00, "cpc": 1.37, "acos": 21.74, "rpc": 6.31 } }
```

(For `groupBy='day'`: `"day": "1".."7"`, `"formattedDay": "Monday".."Sunday"` — ISO weekday, Monday=1.)

**Hour timezone — seller's account-level local time** (confirmed by upstream owner 2026-05-19):

The hour value reflects the seller's account-level local timezone, set when they linked their Amazon Ads account — specifically the main country they configured on the seller account. So:

- US seller (Amazon Ads US account) → buckets in **Pacific time** (PT/PDT).
- German seller (Amazon Ads DE account) → buckets in **CET/CEST**.
- UK seller (Amazon Ads UK account) → buckets in **GMT/BST**.
- Japanese seller → **JST**. Etc.

The timezone is per-seller (account-level), NOT per-marketplace in the query. A US-based seller who also operates Amazon.de still gets PT-bucketed data for both marketplaces — Amazon emits all of their AMS data with PT offsets because that's the timezone configured on the account.

**Attribution windows**:

- SP (Sponsored Products) → **7-day attribution**.
- SB (Sponsored Brands) → **14-day attribution**.
- SD (Sponsored Display) → **14-day attribution**.

Sales/orders are bucketed by **conversion hour** (purchase time), not by click hour. A click at 8 AM that converts at 11 AM lands in the 11 AM bucket. So the hour-of-day pattern reflects when customers BUY, not when they CLICK on ads. Spend/clicks/impressions are bucketed by ad-event hour (when the ad served or was clicked).

**ALL-ZERO ≠ NO ADS** — the most consequential teaching point:

A sequence of zero buckets does NOT prove no ads ran. The most common cause is **deliberate operator dayparting**: many advertisers configure ad schedules to run only during a specific window (e.g. 1 PM–11 PM), so the OFF hours are zero by design, not because the budget exhausted or campaigns failed.

| Input / situation | Server response | What it looks like |
|-------------------|-----------------|--------------------|
| Operator dayparting (most common!) | 200 OK | Continuous zero block during configured OFF hours |
| Seller not subscribed to AMS | 200 OK | All buckets zero across the entire window |
| Window pre-dates the seller's AMS subscription start | 200 OK | All-zero (no backfill — only post-subscription events stream) |
| Bogus `sellerId` | 200 OK | All-zero |
| Bogus `campaignIds` | 200 OK | All-zero (filter resolves to no matching rows) |
| `marketplaces: []` or omitted | 200 OK | Unfiltered = all of seller's marketplaces |
| `marketplaces: ["Foo.bar"]` (invalid enum) | 200 OK | **Silently ignored**, returns unfiltered |
| `marketplaces: ["Amazon.ca"]` (seller has no .ca) | 200 OK | All-zero |
| `groupBy: "week"` (invalid enum) | 400 | Structured error |

**Operator-facing rule**: before recommending budget changes off the back of a zero pattern, ASK the operator about their advertising schedule. Many "11 AM cliffs" you'll see in real seller data are deliberate dayparting schedules, not problems to fix. If a zero pattern is genuinely surprising, cross-verify with `get_account_ppc_metrics` for the same window. If account-level shows spend and AMS shows zero across the board, the seller likely needs to subscribe to AMS on the Amazon Ads side.

**Retention**: per-seller backfill horizon = the seller's AMS subscription start date. Amazon doesn't provide historical AMS data — only events emitted after subscription. So a query window that pre-dates the subscription returns zero for those dates with no warning. Empirically Brendan has data back to roughly 1 year ago (subscription cutoff), zero before.

## Conventions

- **`currencyCode` and `marketplace`** are auto-resolved from the active seller (`mainCurrency` and `mainSalesChannel`) — omit them from `propose_*` bodies.
- **Match-type casing**: SP uses UPPERCASE (`NEGATIVE_EXACT`/`NEGATIVE_PHRASE`); SB uses camelCase (`negativeExact`/`negativePhrase`). Positive variants on SP drop the prefix (`EXACT`/`PHRASE`/`BROAD`).
- **State casing varies by route** — see the ACTIONS.md "State case quirks" table for the full mapping. Zod rejects mismatches before the network call.
- **Create-state**: keywords / targets / negative-keywords accept only `"ENABLED"` on create. Campaigns / ad-groups / product-ads / portfolios accept `ENABLED` or `PAUSED`. To pause/archive after create, use the corresponding `propose_update_*` tool.
- **Budget shape**: campaigns use `budget.budget + budgetType`; portfolios use `budget.amount + policy`.
- **Update-body fields**: see the "Update-body fields per endpoint" allowlist above. The API 400s on any field outside that list — Zod schemas mirror the swagger.

# TitanConnect — Specialized Workflows

These are sub-patterns within the [Knowledge-First Workflow](./SKILL.md#knowledge-first-workflow). Every workflow below pulls knowledge tools FIRST or in parallel — pure-data flows are not allowed under the source-of-truth principle.

## Workflow 0: Account Setup (multiple Titan Tools accounts)

Applies only when authenticated via OAuth. API-key (`tk_*`) auth never sees these tools.

```
1. list_accounts → see linked Titan Tools accounts
2. switch_account({ accountId }) → activate one
   (refreshes the seller list to that account's stores; RESETS active seller)
3. continue with Workflow 1
```

To **link a new Titan Tools account**:

```
1. link_account → returns { authUrl, linkSessionId, completionCodeHint, expiresInSeconds }
2. Share authUrl with the user; they consent in Titan Tools and land on a TitanConnect success page
3a. (Local)  complete_link({ linkSessionId }) — poll if status='pending'
3b. (Remote, e.g. Claude.ai custom connector) ask the user to paste the
    completion code from the success page → complete_link({ completionCode })
4. switch_account({ accountId }) to start using the new account
```

The first account ever linked is the **default** (`isPrimary: true`) and cannot be deleted.

## Workflow 1: Seller Setup & Quick Health Check

```
DATA TRACK:
1. list_seller_accounts → set_active_seller → note mainCurrency
2. get_account_performance_summary (30 days) → sales overview
3. get_account_ppc_metrics (30 days)         → advertising overview
4. get_marketplaces + get_brands             → store context

KNOWLEDGE TRACK:
5. titan_lessons      (query: "account health" or "getting started")
6. community_feed     (query: relevant to any issues spotted)

→ Present onboarding summary with key metrics + Titan best practices,
  every claim cited.
```

## Workflow 2: Comprehensive PPC Audit

The `get_ppc_audit` tool returns a presigned download URL for a
pre-generated audit xlsx that already embeds Titan's curated heuristics.
**The audit data is NOT included inline** — only the URL. Hand it to the
user; for inline analysis, ask them to drag-drop the downloaded xlsx into
the next chat message (Claude.ai parses uploaded xlsx files natively).

For inline analysis WITHOUT requiring a file upload, fall through to the
synthetic chain (steps 2b onward) which composes the same picture from
metric tools.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_ppc_audit({})
   → If status='DONE': hand `fileUrl` to the user. Tell them the URL is
     valid for 5 minutes and that, for AI analysis, they should download
     and drag-drop the xlsx into the next chat message.
   → DO NOT attempt to fetch fileUrl yourself — your sandbox cannot
     reach the file host. The tool does not include audit contents
     inline; only metadata + URL.
   → If status='NONE'/'FAILED': tell the user to trigger a new audit
     from the Titan Tools dashboard, then continue with the synthetic
     fallback below if they want a same-turn analysis.
   → If status='PENDING': tell the user to retry in a few minutes.

   Synthetic fallback (when the user wants inline analysis without
   uploading the xlsx, or when status != DONE):
   2b. get_account_ppc_metrics (30 days)            → overall PPC health
   2c. get_account_ppc_metrics_by_campaign          → top + worst campaigns
   2d. get_ppc_search_terms_metrics                 → high spend + low conversion terms
   2e. get_ppc_placements_metrics                   → placement bid efficiency
   2f. get_ppc_negative_keywords                    → compare vs wasteful terms

3. get_ppc_change_history (narrow with campaignIds, levels, dateRange)
   → context for any flagged campaigns.

KNOWLEDGE TRACK:
4. titan_lessons     (query: "PPC optimization" or topic specific to flagged areas)
5. community_feed    (query: "ACoS reduction" or relevant topic)
6. fetch_framework("ppc_3_0")  (always — canonical for PPC tactics)

→ Report: health score, top optimizations, campaigns to pause, negatives
  to add — all grounded in Titan strategies, with a Sources section.
  If the user uploaded the xlsx, cite specific audit-sheet findings
  alongside the synthetic data.
```

Latency: get_ppc_audit is 1-2s; synthetic fallback adds ~5-10s end-to-end.

## Workflow 3: Product Portfolio Review

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_products_summary → full list with performance metrics
3. Identify top 5 by revenue, bottom 5 by performance
4. get_product_ppc_metrics (REQUIRED: pass asins=[<top product ASINs>]) → advertising efficiency
5. search_for_products → look up specific ASINs if needed

KNOWLEDGE TRACK:
6. titan_lessons   (query: "product optimization" or relevant topic)
7. community_feed  (query: relevant to portfolio findings)

→ Report: portfolio health, concentration risk, organic vs paid ratio —
  with Titan-backed recommendations and a Sources section.
```

## Workflow 7: Bulk Pause / Cleanup (writes — REAL MONEY)

For pausing or archiving many entities at once. Per-tool caps match Nexus's
empirical limits — 100 for SP/SB/SD structure writes, 500 for SP item-level
creates, 1000 for SP item-level updates (see each `propose_*` tool's
description for its specific cap). Bundle pause/cleanup writes per turn —
chain or bundle as needed.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. Discover the entities to pause:
   - Underperforming campaigns: search_for_ppc_campaigns() → filter response client-side by item.state==='enabled' → get_account_ppc_metrics_by_campaign({campaignIds:[…]}) → rank by ACoS
   - Wasteful keywords:    get_ppc_targets({type:'SP', adGroupIds:[id]}) or by matchTypes/targetTextPattern
   - Wasteful product ads: get_ppc_product_ads({adGroupIds:[id]})
   - Stale ad groups:      get_ppc_ad_groups({campaignIds:[id], status:'enabled'})

KNOWLEDGE TRACK:
3. titan_lessons      (query: "wasted spend" or "campaign cleanup")
4. fetch_framework("ppc_3_0")  (Phase-1 cleanup tactics)

WRITES (bundle in one response when natural; the host gates each call):
5. SP pauses:
   - propose_update_sp_campaign({campaigns:[{campaignId, state:'PAUSED'}]})
   - propose_update_sp_ad_group({adGroups:[{adGroupId, state:'PAUSED'}]})
   - propose_update_sp_keyword({keywords:[{keywordId, state:'PAUSED'}]})
   - propose_update_sp_target({targets:[{targetId, state:'PAUSED'}]})
   - propose_update_sp_product_ad({productAds:[{adId, state:'PAUSED'}]})
6. SB pauses (UPPERCASE state for campaigns/ad-groups/ads; lowercase for keywords/targets):
   - propose_update_sb_campaign({campaigns:[{campaignId, state:'PAUSED'}]})
   - propose_update_sb_ad_group({adGroups:[{adGroupId, state:'PAUSED'}]})
   - propose_update_sb_ad({ads:[{adId, state:'PAUSED'}]})
   - propose_update_sb_keyword({keywords:[{keywordId, adGroupId, campaignId, state:'paused'}]})
   - propose_update_sb_target({targets:[{targetId, adGroupId, campaignId, state:'paused'}]})
7. SD pauses (lowercase state everywhere):
   - propose_update_sd_campaign({campaigns:[{campaignId, state:'paused'}]})
   - propose_update_sd_ad_group({adGroups:[{adGroupId, state:'paused'}]})
   - propose_update_sd_product_ad({productAds:[{adId, state:'paused'}]})
   - propose_update_sd_target({targets:[{targetId, state:'paused'}]})

→ Acknowledge what you're about to do, then proceed. Inspect multi-status
  `error[]` after each call.
```

## Workflow 8: Negative-Keyword Hygiene (writes)

Add negative keywords to suppress wasteful search terms. Three variants — pick the right scope and product type.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_ppc_search_terms_metrics → identify high-spend / low-conversion terms
3. get_ppc_negative_keywords({campaignIds:[<targets>], statuses:['ENABLED']})
   → confirm not already negated

KNOWLEDGE TRACK:
4. titan_lessons   (query: "negative keywords")
5. fetch_framework("ppc_3_0")  (Phase 2 — Keyword Domination covers neg-kw strategy)

WRITES — pick by scope + ad type:
6a. SP campaign-level (block term across all ad groups in a campaign):
    propose_create_sp_campaign_neg_keyword({negativeKeywords:[{
      campaignId, keywordText, matchType:'NEGATIVE_EXACT'  // UPPERCASE
    }]})
6b. SP ad-group-level (block term in one specific ad group):
    propose_create_sp_ad_group_neg_keyword({negativeKeywords:[{
      campaignId, adGroupId, keywordText, matchType:'NEGATIVE_EXACT'
    }]})
6c. SB ad-group-level (NEW 2026-05-02 — DIFFERENT casing!):
    propose_create_sb_ad_group_neg_keyword({negativeKeywords:[{
      campaignId, adGroupId, keywordText, matchType:'negativeExact'  // camelCase!
    }]})
    Note: SB does NOT have campaign-level neg-kw create. Negative-keyword
    creates for SD do not exist as a tool.

REMEDIATION — pause / un-pause / archive existing neg-keywords (NEW 2026-05-05):
7. Find duplicates / stale terms: get_ppc_negative_keywords({statuses:['ENABLED']}).
8. SP campaign-level: propose_update_sp_campaign_neg_keyword({campaignNegativeKeywords:[{
     keywordId, state:'ARCHIVED'   // UPPERCASE
   }]})
9. SP ad-group-level: propose_update_sp_ad_group_neg_keyword({negativeKeywords:[{
     keywordId, state:'PAUSED'   // UPPERCASE; success-id is `negativeKeywordId`
   }]})
10. SB ad-group-level: propose_update_sb_ad_group_neg_keyword({negativeKeywords:[{
      keywordId, adGroupId, campaignId, state:'paused'   // lowercase!
    }]})

→ Acknowledge what you're about to do, then proceed — bundle the writes in
  one response when natural. Each call surfaces its own host approval.
```

## Workflow 9: Bid Optimization (writes)

Adjust bids for keywords / targets / ad groups based on metrics-driven recommendations.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_ppc_targets_metrics → find under/over-spending targets
3. get_sp_bid_recommendations(...) → suggested bids for keywords/targets
   (Live API read; p50 ≈ 40s; render a "calculating…" UI)

KNOWLEDGE TRACK:
4. titan_lessons      (query: "bid optimization")
5. fetch_framework("ppc_3_0")  (canonical bid-laddering rules)

WRITES — use the right tool for each entity type and product type:
6. SP keyword bid:    propose_update_sp_keyword({keywords:[{keywordId, bid:N}]})
7. SP target bid:     propose_update_sp_target({targets:[{targetId, bid:N}]})  // ASIN/category targets only
8. SP ad-group default bid: propose_update_sp_ad_group({adGroups:[{adGroupId, defaultBid:N}]})
9. SB keyword bid:    propose_update_sb_keyword({keywords:[{keywordId, adGroupId, campaignId, bid:N}]})  // lowercase state if also setting state
10. SB target bid:    propose_update_sb_target({targets:[{targetId, adGroupId, campaignId, bid:N}]})
11. SD ad-group default bid: propose_update_sd_ad_group({adGroups:[{adGroupId, defaultBid:N, state:'enabled'}]})  // lowercase
12. SD target bid:    propose_update_sd_target({targets:[{targetId, bid:N}]})  // lowercase state if also setting state

NOTE: SB ad-group does NOT have a `defaultBid` — that field is rejected by the API on
SB. Use bid changes at the keyword/target level instead.

→ Acknowledge the % change and expected ACoS / spend impact, then proceed.
```

## Workflow 9b: SP Placement Bid Modifiers (writes — REAL MONEY)

Triggered by: a member asking "boost / drop / clear my Top-of-Search modifier", "set my placement bids", or a placement-metrics audit showing TOS conversion is much better/worse than ROS.

```
KNOWLEDGE TRACK:
1. titan_lessons      (query: "placement modifiers" or "TOS bid adjustment")
2. fetch_framework("ppc_3_0")  (placement-bid laddering — TOS vs PP vs ROS rules)

DATA TRACK:
3. set_active_seller
4. search_for_ppc_campaigns({campaignIds:[...]}) → cache the current
   biddingStrategy + placementTos / placementPp / placementRos scalars.
   The strategy is REQUIRED on the write — Amazon `@IsNotEmpty()`.
5. (optional) get_ppc_placements_metrics → confirm the TOS/PP/ROS perf
   skew for the past N days before changing the modifier.

WRITE — single-campaign target via the dedicated tool:
6. propose_update_sp_campaign_placement_modifiers({
     campaignId,
     dynamicBidding: {
       strategy: '<existing biddingStrategy from step 4>',
       placementBidding: [{ placement: 'PLACEMENT_TOP', percentage: 25 }]
     }
   })

   Semantics (verified 2026-05-07):
   - Amazon merges placementBidding by placement key — placements not in the
     request are PRESERVED.
   - `percentage: 0` REMOVES the placement entry from the campaign.
   - `placementBidding: []` is a NO-OP (does NOT clear modifiers).
   - Omitting placementBidding entirely is also a NO-OP.
   - To clear ALL modifiers, send `0` for each currently-set placement.

   The tool reads the campaign before and after the write and only records
   SUCCESS in action_logs if the post-read shows the change actually landed
   (D2 mitigation). Watch for `WRITE_VERIFICATION_FAILED` or
   `ARCHIVED_NOT_EDITABLE` in the response.

→ Acknowledge per change: which placement, old %, new %, expected spend
  redistribution. The host approves the call.
```

## Workflow 11: Negative-Target Hygiene (writes — REAL MONEY)

Triggered by: search-term reports showing wasted spend on competitor ASINs, or the seller wanting to block a brand.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. Identify the targets to exclude. Either:
   - get_ppc_search_terms_metrics → high-spend / low-conversion competitor ASINs
   - take an explicit list of competitor ASINs / brands from the seller

KNOWLEDGE TRACK:
3. titan_lessons   (query: "competitor targeting" or "brand exclusion")
4. fetch_framework("ppc_3_0")   (Phase 2 — Defense covers neg-target strategy)

NARRATE FIRST — IN PLAIN ENGLISH:
5. Pick the level (campaign vs ad-group):
   - campaign-level applies to every ad group under that campaign (broader)
   - ad-group-level only applies to that one group (surgical)
6. State explicitly: number of campaigns/ad groups affected, the ASINs/brands
   to be blocked, what the seller is committing to.

WRITES:
7a. SP campaign-level (block ASIN/brand across an entire SP campaign):
    propose_create_sp_campaign_neg_target({campaignNegativeTargetingClauses:[{
      campaignId,
      expression: [{ type: 'ASIN_SAME_AS', value: 'B0XXXXXXXX' }],  // UPPERCASE_SNAKE; SINGULAR field
      state: 'ENABLED'
    }]})  // max 500/call
7b. SP ad-group-level (block in one specific ad group only):
    propose_create_sp_ad_group_neg_target({negativeTargetingClauses:[{
      campaignId, adGroupId,
      expression: [{ type: 'ASIN_SAME_AS', value: 'B0XXXXXXXX' }],
      state: 'ENABLED'
    }]})  // max 500/call
7c. SB ad-group-level — DIFFERENT shape:
    propose_create_sb_ad_group_neg_target({negativeTargets:[{
      campaignId, adGroupId,
      expressions: [{ type: 'asinSameAs', value: 'B0XXXXXXXX' }]    // PLURAL field! camelCase types! No state field!
    }]})  // max 100/call

8. After approval, inspect the multi-status `error[]`. Empty error[] is the only
   success. Note the success-id field per tool:
   - SP campaign-level → success.campaignNegativeTargetingClauseId (long-form)
   - SP ad-group-level → success.targetId (short-form)
   - SB ad-group-level → success.targetId

REMEDIATION — pause / un-pause / archive existing neg-targets:
9. SP campaign: propose_update_sp_campaign_neg_target({campaignNegativeTargetingClauses:[{
     targetId, state: 'ARCHIVED'   // UPPERCASE
   }]})
10. SP ad-group: propose_update_sp_ad_group_neg_target({negativeTargetingClauses:[{
      targetId, state: 'PAUSED'   // UPPERCASE
    }]})
11. SB ad-group: propose_update_sb_ad_group_neg_target({negativeTargets:[{
      targetId, adGroupId, state: 'archived'   // lowercase!
    }]})

→ Acknowledge per-item before proceeding (the exclusion commits across an
  entity tree). Bundle creates and state-only updates in one response when
  natural; rollback is to flip state back.
```

## Workflow 4: Knowledge-Only Research (no seller needed)

```
1. titan_lessons          → structured educational content on the topic
2. community_feed         → member discussions and real-world experiences
3. whatsapp_conversations → recent tactical discussions
4. fetch_framework        → applicable frameworks; pick from { "plog", "ppc_3_0", "states_and_drivers" } based on topic

→ Synthesize: key takeaways, real-world examples, latest insights,
  actionable steps. Sources section is mandatory even here.
```

## Workflow 5: Dual-Track Analysis (Data + Knowledge)

The combinatorial workflow — pull both tracks for the same question.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_account_performance_summary (30 days)  → sales metrics
3. get_account_ppc_metrics (30 days)          → PPC metrics
4. get_products_summary                       → identify key products
5. get_account_ppc_metrics_by_campaign        → campaign performance

KNOWLEDGE TRACK:
6. titan_lessons   → strategies relevant to the account's situation
7. community_feed  → similar seller experiences
8. fetch_framework → applicable frameworks (PPC 3.0 for tactics, States + Drivers for posture, PLOG for established-product focus)

SYNTHESIS:
→ Compare metrics against best practices from Titan Network content
→ Identify gaps between current performance and recommended strategies
→ Provide 5 prioritized action items backed by BOTH data and knowledge
→ Suggest relevant Titan Network lessons to study for each action item
→ Sources section listing every knowledge-tool result used
```

## Workflow 6: Keyword Research via SQP (Brand Analytics)

**Caveats — read first:**
- `searchQueryScore` is a RANK; sort ASC for top queries.
- `searchQueryVolume` is normalised; do NOT compare to external keyword tools.
- Purchase metrics use 24h attribution — low purchase share does NOT mean "doesn't convert". Use cart-add share.
- Empty results = ambiguous (not enrolled / no data / pre-W15).

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_products_summary → pick the target ASIN (or use the user's)
3. get_sqp_metrics with that ASIN, 4 most recent published ISO weeks,
   sortBy="searchQueryVolume" DESC
4. Also get_sqp_metrics with sortBy="searchQueryScore" ASC for top-ranked queries
5. Cross-check with get_ppc_targets + get_ppc_negative_keywords
   for paid-coverage gaps

KNOWLEDGE TRACK:
6. titan_lessons   (query: "keyword research" / "SQP analysis")
7. community_feed  (query: "search query performance")

→ Synthesize: Must-Add Exact Targets, Must-Add Negatives, Listing Fixes.
  Cite SQP rows AND Titan sources.
```

## Workflow 6.5: Out-of-Budget Diagnostic (read-only)

For "which of my campaigns are running out of budget?" / "is my budget pacing right?".

Uses two response fields added 2026-05: `outOfBudget` (boolean per campaign — `true` when the campaign hit its daily cap at least once in the window) and `avgDailySpend` (= spend / daysInWindow).

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_account_ppc_metrics_by_campaign({ …30d range, sortBy: 'spend', sortDirection: 'DESC' })
   → response items carry `outOfBudget` (boolean) and `avgDailySpend` (number).
   Flag any item where outOfBudget=true.
3. For each flagged campaign, fetch its budget cap via
   search_for_ppc_campaigns({ campaignIds: [id] }) — response gives `budget`.
   Pacing ratio = avgDailySpend / budget. >1.0 means the campaign is
   capped daily; close to 1.0 means it's pacing right at the limit.
4. (optional) get_ppc_change_history({ entityType: 'campaign',
   categories: ['STATUS', 'ADJUSTMENTS'], campaignIds: [flagged ids],
   …dateRange }) for operator-side context in the window — budget edits,
   status flips, schedule changes that may explain the saturation. NOTE:
   change_history records operator actions, NOT runtime ad-server events,
   so it will NOT surface the exact day(s) the cap was hit. The
   `outOfBudget` boolean is the source of truth for whether-it-happened.

KNOWLEDGE TRACK:
5. titan_lessons (query: "budget pacing" or "out of budget")
6. fetch_framework("ppc_3_0")  (Phase 2 — Keyword Domination covers
   budget posture for scale vs hold decisions)

→ Report: flagged campaigns, saturation ratio (avgDailySpend / cap),
  any operator-side budget edits or status flips in the window (from
  step 4, when surfaced), and the recommended action per Titan grounding
  (raise budget vs trim wasteful keywords vs hold).
```

## PPC Tool Selection by Goal

| Goal | Tools to use |
|------|--------------|
| Overall PPC health | `get_account_ppc_metrics` → `get_account_ppc_metrics_by_campaign` |
| Find wasted spend | `get_ppc_search_terms_metrics` (high spend + low conversion; narrow by `campaignIds` or `asins` — server-side, 2026-05) → cross-ref `get_ppc_negative_keywords` |
| Search terms for one campaign / ASIN | `get_ppc_search_terms_metrics({ adType: 'SP', campaignIds: [id], …dateRange })` or `{…, asins: [asin], …}` — server-side narrows (verified 2026-05-14) |
| Optimize bids | `get_ppc_targets_metrics` → `get_ppc_placements_metrics` |
| Product PPC review | `search_for_products` → `get_product_ppc_metrics` → `get_ppc_product_ads_metrics` |
| Campaign audit | `search_for_ppc_campaigns` (resolve IDs) → `get_account_ppc_metrics_by_campaign({ campaignIds })` → `get_ppc_ad_groups({ campaignIds: [id] })` |
| Targets in an ad group | `get_ppc_targets({ type: 'SP', adGroupIds: [id] })` — server-side narrow, returns the matching targets in one call (no pagination) |
| Search a target by keyword text | `get_ppc_targets({ type: 'SP', targetTextPattern: '%towel%' })` — SQL LIKE pattern (% wildcards) |
| Placement breakdown for one ASIN | `get_ppc_placements_metrics({ adType: 'SP', asins: [asin], …dateRange })` — server-side narrows per-placement clicks/spend (verified 2026-05-14). For per-campaign placement breakdown, fall back to `get_account_ppc_metrics_by_campaign` (response carries `placementTos/Pp/Ros` per campaign); `placements.campaignIds` is accepted but a no-op upstream as of 2026-05-14. |
| Find campaigns that hit their budget cap | `get_account_ppc_metrics_by_campaign({ …dateRange })` → filter response by `outOfBudget: true`. For the specific date(s) the cap was hit, layer `get_ppc_change_history({ entityType: 'campaign', categories: ['STATUS'], campaignIds: [id] })`. |
| Compare run-rate vs budget | `get_account_ppc_metrics_by_campaign({ …dateRange })` → response `avgDailySpend` (= spend / daysInWindow) vs each campaign's `budget` (from `search_for_ppc_campaigns`). Pacing ratio = avgDailySpend / budget — >1.0 means capped daily. |
| Negative keywords for one campaign | `get_ppc_negative_keywords({ campaignIds: [id] })` or by status: `{ statuses: ['ENABLED'] }` |
| Metrics for ASIN-bidding campaigns only | `get_account_ppc_metrics_by_campaign({ asins: [<ASINs>], …dateRange })` — server-side narrow |
| Metrics for one campaign type | `get_account_ppc_metrics_by_campaign({ adType: 'SD', …dateRange })` — server-side narrow to SD only |
| Pause one campaign | `propose_update_sp_campaign({campaigns:[{campaignId, state:'PAUSED'}]})` — UPPERCASE for SP/SB; lowercase for SD |
| Pause one keyword | `propose_update_sp_keyword({keywords:[{keywordId, state:'PAUSED'}]})` (SP) or `propose_update_sb_keyword({keywords:[{keywordId, adGroupId, campaignId, state:'paused'}]})` (SB lowercase + parent IDs) |
| Pause one target (NEW 2026-05-02) | SP: `propose_update_sp_target({targets:[{targetId, state:'PAUSED'}]})` (ASIN/category only). SB: `propose_update_sb_target({targets:[{targetId, adGroupId, campaignId, state:'paused'}]})`. SD: `propose_update_sd_target({targets:[{targetId, state:'paused'}]})` |
| Change one keyword's bid | `propose_update_sp_keyword({keywords:[{keywordId, bid:1.50}]})` (SP) |
| Add SB ad-group neg-keyword (NEW 2026-05-02) | `propose_create_sb_ad_group_neg_keyword({negativeKeywords:[{campaignId, adGroupId, keywordText, matchType:'negativeExact'}]})` — **camelCase** matchType, different from SP! |
| Pause an existing neg-keyword (NEW 2026-05-05) | SP campaign: `propose_update_sp_campaign_neg_keyword({campaignNegativeKeywords:[{keywordId, state:'PAUSED'}]})`. SP ad-group: `propose_update_sp_ad_group_neg_keyword(...)`. SB ad-group: `propose_update_sb_ad_group_neg_keyword(...)` (lowercase + parent IDs). |
| Block competing ASINs / brands from showing alongside my ads (NEW 2026-05-05) | SP campaign-level: `propose_create_sp_campaign_neg_target({campaignNegativeTargetingClauses:[{campaignId, expression:[{type:'ASIN_SAME_AS', value:'B0XXXXXXXX'}], state:'ENABLED'}]})`. SP ad-group: `propose_create_sp_ad_group_neg_target(...)`. SB: `propose_create_sb_ad_group_neg_target({negativeTargets:[{campaignId, adGroupId, expressions:[{type:'asinSameAs', value:'B0XXXXXXXX'}]}]})` — camelCase + PLURAL `expressions`! |
| Pause an existing neg-target (NEW 2026-05-05) | SP campaign: `propose_update_sp_campaign_neg_target({campaignNegativeTargetingClauses:[{targetId, state:'PAUSED'}]})`. SP ad-group: `propose_update_sp_ad_group_neg_target(...)`. SB: `propose_update_sb_ad_group_neg_target({negativeTargets:[{targetId, adGroupId, state:'paused'}]})` (lowercase + adGroupId). |
| Budget analysis | `get_ppc_portfolios_metrics` → `get_account_ppc_metrics_by_campaign` → `get_ppc_placements_metrics` |
| Metrics for specific campaigns | `search_for_ppc_campaigns` (resolve names → IDs) → `get_account_ppc_metrics_by_campaign({ campaignIds: [...] })` direct narrow, no pagination |
| Pre-generated PPC audit (curated by Titan) | `get_ppc_audit({})` — hand fileUrl to user; for inline analysis, user drags-drops the downloaded xlsx into chat |
| Where am I ranking on phrase X? (organic) | `get_keyword_ranks({ asin, weeks: 8 })` — NOT search-terms metrics (PPC ≠ organic); rank=301 means "not ranking" |
| Are these keywords relevant to my listing? | `get_keyword_relevancy({ asin })` — FIRST; relevancyScore 0-9; do not infer relevance from PPC search-terms metrics |
| What am I tracking + member notes? | `get_keyword_tracker_data({ asin })` — surfaces tags / labels / segments / member comments (operator-truth) |
| Pre-launch keyword strategy | `get_keyword_relevancy` → `get_keyword_tracker_data` → `get_keyword_ranks` (in this order; see Workflow 10) |

## Filtering metrics to specific campaigns

When the user asks about specific campaigns by name (e.g. "how is my Brand Defense campaign performing"), use `campaignIds` to narrow server-side rather than paging through results:

```
1. search_for_ppc_campaigns({ query: "Brand Defense" })  → returns matching campaigns with their campaignIds
2. get_account_ppc_metrics_by_campaign({
     currencyCode, startDate, endDate,
     campaignIds: [<id1>, <id2>, ...],
   })                                                     → server returns only those campaigns
3. titan_lessons (knowledge track)
4. Synthesize with Titan grounding
```

`campaignIds` is server-side filtered (verified 2026-04-30 against upstream). Do NOT fabricate campaign IDs; resolve them via `search_for_ppc_campaigns`, `get_ppc_change_history`, or a previous tool result this turn.

The same server-side narrowing applies to the structure tools as of 2026-04-30: `get_ppc_targets`, `get_ppc_ad_groups`, `get_ppc_product_ads`, and `get_ppc_negative_keywords` all accept `campaignIds`/`adGroupIds`/`targetIds`/`adIds` arrays (single ID? wrap it: `[id]`) and the API narrows results before pagination. No need to paginate-and-filter — pass the array, get the matching rows back in one call.

## Read-tool filter inventory (server-side narrowing)

For each PPC read tool, here are the filters the API accepts. Pass them and the server narrows before pagination — no need to fetch full pages and filter locally. Required fields are bold.

| Tool | Filters |
|------|---------|
| `get_account_ppc_metrics_by_campaign` | `campaignIds?`, `asins?`, `adType?` ('SP'/'SB'/'SBV'/'SD'), `sortBy?`, `sortDirection?` (no status filter — call `search_for_ppc_campaigns()` first, then filter response items client-side by `item.state`) |
| `get_ppc_portfolios_metrics` | `portfolioNamePattern?`, `sortBy?`, `sortDirection?` |
| `get_ppc_product_ads_metrics` | `asins?`, `adType?` ('SP'/'SD'/'SBV'), `sortBy?`, `sortDirection?` |
| `get_ppc_targets_metrics` | `adType?` ('SP'/'SB'/'SBV'/'SD'), `sortBy?`, `sortDirection?` |
| `get_ppc_placements_metrics` | **`adType: 'SP'`**, `asins?` (verified 2026-05-14), `campaignIds?` (currently a server-side no-op upstream; field accepted, results unchanged), `sortBy?`, `sortDirection?` |
| `get_ppc_search_terms_metrics` | **`adType: 'SP'`**, `campaignIds?` (verified 2026-05-14), `asins?` (verified 2026-05-14), `sortBy?`, `sortDirection?` |
| `get_product_ppc_metrics` | **`asins`** (non-empty) |
| `get_product_performance_summary` | **`asins`** (non-empty) |
| `search_for_ppc_campaigns` | `query?`, `campaignIds?`, `types?` (no `status` — upstream rejects with 400 as of 2026-05-15; filter response items client-side by `item.state`) |
| `get_ppc_portfolios` | `portfolioNamePattern?`, `portfolioIds?`, `statuses?` |
| `get_ppc_ad_groups` | `campaignIds?`, `adGroupIds?`, `types?`, `adGroupNamePattern?`, `status?` |
| `get_ppc_product_ads` | `campaignIds?`, `adGroupIds?`, `adIds?`, `types?`, `query?` (ad-name pattern), `status?` |
| `get_ppc_targets` | **`type`** ('SP'/'SB'/'SD'), `campaignIds?`, `adGroupIds?`, `targetIds?`, `matchTypes?` (UPPERCASE), `targetTextPattern?` (SQL LIKE, use % wildcards), `status?` |
| `get_ppc_negative_keywords` | `campaignIds?`, `adGroupIds?`, `negativeKeywordIds?`, `matchTypes?` (UPPERCASE), `statuses?` (UPPERCASE), `keywordTextPattern?` |
| `get_ppc_change_history` | **`currencyCode`**, `entityType?`, `categories?`, `campaignIds?`, `asins?`, `changeTypes?` |

### Filtering metrics by campaign status

`get_account_ppc_metrics_by_campaign` does NOT have a `status` parameter. The upstream metrics response doesn't carry a status field on items. Status filtering routes through `search_for_ppc_campaigns` instead.

When the user asks for metrics on enabled / paused / archived campaigns:

```
1. search_for_ppc_campaigns({ limit: 50 })  → page through if there are many → filter client-side by item.state==='enabled' (upstream rejects a status request param with 400 as of 2026-05-15)
   (collect all enabled campaignIds; for an account with ~363 enabled campaigns, that's 8 pages)
2. get_account_ppc_metrics_by_campaign({
     currencyCode, startDate, endDate,
     campaignIds: [<all collected ids>],
     sortBy: "spend", sortDirection: "desc",
     limit: 5,                            ← if user wants top N
   })                                                            → server narrows + sorts
3. titan_lessons (knowledge track)
4. Synthesize with Titan grounding
```

Alternative pattern when "top N by spend regardless of status" is acceptable: pull the unfiltered top page first, then verify each top result's status via `search_for_ppc_campaigns({query: name})` lookups and check the returned item's `state` field client-side (the upstream endpoint does not accept a `status` request parameter as of 2026-05-15). Both are valid; the first is cheaper when the status set is small relative to the full account.

---

## Keyword Research Workflows (titan-connect-only tools)

The following workflows use the four titan-connect-only tools
(`get_ppc_audit`, `get_keyword_ranks`, `get_keyword_tracker_data`,
`get_keyword_relevancy`). They have different latency / sentinel
behavior than the metric tools above — see the
`<keyword_and_audit_tools>` block in MCP_INSTRUCTIONS for the
cross-cutting rules (cold-pool latency up to 30s on first call,
sentinel values like rank=301, internal-ID hygiene, etc.).

### Workflow 10: Keyword Strategy for an ASIN

For pre-launch / re-launch / "what should I target?" questions. **Always
start with relevancy** — PPC search-terms metrics are spend-weighted, not
relevance-weighted, and bias toward "what's getting traffic" instead of
"what should be."

```
DATA TRACK (do all 3 in this order — they compose into the strategy):
1. list_seller_accounts → set_active_seller
2. get_keyword_relevancy({ asin, topN: 100 })
   → identifies which phrases ARE relevant to this listing
   (relevancyScore is integer 0-9; the Negative datasets correctly
    return [] with a deferral message — that's by design, not an error).
3. get_keyword_tracker_data({ asin })
   → identifies what's already tracked (with tags, segments, member
    comments). Comments are operator-truth — cite verbatim where
    relevant.
4. get_keyword_ranks({ asin, weeks: 8, topN: 25 })
   → identifies current organic performance on tracked phrases.
   FIRST CALL CAN TAKE UP TO 30s — wait for it, don't bail.

KNOWLEDGE TRACK:
5. titan_lessons (query: "keyword research" or relevant)
6. fetch_framework("ppc_3_0")  (Phase 1 / 2 / 3 keyword strategy)

CROSS-REFERENCE (the synthesis step):
- Relevant + not tracked = gap to add to tracker
- Tracked + not ranking (rank=301 sentinel) = PPC opportunity
- Tracked + ranking + low relevancy = candidate to drop
- Member comments from step 3 outweigh model speculation

→ Report: 3-tier list (priority/secondary/parking) with REASONS, sourced
  to the data tool that produced each insight + Titan framework citation.
```

Latency: 3 tool calls, ~30-40s on cold pool first time, 10-15s warm.

### Workflow 11: Rank Health Check

For "where am I ranking?" / "is my rank trending up or down?" questions.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_keyword_ranks({ asin, weeks: 8, topN: 25 })
   → per-phrase current rank + 8-week daily history.
   Rank=301 sentinel means "not ranking" (NOT actual position 301).
3. For phrases with concerning trends:
   get_keyword_tracker_data({ asin })
   → check tags / segment membership / member comments for context.
   Member comments often explain rank movement (e.g. "sponsored rank
   dropped after PPC pause") — these are first-party context.
4. For ranks that look unexpectedly low: cross-check with
   get_keyword_relevancy({ asin, topN: 100 })
   → low-relevance phrases are expected to rank poorly; high-relevance
   phrases ranking poorly are PPC opportunities.

KNOWLEDGE TRACK:
5. titan_lessons (query: "rank tracking" / "organic rank")
6. fetch_framework("ppc_3_0")  (PPC tactics for boosting organic rank)

→ Report: top phrases by current rank, trend direction (improving /
  declining / not ranking), and recommended action with Titan grounding.
```

Latency: 1-3 tool calls, up to 30s on cold pool first time.

### Workflow 12: Tracker Inventory Audit

For "what am I tracking?" / "is my tracker setup healthy?" questions.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_keyword_tracker_data({ asin, topN: 200 })
   → full tracker config: phrases, tags, labels, segments, comments.
   Use NAMES (segments[].name, labels[].name) in user-facing prose,
   never IDs.
3. (optional) get_keyword_relevancy({ asin, topN: 200, includeUnfiltered: true })
   → check which tracked phrases are actually relevant to the listing.
4. (optional) get_keyword_ranks({ asin, weeks: 4 })
   → check which tracked phrases are actually performing.

CROSS-REFERENCE:
- Tracked + low relevancy + not ranking = candidates to remove
- Tracked + high relevancy + amazonChoice (is_amazon_choice) = wins to amplify
- Stale comments (comment_date > 90 days old) = outdated context

→ Report: tracker hygiene summary, candidates to add/remove, surface
  member comments that are still load-bearing.
```

### Workflow 13: Hour-of-day / weekday pattern detection (AMS)

For "what's my best hour to advertise?", "are weekend campaigns
underperforming?", or any dayparting hypothesis.

AMS is available for all regions where the seller is subscribed via
Amazon Ads. The seller's account-level timezone (set at Amazon-Ads-link
time, based on their main country) determines what the hour values mean.

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. get_ppc_ams_metrics({
     startDate, endDate, currencyCode,
     groupBy: 'hour'    // or 'day' for weekday breakdown
   })
   → 24 hour-of-day buckets summed across the window (or 7 weekday
     buckets). Use a 30–90 day window for stable patterns; shorter
     windows are noisy.
   → Hour buckets are in the seller's account-level local time (US→PT,
     DE→CET, UK→GMT/BST — based on their configured main country, not
     per-marketplace).
   → Sales/orders are bucketed by CONVERSION hour (purchase time), not
     click hour. Spend/clicks/impressions are bucketed by ad-event hour.
     Attribution windows: SP=7d, SB+SD=14d.
   → Near-real-time: endDate can be today (NOT subject to the 2-day
     daily-PPC-metrics lag rule).

3. INTERPRET ZERO BUCKETS — zero is NOT a failure signal by default.
   Most often it indicates the operator's advertising schedule. Order:
   a. If a contiguous block of zero hours is bordered by non-zero hours
      (e.g. zero from 11 PM–12 PM, non-zero from 1 PM onward), this is
      almost certainly DELIBERATE DAYPARTING. ASK the operator: "Are
      you running ads only between X and Y?" Don't recommend budget
      changes from this pattern.
   b. If EVERY bucket is zero across the window, call get_account_ppc_metrics
      for the same window:
        - account spend > 0 AND AMS all-zero → seller likely lacks an
          Amazon Marketing Stream subscription. Tell them to enable
          AMS on the Amazon Ads side.
        - account spend == 0 AND AMS all-zero → genuine zero traffic
          OR window pre-dates the seller's AMS subscription start
          (Amazon doesn't backfill historical AMS data).
   c. NEVER narrate "you ran no ads" or "your budget exhausted" as a
      finding from AMS alone without operator confirmation of their
      schedule.

4. Identify peak/trough buckets by sorting on the metric that matches
   the operator's actual question:
   - impressions → when do customers SEE my ads?
   - clicks → when do they ENGAGE?
   - sales/orders → when do they BUY (note: this is conversion-hour,
     so the "peak" may be hours after the click-hour peak)?
   - acos → when am I MOST PROFITABLE (low ACoS hours, not high-volume)?

5. For drill-down ("which campaigns drive the 7 AM peak?"), AMS does
   NOT support cross-tool composition at hour granularity. Use AMS to
   identify the time-of-day signal, then drop to daily resolution via
   get_account_ppc_metrics_by_campaign for the same window. Hour-of-day
   on the campaign-level surface is NOT in this upstream round.

KNOWLEDGE TRACK:
6. (optional) fetch_framework('ppc_3_0') — AMS gives raw hour-of-day
   data; the operator's tactical response (dayparting, bid modifiers,
   ad-group hibernation) belongs in the Titan playbook layer, not the
   raw data layer.

→ Report: peak hour(s) / day(s) with absolute and relative numbers,
  with the operative timezone named (e.g. "7 AM Pacific" not "7 AM"),
  and any inferred dayparting clearly attributed to the operator's
  schedule (after confirming with them) — not labelled as a "leak".
```

Latency: 1 tool call, ~6s for the 365-day window probe.

Latency: 1-3 tool calls, 1-30s depending on cold pool.