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.

## Prefer live writes over sheets

When a change can be made with the `propose_*` tools (and `tools:write` is granted), **make it live** — call the tool. Do **not** default to generating a bulk XLSX/CSV upload sheet for the user to apply by hand when a live write is available: the live path is approval-gated, auditable, and applies immediately, whereas a sheet is an un-tracked manual step that often never gets uploaded.

Fall back to producing a sheet only when:
- the user **explicitly** asks for a downloadable file, or
- the operation isn't covered by the `propose_*` surface (e.g. a bulk operation with no corresponding write tool), or
- `tools:write` isn't granted (no write access on this connection).

## 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

By default, `marketplace` resolves to the active seller's default storefront (`mainSalesChannel`, e.g. `"Amazon.com"`, `"Amazon.co.uk"`) — so for a single-marketplace seller, **omit it**.

For a multi-marketplace account (one seller spanning e.g. Amazon.co.uk + Amazon.de), to act on a **non-default** marketplace:

1. Call `get_marketplaces` to list the seller's connected storefronts.
2. Pass the exact storefront string (e.g. `"Amazon.de"`) as `marketplace` on the `propose_*` / `get_sp_bid_recommendations` / `propose_update_sp_campaign_placement_modifiers` / `get_ppc_negative_targets` call.

Omit `marketplace` to use the default. A value that isn't one of the seller's connected marketplaces returns `MARKETPLACE_NOT_AVAILABLE` (with the valid list in `available`) — re-issue with a listed storefront. Campaign / ad-group / keyword IDs are marketplace-specific: target the marketplace the IDs belong to.

## Keyword Relevancy dataset writes (`account:write` — NOT Amazon Ads)

Five writes touch the seller's Titan Tools **Keyword Relevancy datasets** instead of their Amazon Advertising account: `propose_create_relevancy_dataset`, `propose_add_relevancy_dataset_asins`, `propose_remove_relevancy_dataset_asins`, `propose_relevancy_ranking_update`, `propose_relevancy_cache_purge`. They behave differently from the Amazon Ads writes above:

- **No dry-run, no delete.** Upstream `/v1/tools/relevancy/*` has no dry-run, so these execute the moment the host approves — in EVERY environment, including staging. A created dataset CANNOT be removed via the API (there is no delete endpoint). Confirm intent before calling, and label throwaway/test datasets clearly (they leave permanent residue).
- **Not multi-status.** They return the raw `{ datasetId }` (create — a NUMBER, e.g. `187798`) or `{ success: true }` (add/remove/ranking-update/cache-purge), plus a `correlationId`. There is no `success[]`/`error[]` array — a thrown upstream error surfaces as a structured `{ error, message }`.
- **Auth is handled server-side** — no re-link needed. The write runs under the user's OAuth grant when it carries write access, otherwise it transparently falls back to the server credential. (Upstream requires `account:write`; the OAuth client cannot grant that scope yet — raised with upstream 2026-06-11 — so the server-credential fallback is currently the active path.)
- **Body shapes** (see `WIRE_FORMATS.md`): create takes `{ datasetName, asin, competitorAsins:[1-10] }`; add/remove take `{ dataSetId, asins:[1-10] }` — note `dataSetId` is **camelCase** (capital S), unlike the `datasetId` the read tool returns. sellerId + marketplace are injected from the active seller.
- **`propose_relevancy_ranking_update` is a REAL recompute, once per 24h, ASYNC.** It returns `{ success }` immediately but the recompute runs in the background — poll `get_relevancy_ranking_status` (`{ ongoing }`) until false, then re-read `get_keyword_relevancy` / `get_keyword_families`. Body: `{ datasetId }` + injected marketplace. **`propose_relevancy_cache_purge`** drops the dataset's cached ranking results (`{ datasetId }` — **NO marketplace**); returns `{ success }`.

Result presentation: same natural-prose rule as the Amazon Ads writes — e.g. "Created a relevancy dataset for B0… seeded with 3 competitors." Never surface the raw envelope or correlationId.

## Keyword Rank Tracker writes (`account:write` — NOT Amazon Ads)

Five writes manage what the seller tracks in the **Keyword Rank Tracker** (`/v1/krt/*`): `propose_track_keywords`, `propose_untrack_keywords`, `propose_set_keyword_label`, `propose_add_keyword_tag`, `propose_remove_keyword_tags`. They behave differently from both the Amazon Ads writes and the relevancy writes:

- **No dry-run, but REVERSIBLE.** Upstream has no dry-run (they execute on approval, every environment), but each is undoable: untrack reverses track, a `null` label clears a label, remove-tag reverses add-tag. The HIL copy says "REAL, IMMEDIATE, but reversible" — distinct from the relevancy writes' "IRREVERSIBLE".
- **Partial-success batches (NOT multi-status).** They return `{ items: [{ key, status, error? }], summary: { succeeded, skipped, failed } }` + a `correlationId`. This is NOT the Amazon Ads `success[]`/`error[]` shape. Inspect each item: `propose_track_keywords` per-item status ∈ `SUCCESS | ALREADY_TRACKED | ERROR` (ALREADY_TRACKED counts under `summary.skipped`); the others ∈ `SUCCESS | ERROR`. The connector writes one `action_logs` row per item.
- **`propose_track_keywords` does NOT return the new id.** `items[].key` echoes the *phrase*, not the new `keywordRankTrackerId`. To label/tag a just-added keyword, re-call `get_keyword_ranks` (with `search`) to resolve its id first.
- **Auth is handled server-side** — same user-OAuth-first → server-credential fallback as the relevancy writes.
- **Body shapes** (see `WIRE_FORMATS.md`): `propose_track_keywords` is asin-scoped — `{ asin, phrases:[1-500] }` with marketplace injected from the active seller (US/DE/UK/CA only). The other four are by-id and take NO marketplace: `propose_untrack_keywords` `{ keywordRankTrackerIds:[1-500] }`; `propose_set_keyword_label` `{ keywordRankTrackerIds, labelId }` (`labelId: null` clears); `propose_add_keyword_tag` `{ keywordRankTrackerIds, tag }`; `propose_remove_keyword_tags` `{ tagIds }`. sellerId is injected from the active seller.

Result presentation: natural prose — e.g. "Now tracking 3 new keywords (1 was already tracked)." Never surface the raw envelope, item statuses verbatim, or correlationId.

## Keyword comment writes (`account:write` — NOT Amazon Ads)

Three writes manage member **comments** (notes) on a tracked keyword (`/v1/krt/comments`): `propose_add_keyword_comment`, `propose_edit_keyword_comment`, `propose_remove_keyword_comment`. They differ from the KRT keyword writes above:

- **SINGLE-ITEM, NOT partial-success batches.** add → `{ comment, count }` (the keyword's active-comment count after insert); edit → `{ comment }`; remove → `{ success }` — each plus a `correlationId`. There is no `items[]`/`summary`. The connector writes ONE `action_logs` row.
- **REVERSIBLE (add ↔ remove), no dry-run.** A `null` is never returned for a missing item — a foreign/unknown `keywordRankTrackerId` (add) or `commentId` (edit/remove) returns an upstream **404**. Surface that as "that keyword/comment isn't yours" — never fabricate success.
- **`propose_add_keyword_comment` returns a `commentId`** (after the connector's `id`→`commentId` shaping). Use it for a later `propose_edit_keyword_comment` / `propose_remove_keyword_comment`. **Edit changes the TEXT ONLY** — there is no editable `commentDate`.
- **By-id — NO marketplace.** add: `{ keywordRankTrackerId, commentDate (YYYY-MM-DD), commentText }`; edit: `{ commentId, commentText }`; remove: `{ commentId }`. sellerId is injected from the active seller. The `keywordRankTrackerId` comes from a `get_keyword_ranks` row or a `get_keyword_segments` segment.

Result presentation: natural prose — e.g. "Added your note to that keyword." Never surface the raw envelope, commentId, or correlationId.

## 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 |
| `propose_create_relevancy_dataset` | ✅ | **NEW 2026-06-11.** `account:write`. `{datasetName, asin, competitorAsins:[1-10]}`. Returns numeric `datasetId`. NO dry-run, NO delete. |
| `propose_add_relevancy_dataset_asins` | ✅ | **NEW 2026-06-11.** `{dataSetId, asins:[1-10]}` (camelCase `dataSetId`). Returns `{success}`. |
| `propose_remove_relevancy_dataset_asins` | ✅ | **NEW 2026-06-11.** `{dataSetId, asins:[1-10]}`. Returns `{success}`. |
| `propose_track_keywords` | ✅ | **NEW 2026-06-15.** `account:write`. asin-scoped: `{asin, phrases:[1-500]}` + injected marketplace (US/DE/UK/CA). Partial-success `{items,summary}`; per-item SUCCESS/ALREADY_TRACKED/ERROR. `items[].key`=phrase (NOT the new id). REVERSIBLE. |
| `propose_untrack_keywords` | ✅ | **NEW 2026-06-15.** by-id: `{keywordRankTrackerIds:[1-500]}` (no marketplace). Reverses track. |
| `propose_set_keyword_label` | ✅ | **NEW 2026-06-15.** PATCH. `{keywordRankTrackerIds, labelId}` — `labelId:null` clears. |
| `propose_add_keyword_tag` | ✅ | **NEW 2026-06-15.** `{keywordRankTrackerIds, tag}` (≤120 chars; creates tag if new). |
| `propose_remove_keyword_tags` | ✅ | **NEW 2026-06-15.** `{tagIds}` (from a `get_keyword_ranks` row's `tags[].tagId`). |
| `propose_add_keyword_comment` | ✅ | **NEW 2026-06-19.** `account:write`. SINGLE-ITEM (not batch): `{keywordRankTrackerId, commentDate, commentText}` (no marketplace) → `{comment, count}`; comment carries a `commentId`. REVERSIBLE; 404 on a foreign id. |
| `propose_edit_keyword_comment` | ✅ | **NEW 2026-06-19.** `{commentId, commentText}` — text ONLY, no date → `{comment}`. 404 on a foreign/unknown id. |
| `propose_remove_keyword_comment` | ✅ | **NEW 2026-06-19.** `{commentId}` → `{success}`. Reverses add. 404 on a foreign/unknown id. |
| `propose_relevancy_ranking_update` | ✅ | **NEW 2026-06-19.** `account:write`. `{datasetId}` + injected marketplace → `{success}`. REAL recompute, once/24h, ASYNC — poll `get_relevancy_ranking_status` (`{ongoing}`). |
| `propose_relevancy_cache_purge` | ✅ | **NEW 2026-06-19.** `{datasetId}` (**NO marketplace**) → `{success}`. Drops cached ranking results. |

### 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` (Amazon Ads writes only — the relevancy dataset writes auto-fall-back to the server credential and do not surface this) | Ask the user to re-link (`link_account`) with the missing 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. **Marketplace defaults to the active seller's storefront** — omit `marketplace` unless you're targeting a connected non-default marketplace, in which case pass its exact storefront string from `get_marketplaces` (see "Marketplace handling").
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.

## Alert read-state actions (OAuth `tools:write` — NOT Amazon Ads writes)

`mark_alerts` and `mark_alerts_by_filter` change an alert's READ/UNREAD state. They are write tools (OAuth `tools:write`/`mcp` scope, same gating as the `propose_*` tools above) but they are a different class entirely: **no money, no live-ad change, no `dryRun` field, no multi-status `success[]`/`error[]` envelope.** They execute immediately (not proposals) and are fully **reversible** — re-mark with the opposite `state` to undo. The `propose_*` dryRun / multi-status / "Always Allow" protocol does NOT apply to these two tools.

| Tool | Effect |
|------|--------|
| `mark_alerts` | Mark specific alerts read/unread. Params: `state` (READ/UNREAD), `alerts` (array of `{ alertId, alertDate }`, max 500). `alertId` = `items[].id` from `get_alerts`; `alertDate` = the YYYY-MM-DD slice of that alert's `datetime`. Returns `{ results: [{ id, status }] }` with per-alert `SUCCESS`/`ERROR` — partial success, one bad id does not fail the batch. |
| `mark_alerts_by_filter` | Bulk-mark every alert in a window + filter read/unread. Params: `state` (READ/UNREAD), `startDate`, `endDate` (≤180 days), + the same filters as `get_alerts`. Returns `{ updatedCount, failedDates }` — `updatedCount` is alerts whose flag actually changed; re-issue to retry `failedDates` (idempotent). Can be slow over wide ranges. |

Confirm intent before bulk-marking a wide range, but no per-item approval dance is needed — these are low-stakes and reversible. Read the alerts first via `get_alerts` (a data tool) to get the `alertId`/`alertDate` pairs.

# 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.

## `create_custom_report` / `get_custom_report` — wire format (async report generation)

Internal-api, x-api-key. Read-style tools (no approval prompt). `sellerId` is auto-resolved from the active seller and `deliveryMethod` is always `link` — neither is model-facing; the tool injects them, so they are omitted from the bodies below.

### `create_custom_report` body

Top-level: `marketplaces` (array of storefront URLs e.g. `["Amazon.com"]` — NOT marketplace IDs; defaults to the active seller's `mainSalesChannel` when omitted), `brands?`, `asins?`, `updateFrequency` (`ONCE` default | `DAILY` | `WEEKLY` | `MONTHLY` | `QUARTERLY` | `YEARLY`), and `reportConfig`. `reportConfig` = `currencyCode`, `reportType`, `dateRangeType`, `fileType` (`CSV`|`XLSX`), optional `dateRangeConfig`. Returns `{ reportId }`; the report generates asynchronously — poll with `get_custom_report`.

**Per-`reportType` date-range matrix** (wrong combo → upstream 400):

| reportType | allowed `dateRangeType` | `dateRangeConfig` |
|---|---|---|
| DASHBOARD_METRICS / DST_METRICS / PPC_SEARCH_TERM / PPC_CAMPAIGNS | CUSTOM_DATES, LAST_MONTH, LAST_YEAR, LAST_7_DAYS, LAST_30_DAYS, LAST_60_DAYS | CUSTOM_DATES → `startDate`+`endDate` (no `periodicity`); presets → omit |
| DASHBOARD_PROFIT_AND_LOSS_METRICS | CUSTOM_DATES, LAST_12_MONTHS_BY_MONTH, THIS_YEAR_BY_MONTH, LAST_YEAR_BY_MONTH, LAST_3_MONTHS_BY_WEEK, LAST_30_DAYS_BY_DAY | CUSTOM_DATES → `startDate`+`endDate`+`periodicity` (DAY/WEEK/MONTH); presets → omit |
| PPC_AUDIT | LAST_8_FULL_WEEKS only | omit |
| SEARCH_QUERY_PERFORMANCE | CUSTOM_DATES_SQP only | `periodicity`(WEEK/MONTH/QUARTER)+`year`+`periodRange`; NO `startDate`/`endDate`; exactly 1 marketplace + 1 ASIN; ONCE only |

Global: `CUSTOM_DATES` / `CUSTOM_DATES_SQP` require `updateFrequency: ONCE`. Day-count rules (P&L DAY ≤ 32d / WEEK ≥ 9d / MONTH ≥ 33d) and the SQP year-floor (≤16 months) + fully-completed-period checks are enforced upstream and surface as a readable 400.

Preset range (dashboard metrics, last 7 days, recurring daily):

```json
{
  "marketplaces": ["Amazon.com"],
  "updateFrequency": "DAILY",
  "reportConfig": {
    "currencyCode": "USD",
    "reportType": "DASHBOARD_METRICS",
    "dateRangeType": "LAST_7_DAYS",
    "fileType": "XLSX"
  }
}
```

Custom dates (P&L, monthly buckets, one-time):

```json
{
  "marketplaces": ["Amazon.com"],
  "updateFrequency": "ONCE",
  "reportConfig": {
    "currencyCode": "USD",
    "reportType": "DASHBOARD_PROFIT_AND_LOSS_METRICS",
    "dateRangeType": "CUSTOM_DATES",
    "fileType": "CSV",
    "dateRangeConfig": { "startDate": "2026-01-01", "endDate": "2026-04-30", "periodicity": "MONTH" }
  }
}
```

SQP (weekly — exactly one ASIN + one marketplace, one-time):

```json
{
  "marketplaces": ["Amazon.com"],
  "asins": ["B07PARENT01"],
  "updateFrequency": "ONCE",
  "reportConfig": {
    "currencyCode": "USD",
    "reportType": "SEARCH_QUERY_PERFORMANCE",
    "dateRangeType": "CUSTOM_DATES_SQP",
    "fileType": "XLSX",
    "dateRangeConfig": { "periodicity": "WEEK", "year": 2026, "periodRange": "W18" }
  }
}
```

`periodRange` shape by periodicity: WEEK → `"W18"`, MONTH → English month name `"April"`, QUARTER → `"Q2"`.

### `get_custom_report` body + status vocabulary

Body: `{ "reportId": "<from create>" }`. **Single poll** — on `IN_PROGRESS` you re-invoke; the tool does NOT loop internally.

Response `status` ∈ `IN_PROGRESS | DONE | FAILED | CANCELLED | DELETED | NO_DATA_AVAILABLE`; `downloadUrl` is non-null ONLY on `DONE`.

| status | meaning | action |
|---|---|---|
| IN_PROGRESS | still generating | call again in ~5-25s |
| DONE | ready | hand the operator `downloadUrl` |
| NO_DATA_AVAILABLE | no data for the parameters | suggest a different range / marketplace / ASIN |
| FAILED / CANCELLED / DELETED | terminal | create a new report |

`downloadUrl` = `https://app.titantools.com/reports/download?source=<signed token>` — a **self-authenticating bearer link**: it opens with no Titan Tools login and has no per-link expiry. Treat it as a secret — hand it to the operator, do not post it anywhere public, and do **NOT** fetch it yourself (URL-only delivery; fetching pulls the whole file into context).

**Latency**: DASHBOARD / DST / PPC report types reach `DONE` within seconds; `SEARCH_QUERY_PERFORMANCE` ~25s. A recurring `create` also materializes the first run immediately, so the poll behaves identically to a one-time report.

**No lifecycle CRUD**: upstream exposes only create + download. A created report — including a recurring schedule — cannot be listed, edited, or cancelled via these tools. Confirm a recurring schedule with the operator BEFORE creating it.

## `get_awd_inventory` / `get_awd_inbound_shipments` / `get_awd_replenishment_orders` — wire format (AWD live reads, US-only)

Live SP-API AWD proxies. Read-style tools (no approval prompt). `sellerId` is auto-resolved from the active seller and `marketplace` is **forced to `Amazon.com`** (AWD is US-only — never derived from `mainSalesChannel`); neither is model-facing. The only model-facing inputs are the optional Amazon filters + `nextToken` (see the SKILL tool table). The response is Amazon's payload **verbatim, including `nextToken`** — pagination is the caller's responsibility (pass `nextToken` back; the tool does NOT auto-walk).

**3-state response signal** (the body of a 403/404 is an identical-looking Amazon `Unauthorized` envelope — we classify on HTTP status, so trust the `code`):

| Input / situation | Server response | What it looks like |
|---|---|---|
| Enrolled US seller, has data | 200 | `{ inventory: [...] }` / `{ shipments: [...] }` / `{ orders: [...], nextToken? }` |
| Enrolled US seller, nothing right now | 200 | `{ inventory: [] }` (etc.) — enrolled, no current stock/shipments/orders — **NOT "no AWD"** |
| Not re-authed for the AWD role | 403 → `AWD_NOT_ENROLLED` | `{ error: true, code: "AWD_NOT_ENROLLED", message }` — actionable: ask the operator to re-authorise Titan Tools |
| No US (Amazon.com) connection | 404 → `AWD_NO_US_CONNECTION` | `{ error: true, code: "AWD_NO_US_CONNECTION", message }` — US-only gating |

Real shapes (probe-verified gomezfit / A20KO674Z5KLVG, 2026-05-30):

```jsonc
// get_awd_inventory (details=SHOW) — 55 SKUs, no nextToken when one page
{ "inventory": [
  { "sku": "3D Mesh3-Xlong", "totalOnhandQuantity": 0, "totalInboundQuantity": 250,
    "inventoryDetails": { "availableDistributableQuantity": 0, "replenishmentQuantity": 0, "reservedDistributableQuantity": 0 } }
] }
// get_awd_inbound_shipments — 101 shipments
{ "shipments": [
  { "shipmentId": "STAR-S3ZWFTUQR4ZNW", "orderId": "STAR-QYDAM5GK5VYWW", "externalReferenceId": "wfd695d266-…",
    "shipmentStatus": "RECEIVING", "createdAt": "2026-04-24T01:23:57.905Z", "updatedAt": "2026-05-29T18:22:35.313Z" }
] }
// get_awd_replenishment_orders — 100 orders, paginates via nextToken
{ "orders": [
  { "orderId": "repl-2acb32f8-…", "status": "SUCCESS", "confirmedOn": "2026-05-23T19:01:22.139Z",
    "eligibleProducts": [{ "sku": "Kickstand Pad Red", "quantity": 150 }],
    "outboundShipments": [{ "shipmentId": "repl-ship-…", "shipmentStatus": "DELIVERED" }],
    "distributionIneligibleReasons": [] } ],
  "nextToken": "eyJ…" }
```

**Field semantics**: `totalOnhandQuantity` (units physically in the AWD warehouse) vs `totalInboundQuantity` (en route to AWD, not yet received) vs `inventoryDetails.availableDistributableQuantity` (distributable from AWD to FBA) vs `replenishmentQuantity`. `distributionIneligibleReasons[].failureCode` (e.g. `NO_NETWORK_INVENTORY_RESERVED`) explains SKUs a replenishment order couldn't move.

**`search_for_products` inventory fields** — the `/products` rows carry `awdAvailableQuantity` + `awdInboundQuantity`, which come from a daily AWD snapshot and may be null or stale: they are null for sellers not enrolled in AWD and can lag the live position even when populated. Do NOT treat them as authoritative AWD stock — use the three live AWD tools above for real, live AWD figures. The same rows also carry the FBA inventory fields `reservedQuantity` (units in Amazon's network being picked/packed/shipped or sidelined), `inboundQuantity` (units en route to Amazon), and `unfulfillableQuantity` (units that cannot be sold) — any of these may be `null` for a given SKU.

## `get_alerts` / `get_alerts_unread_count` / `mark_alerts` / `mark_alerts_by_filter` — wire format (Alerts)

`sellerId` is injected from the active seller — never send it. All four are internal-api calls; the two `mark_*` tools are HTTP `PATCH`, the two reads are `POST`.

**`get_alerts` request** (startDate/endDate required, inclusive, range ≤180 days):
```json
{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "marketplaces": ["Amazon.com"],
  "asins": ["B0CKPV1G9B"],
  "skus": ["SE-BSK-1"],
  "parentAsins": ["B0CKPV1G9B"],
  "eventCategories": ["INVENTORY"],
  "eventTypes": ["OUT_OF_STOCK"],
  "types": ["ALERT"],
  "readStatus": "UNREAD",
  "sortBy": "datetime",
  "sortDirection": "DESC",
  "page": 1,
  "pageSize": 10
}
```
All fields except `startDate`/`endDate` are optional. **`eventCategories`** ∈ `SUPPRESSION|INDEXING|LISTING|FEES|INVENTORY`. **`eventTypes`** (21): `STATUS_CHANGED, ADULT_FLAG_CHANGED, LISTING_SUPPRESSED, LISTING_SUSPENDED, LISTING_ISSUES, PRODUCT_TYPE_CHANGED, CATEGORY_CHANGED, TITLE_CHANGED, BULLETS_REMOVED, BULLETS_CHANGED, DESCRIPTION_CHANGED, SEARCH_TERMS_CHANGED, LISTING_ATTRIBUTE_CHANGED, PARENT_PRODUCT_CHANGED, BUYBOX_LOST, DIMENSIONS_CHANGED, PACKAGE_DIMENSIONS_CHANGED, WEIGHT_CHANGED, FBA_FEE_CHANGED, REFERRAL_FEE_CHANGED, OUT_OF_STOCK`.

**`get_alerts` response**:
```json
{
  "items": [{
    "id": "515a7ddf-3c76-4928-9bb6-9d2dcb8a357c",
    "level": "SKU", "sku": "SE-BSK-1", "asin": "B0CKPV1G9B", "parentAsin": "B0CKPV1G9B",
    "salesChannel": "Amazon.com", "eventCategory": "INVENTORY", "eventType": "OUT_OF_STOCK",
    "oldValue": null, "newValue": null, "value": null, "type": "ALERT", "notes": null,
    "datetime": "2026-05-27 09:22:17.971", "read": false, "readDatetime": null
  }],
  "total": 1, "page": 1, "pageSize": 10, "totalPages": 1, "hasNext": false
}
```
**Wire quirks**: `datetime` and `readDatetime` are ClickHouse `YYYY-MM-DD HH:mm:ss.SSS` (space-separated, NO `T`/`Z`) — NOT ISO-8601, despite older doc-strings. `datetime` is **marketplace-local** wall-clock; `readDatetime` is **UTC** — do not diff them. `notes` is always `null` today; `level` is always `SKU`. An empty `items: []` is a normal quiet-account result (the tool replaces it with a `noResults: true` + `hint` envelope), not an error.

**`get_alerts_unread_count`**: same request as `get_alerts` minus `readStatus`/`sortBy`/`sortDirection`/`page`/`pageSize`. Response: `{ "totalUnread": 1473 }`.

**`mark_alerts` request** (`PATCH`; `state` picks `/alerts/read` vs `/alerts/unread`; max 500 items):
```json
{ "state": "READ", "alerts": [{ "alertId": "515a7ddf-3c76-4928-9bb6-9d2dcb8a357c", "alertDate": "2026-05-27" }] }
```
`alertDate` is the `YYYY-MM-DD` slice of the alert's marketplace-local `datetime`. Response (partial success — one bad id does not fail the batch):
```json
{ "results": [{ "id": "515a7ddf-3c76-4928-9bb6-9d2dcb8a357c", "status": "SUCCESS" }] }
```
`status` ∈ `SUCCESS|ERROR`.

**`mark_alerts_by_filter` request** (`PATCH`; `state` picks `/alerts/read-all` vs `/alerts/unread-all`; same filters as `get_alerts`, no sort/paging):
```json
{ "state": "READ", "startDate": "2026-05-01", "endDate": "2026-05-31", "eventCategories": ["INVENTORY"] }
```
Response:
```json
{ "updatedCount": 12, "failedDates": [] }
```
`updatedCount` = alerts whose `read` flag actually flipped (already-in-state rows are skipped, not counted). `failedDates` = `YYYY-MM-DD` dates the op could not apply; the op is **idempotent**, so re-issue to retry just those. Bulk `*-all` is synchronous and can be slow over wide ranges (the handler uses a 90s timeout vs the 30s default).

## Conventions

- **`currencyCode`** is auto-resolved from the active seller (`mainCurrency`) — omit it from `propose_*` bodies. **`marketplace`** defaults to the active seller's `mainSalesChannel` when omitted; to target a connected non-default marketplace, pass its exact storefront string from `get_marketplaces` (an unconnected value returns `MARKETPLACE_NOT_AVAILABLE`). See ACTIONS.md "Marketplace handling".
- **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.

## Keyword Relevancy dataset writes (`/v1/tools/relevancy/*`, `account:write`)

Distinct from the Amazon Ads writes above: these hit the Keyword Relevancy dashboard's API, are NOT multi-status, have NO dry-run and NO delete. `sellerId` + `marketplace` (storefront string) are injected from the active seller — omit them.

```jsonc
// propose_create_relevancy_dataset
{ "datasetName": "Premium Album — competitors",
  "asin": "B0B3V3791F",            // a seller-OWNED ASIN
  "competitorAsins": ["B0B96J9LL8", "B001VGC0AA"] }  // 1-10, runtime-required
//  -> { "datasetId": 187798 }      // NUMBER (not the UUID the swagger implies)

// propose_add_relevancy_dataset_asins  /  propose_remove_relevancy_dataset_asins
{ "dataSetId": 187798,              // camelCase `dataSetId` (capital S) — NOT `datasetId`
  "asins": ["B001VGC0AA"] }         // 1-10
//  -> { "success": true }
```

- **`dataSetId` camelCase quirk**: the read tool (`get_keyword_relevancy`) returns datasets keyed on `datasetId`, but the add/remove write body wants `dataSetId` (capital S). Use the numeric value from `availableDatasets[].datasetId`.
- **`create` returns a NUMBER** (`datasetId`), directly usable by add/remove/`get_keyword_relevancy` — the swagger's UUID example is wrong.
- **No dry-run, no delete**: a created dataset is permanent. Label test datasets; there is no endpoint to remove one.

```jsonc
// propose_relevancy_ranking_update  (marketplace injected)
{ "datasetId": 187821 }              // NOTE: datasetId (lowercase s), not dataSetId
//  -> { "success": true }           // returns immediately; recompute runs ASYNC

// propose_relevancy_cache_purge  (NO marketplace — even though it is injected
//                                  for the other relevancy writes)
{ "datasetId": 187821 }
//  -> { "success": true }
```

- **`ranking/update` is once/24h + ASYNC**: `{success}` means "accepted", not "done". Poll `get_relevancy_ranking_status` (`{ datasetId }` → `{ ongoing: boolean }`) until `ongoing:false`, then re-read.
- **`cache/purge` takes NO marketplace** (D-purge) — `{ sellerId, datasetId }` only. `ranking/update` DOES carry the injected marketplace. Note both use `datasetId` (lowercase s), unlike the add/remove `dataSetId`.

## Keyword Rank Tracker writes (`/v1/krt/*`, `account:write`)

Distinct from both the Amazon Ads writes and the relevancy writes: these are **partial-success batches** (NOT multi-status), have **NO dry-run**, but are **REVERSIBLE**. `sellerId` is injected from the active seller — omit it. `marketplace` is injected ONLY for `propose_track_keywords` (asin-scoped, US/DE/UK/CA); the by-id writes take NO marketplace.

```jsonc
// propose_track_keywords  (asin-scoped — marketplace injected, US/DE/UK/CA only)
{ "asin": "B0D1NMX2BS",
  "phrases": ["travel towel", "quick dry towel"] }   // 1-500
//  -> { "items": [ { "key": "travel towel", "status": "ALREADY_TRACKED" },
//                   { "key": "quick dry towel", "status": "SUCCESS" } ],
//       "summary": { "succeeded": 1, "skipped": 1, "failed": 0 } }
//  NOTE: items[].key is the PHRASE, NOT the new keywordRankTrackerId. Re-call
//  get_keyword_ranks (search by phrase) to resolve the id before labeling/tagging.

// propose_untrack_keywords  (by-id — NO marketplace)
{ "keywordRankTrackerIds": [1287188, 1287189] }       // 1-500
//  -> { "items": [ { "key": "1287188", "status": "SUCCESS" } ], "summary": {…} }

// propose_set_keyword_label  (PATCH — by-id)
{ "keywordRankTrackerIds": [1287188], "labelId": 46 } //  labelId: null CLEARS the label
//  -> { "items": [ { "key": "1287188", "status": "SUCCESS" } ], "summary": {…} }

// propose_add_keyword_tag  (by-id)
{ "keywordRankTrackerIds": [1287188], "tag": "launch-q3" }  // ≤120 chars; creates if new

// propose_remove_keyword_tags  (by-id — tagId, NOT keywordRankTrackerId)
{ "tagIds": [34930] }                                  // tagId from a row's tags[].tagId
```

- **Partial-success envelope**: `{ items:[{key,status,error?}], summary:{succeeded,skipped,failed} }`. `propose_track_keywords` status ∈ `SUCCESS | ALREADY_TRACKED | ERROR`; the rest ∈ `SUCCESS | ERROR`. Do NOT `parseMultiStatus`.
- **`items[].key` semantics**: track → the phrase; untrack/label/tag → the `keywordRankTrackerId`; remove-tags → the `tagId`.
- **`propose_set_keyword_label` is a PATCH** and `labelId: null` CLEARS the label (reversible).
- **Marketplace asymmetry**: only `propose_track_keywords` carries `marketplace` (injected). Sending `marketplace` on a by-id write is rejected.

## Keyword comment writes (`/v1/krt/comments`, `account:write`)

SINGLE-ITEM (NOT partial-success batches), REVERSIBLE (add ↔ remove), no dry-run, NO marketplace. `sellerId` injected from the active seller. A foreign/unknown `keywordRankTrackerId`/`commentId` returns an upstream **404** (the NestJS `{message,error,statusCode}` envelope) — never an empty success.

```jsonc
// propose_add_keyword_comment  (POST /v1/krt/comments)
{ "keywordRankTrackerId": 1029389,
  "commentDate": "2026-06-19",       // YYYY-MM-DD — the event date the note marks
  "commentText": "Price drop" }
//  -> { "comment": { "commentId": 32939, "keywordRankTrackerId": 1029389,
//                    "commentDate": "2026-06-19", "commentText": "Price drop",
//                    "createdAt": "…", "updatedAt": "…" },
//       "count": 1 }                 // active comments on the keyword after insert

// propose_edit_keyword_comment  (PATCH /v1/krt/comments — TEXT ONLY)
{ "commentId": 32939, "commentText": "Updated note" }   // NO commentDate
//  -> { "comment": { "commentId": 32939, …, "updatedAt": "…" } }  // updatedAt advances

// propose_remove_keyword_comment  (POST /v1/krt/comments/remove)
{ "commentId": 32939 }
//  -> { "success": true }
```

- **Wire `id` → `commentId`**: upstream returns the comment's primary key as `id`; the connector's L1 sanitizer strips any field named `id`, so the shape layer renames it to `commentId` BEFORE sanitization — that is the handle you pass to edit/remove.
- **Edit is text-only**: `commentDate` is not editable (the `KrtEditCommentRequestBody` carries only `commentId` + `commentText`).
- **404, not empty**: an unknown/foreign `keywordRankTrackerId` (add) or `commentId` (edit/remove) → `{"message":"Comment … was not found for this user","error":"Not Found","statusCode":404}`. Surface it as a 404, not a fabricated success.

## Keyword segments / comments / families reads (`/v1/krt/*`, `/v1/tools/relevancy/*`)

Reads — no approval. `sellerId` injected; segments need `marketplace` (asin-scoped, US/DE/UK/CA); comments are by `keywordRankTrackerId` (no marketplace); families/members need `marketplace` + `datasetId`.

```jsonc
// get_keyword_segments  (POST /v1/krt/segments/list)  -> { "segments": [...] }
{ "asin": "B0D1NMX2BS" }
//  -> { "segments": [ { "segmentId": 789, "name": "High intent",
//         "type": "CUSTOM_SEGMENT",            // IMPORTED_SET|CUSTOM_SEGMENT|MANUALLY_ADDED|MASTER_SET
//         "keywordRankTrackerIds": [1029102, 1029236],   // NO itemCount upstream
//         "keywordCount": 2 } ] }              // derived = keywordRankTrackerIds.length

// get_keyword_comments  (POST /v1/krt/comments/list)  — by-id, NO marketplace
{ "keywordRankTrackerId": 1029389 }
//  -> { "comments": [ { "commentId": 32939, "keywordRankTrackerId": 1029389,
//         "commentDate": "2026-06-19", "commentText": "…", "createdAt": "…",
//         "updatedAt": "…" } ] }
//  404 on an unknown keywordRankTrackerId — NOT an empty list.

// get_keyword_families  (POST /v1/tools/relevancy/keywords/families)
{ "datasetId": 187821, "ppcCheck": true }      // ppcCheck optional (adds inPpc/adTypes/matchTypes)
//  -> { "items": [ { "familyId": "family_1560217822",   // OPAQUE STRING, not a number
//         "rootPhrase": "scrapbook album", "memberCount": 5,
//         "inPpc": true, "adTypes": ["SP"], "matchTypes": ["EXACT"] } ],
//       "total": 2380, "page": 1, "pageSize": 5, "totalPages": 476, "hasNext": true }
//  ⚠ total (2380) is the KEYWORD count, NOT the family count.

// get_keyword_family_members  (POST /v1/tools/relevancy/keywords/families/members — PLURAL)
{ "datasetId": 187821, "familyId": "family_1560217822" }   // the singular …/family/members 404s
//  -> { "familyId": "…", "rootPhrase": "…", "members": [<relevancy keyword rows>],
//       "total": …, "page": …, "hasNext": … }

// get_relevancy_ranking_status  (POST /v1/tools/relevancy/dataset/ranking/update/status)
{ "datasetId": 187821 }
//  -> { "ongoing": false }                     // true while a recompute is running
```

- **`familyId` is an opaque STRING** (`"family_1560217822"`), not a number — pass it verbatim to `get_keyword_family_members`; never quote it to the user.
- **Members route is PLURAL** `…/keywords/families/members` — the announced singular `…/family/members` 404s.
- **`families.total` = keyword count, NOT family count** — it equals `get_keyword_relevancy`'s `total`.
- **`ppcCheck` is opt-in** (default off): adds `inPpc` / `adTypes` (SP/SB/SD) / `matchTypes` (EXACT/PHRASE/BROAD). The dataset-list competitors also gain `marketDepth` / `rankedKeywords`.

# 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.

**Run this ONLY when context isn't already established.** Active account + seller
are server-side session state that persists across calls; a single account /
single store is auto-selected. Skip this whole workflow if the user has one
account (auto-selected) or you already switched this session. Before committing a
write batch, state the active account + seller you're writing to (confirm with a
free `get_active_account` probe rather than re-running discovery — a failed write
burns an approval click). Every write result also echoes `activeContext` (the
account + seller + marketplace it hit) — verify it matches what the user
intended. See SKILL.md → "Required Workflow".

```
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 1b: Build an SP Campaign From Scratch (writes — REAL MONEY)

Use when the user wants a brand-new Sponsored Products campaign (campaign → ad
group → product ad(s) → keywords/targets → optional placement bids).

There is **no single "build campaign" tool** and no way to collapse this into one
approval. Each entity is a separate `propose_*` call, and each downstream call
needs an ID that only comes back in the previous call's `success[]` — so the
calls are a forced serial chain, not a bundle. The host prompts for approval
**once per call**, so a full build is ~5 approvals (more if a step fails and
retries). Set expectations up front, e.g. *"This is a 5-step build — you'll get
one approval prompt each for the campaign, ad group, product ad, keywords, and
placement bids."* Do **not** suggest "Always Allow".

```
KNOWLEDGE TRACK (first, mandatory):
- titan_lessons (campaign structure / single-keyword campaign / etc.)
  + fetch_framework("ppc_3_0") for the build rationale. Cite it.

PRE-FLIGHT:
- get_active_account (free, no approval) → confirm the right account + store
  are active BEFORE any approval-gated write. Establish context if missing.

DATA TRACK (sequential — each step feeds the next; batch items WITHIN a step):
1. propose_create_sp_campaign({ campaigns: [ ... ] })
   → read the new campaignId from success[0].
2. propose_create_sp_ad_group({ adGroups: [{ campaignId, name, defaultBid, state }] })
   → read the new adGroupId from success[0].
3. Product ad(s) + keywords/targets — each needs campaignId + adGroupId. Put all
   items of one kind in ONE call (= ONE approval each):
   - propose_create_sp_product_ad({ productAds: [{ campaignId, adGroupId, sku|asin, state }] })   (max 500/call)
   - propose_create_sp_keyword({ keywords: [{ campaignId, adGroupId, keywordText, matchType, bid?, state:"ENABLED" }, ...] })   (max 500/call — ALL keywords in one call)
   - (or propose_create_sp_target for product/category targets — max 100/call)
4. (optional) propose_update_sp_campaign_placement_modifiers — needs the
   campaign's biddingStrategy; source it from search_for_ppc_campaigns({campaignIds:[id]})
   first (see Workflow 9b). strategy is REQUIRED.

PER STEP:
- Inspect the multi-status error[] — empty error[] is the only success. On a
  partial failure, narrate per-item and retry ONLY the failed items.
- Never fabricate campaignId / adGroupId — use only this turn's success[].
  Create with state:"ENABLED" (pause afterward if the user wants it dark).

→ Close with a plain-prose summary of what was created + a Sources section.
```

## 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:
DEFAULT: ad-group-level (6b/6c) unless the user explicitly asks to block the
term across the whole campaign. "in [the] campaign" = where the keyword lives,
not a request for campaign-scope.
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):
   - DEFAULT: ad-group-level (surgical — applies only to that one group). Use it
     unless the user explicitly asks to block across the whole campaign.
   - campaign-level applies to every ad group under that campaign (broader) — use
     ONLY on an explicit campaign-wide / all-ad-group request.
   - "in [the] campaign" = where the ASIN/brand lives, NOT a request for
     campaign-scope; default to ad-group-level.
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, search: "X" })` — NOT search-terms metrics (PPC ≠ organic); `organicRank`/`sponsoredRank` are `null` when not ranking (read `isOrganicRanked`/`isSponsoredRanked`); no 301 sentinel |
| Are these keywords relevant to my listing? | `get_keyword_relevancy({ asin })` — FIRST; `relevancy` 0-9; do not infer relevance from PPC search-terms metrics |
| Keyword groupings + member notes? | `get_keyword_segments({ asin })` for the groupings; pick a `keywordRankTrackerId` → `get_keyword_comments({ keywordRankTrackerId })` for the operator-truth notes |
| Keyword families / root phrases? | `get_keyword_families({ datasetId })` → pick a STRING `familyId` → `get_keyword_family_members({ datasetId, familyId })` |
| Pre-launch keyword strategy | `get_keyword_relevancy` → `get_keyword_segments` → `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 titan-connect-only keyword tools, all over the
HTTP `/v1/krt/*` + `/v1/tools/relevancy/*` APIs (fast, no cold-store warm-up):
`get_ppc_audit`, `get_keyword_ranks`, `get_keyword_rank_history`,
`get_keyword_tracking_limits`, `get_keyword_labels`, `get_keyword_tags`,
`get_keyword_segments`, `get_keyword_comments`, `get_keyword_relevancy`,
`get_keyword_families`, `get_keyword_family_members`,
`get_relevancy_ranking_status` — plus the KRT + comment + relevancy writes. See
the `<keyword_and_audit_tools>` block in MCP_INSTRUCTIONS for the cross-cutting
rules. KRT is US/DE/UK/CA only. `organicRank`/`sponsoredRank` are `null` when not
ranking (read `isOrganicRanked`/`isSponsoredRanked`) — there is NO 301 sentinel.

### 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 these in this order — they compose into the strategy):
1. list_seller_accounts → set_active_seller
2. get_keyword_relevancy({ asin })
   → identifies which phrases ARE relevant to this listing
   (relevancy is integer 0-9; paginate with page/pageSize; a Negative/manual
    dataset correctly returns keywords:[] with a message — by design, not an
    error). For root-phrase grouping, drill with
    get_keyword_families({ datasetId }) → get_keyword_family_members({ datasetId,
    familyId }) — remember families `total` is the KEYWORD count, NOT the family
    count.
3. get_keyword_segments({ asin })
   → the seller's keyword groupings (segmentId/name/type/keywordRankTrackerIds[]/
    keywordCount; summarize a big MASTER_SET, don't dump 2,000 ids). For member
    notes on a phrase, take its keywordRankTrackerId (from a segment or a rank row)
    → get_keyword_comments({ keywordRankTrackerId }). Comments are operator-truth —
    cite verbatim (an unknown/foreign id 404s; that's "not your keyword", not "0").
4. get_keyword_ranks({ asin })
   → current organic performance on tracked phrases (sort with sortBy, paginate
    with page; for movement over time use get_keyword_rank_history by
    keywordRankTrackerId, span ≤ 360 days).

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 (propose_track_keywords)
- Tracked + not ranking (organicRank null) = PPC opportunity
- Tracked + ranking + low relevancy = candidate to drop
- Member comments from step 3 outweigh model speculation; a note worth recording →
  propose_add_keyword_comment (returns a commentId for later edit/remove)

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

Latency: a handful of HTTP calls, 1-3s each.

### 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 })  (filter with search, sort with sortBy)
   → per-phrase current organicRank/sponsoredRank (null = not ranking, read the
     isOrganicRanked/isSponsoredRanked booleans).
   For per-day history: get_keyword_rank_history({ asin, keywordRankTrackerId,
     startDate, endDate })  (span ≤ 360 days).
3. For phrases with concerning trends:
   get_keyword_comments({ keywordRankTrackerId })
   → member notes often explain rank movement (e.g. "sponsored rank dropped after
     PPC pause") — first-party context, cite verbatim.
4. For ranks that look unexpectedly low: cross-check with
   get_keyword_relevancy({ asin })
   → 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: a few HTTP calls, 1-3s each.

### 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_ranks({ asin }) + get_keyword_segments({ asin })
   + get_keyword_labels({}) + get_keyword_tags({ asin })
   → the tracked phrases, the keyword groupings, and the account's labels/tags.
   Use NAMES (segment name, label name) in user-facing prose, never IDs.
   For per-phrase member notes: get_keyword_comments({ keywordRankTrackerId }).
3. (optional) get_keyword_relevancy({ asin })
   → check which tracked phrases are actually relevant to the listing.
4. (optional) get_keyword_rank_history(...) for phrases whose trend matters.

CROSS-REFERENCE:
- Tracked + low relevancy + not ranking = candidates to remove (propose_untrack_keywords)
- Tracked + high relevancy + Amazon's Choice = wins to amplify
- Stale comments (commentDate > 90 days old) = outdated context

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

**Recompute / refresh a relevancy dataset's rankings:** when the data looks stale,
`propose_relevancy_ranking_update({ datasetId })` triggers a REAL recompute (once
per 24h, runs async — returns `{success}` immediately). Then poll
`get_relevancy_ranking_status({ datasetId })` until `{ ongoing: false }` and re-read
`get_keyword_relevancy` / `get_keyword_families`. `propose_relevancy_cache_purge({
datasetId })` (no marketplace) drops cached results to force a fresh read.

**PARENT/CHILD + SIBLINGS:** the tracker (and relevancy) attach to the **PARENT**
ASIN. If `get_keyword_ranks` returns `total: 0` (or relevancy returns `productId:
-1` / empty) for a **child** ASIN, it's almost never a real data gap — resolve the
parent via `search_for_products` and retry on the parent. A family's keywords can
also be split across **sibling parents** (e.g. different size/format parents in one
brand) — if some keywords come back "not tracked" on one parent, check the other
parent ASINs in the family before reporting them untracked. Don't report
"relevancy data not coming in" before trying parents.

**VOLUME SOURCE = the Keyword Rank Tracker, NOT relevancy.** For "give me the
search volume for these keywords," use `get_keyword_ranks` (curated per-phrase
`searchVolume` + `searchVolumeRaw`; filter with `search`). `get_keyword_relevancy`
ALSO returns a populated `searchVolume`, but it's the full relevance corpus (often
thousands of phrases), so read it as relevance-context, not the primary volume
list. `get_sqp_metrics` is a secondary/partial cross-check only. If a keyword isn't
tracked (after parent + sibling checks), **say "not tracked" and stop** — don't
fish across relevancy/SQP/web to manufacture a number.

**SEARCH VOLUME — `<100` vs not-tracked:** `searchVolume` comes back as a number
(>100), the sentinel `"<100"` (real but low — the upstream ZV/sub-threshold
bucket; **not** zero, **not** untracked), or `null`/absent (not in tracker).
`searchVolumeRaw` carries the raw number for threshold maths. Report `"<100"` as
"<100", not "0".

**PRODUCT SEARCH IS NOT EXHAUSTIVE.** `search_for_products` matches a text
pattern, so it silently misses naming variants ("Twin XL" vs "Twin Extra Long
(XL)", "bedbug" vs "bed bug"). **Never** answer "which ASIN / highest revenue /
top / ranking" from one text query (a "Twin XL" search missed the real revenue
leader named "Twin Extra Long (XL)" — off by ~4×). Pull at the parent/family
level or run multiple naming-variant queries and union; caveat any ranking as
limited to matched names; if the member names an ASIN you missed, re-run wider
instead of defending the original ranking.

### Workflow 12b: Search volume for ONE keyword

For "what's the search volume for `<keyword>`?" / "is `<keyword>` tracked?" — do
NOT dump a full table.

```
1. list_seller_accounts → set_active_seller
2. get_keyword_ranks({ asin, search: "<keyword>" })
   → the search param narrows server-side, so an ASIN with hundreds of tracked
     phrases still surfaces the one you asked about (an unfiltered call paginates
     and can hide it).
   → If total:0 on a child, retry on the PARENT ASIN.
3. Match the phrase EXACTLY (don't substitute a different word order, e.g.
   "twin xl mattress cover waterproof" ≠ "waterproof twin xl mattress cover").
4. State which figure + source: relevancy searchVolume vs KRT searchVolume
   (get_keyword_ranks) vs SQP searchQueryVolume — they differ; name the one.
→ Report: the single SV (or "<100" / "not tracked"), its source field, nothing
  else. If the answer feeds a campaign-structure decision (PPC 3.0 1,000+ rule),
  use searchVolumeRaw and say so only when confirmed.
```

### 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.

## Workflow 14: Downloadable / Scheduled Custom Report (read-style)

For "give me a CSV of …", "export my … to a spreadsheet", or "set up a weekly/monthly … report". Distinct from the metric tools (which return data you analyze in-chat) — this produces a **downloadable file**. See the create/download wire format + per-type matrix in [`WIRE_FORMATS.md`](./WIRE_FORMATS.md).

```
DATA TRACK:
1. list_seller_accounts → set_active_seller
2. Pick reportType + dateRangeType for the ask (one of 7 types; each allows
   only certain date ranges — see the WIRE_FORMATS matrix). For
   SEARCH_QUERY_PERFORMANCE you need exactly one ASIN + one marketplace,
   periodicity+year+periodRange, ONCE only.
3. RECURRING? (updateFrequency ≠ ONCE) — CONFIRM the schedule with the operator
   FIRST. Recurring reports cannot be listed, edited, or cancelled via the API,
   so a mistaken DAILY report keeps generating with no in-tool off switch.
4. create_custom_report({ marketplaces, asins?, updateFrequency?, reportConfig })
   → returns { reportId }.
5. get_custom_report({ reportId })  — SINGLE poll, the tool does not loop:
   → IN_PROGRESS: say it's generating, call again in ~5-25s
     (SEARCH_QUERY_PERFORMANCE ~25s; others seconds).
   → DONE: hand over downloadUrl — it opens with NO Titan Tools login. Keep it
     private; do NOT fetch it yourself.
   → NO_DATA_AVAILABLE: suggest a wider range / different marketplace / ASIN.
   → FAILED/CANCELLED/DELETED: create a new report.

KNOWLEDGE TRACK:
6. titan_lessons (query: the report's subject, e.g. "profit and loss",
   "search query performance") → the operator still gets a Titan-grounded
   interpretation layer alongside the link.

→ Hand over the download link, name what's in the file and its date range, and
  (for recurring) restate the cadence + the no-edit/no-cancel caveat. Sources
  section is still mandatory.
```

Latency: create is instant; the single poll is seconds (SQP ~25s).

## Workflow 15: AWD stock picture (US-only — Amazon Warehousing & Distribution)

For "how much AWD inventory do I have?", "what's inbound to AWD?", "which replenishment orders went to FBA?", or a full AWD stock picture. AWD is **US-only** — these tools always run against `Amazon.com`. They return Amazon's payload verbatim incl. `nextToken` (page by passing it back).

```
DATA TRACK:
1. list_seller_accounts → set_active_seller.
2. get_awd_inventory (details: 'SHOW' for the per-SKU distributable/replenishment/
   reserved breakdown). For a full picture also call get_awd_inbound_shipments
   (what's en route to AWD) and get_awd_replenishment_orders (AWD → FBA).
3. READ THE 3-STATE SIGNAL before reporting:
   → 200 with rows: real AWD data — report it.
   → 200 with an empty array (inventory:[]/shipments:[]/orders:[]): the seller IS
     AWD-enrolled but has nothing right now. Say "no current AWD stock", NOT "no AWD".
   → AWD_NOT_ENROLLED (403): the seller hasn't re-authorised Titan Tools for the AWD
     role. Tell them to re-authorise Titan Tools to turn on AWD data — do NOT report
     "no AWD inventory".
   → AWD_NO_US_CONNECTION (404): no US Selling-Partner connection; AWD is US-only.
4. Do NOT use the awd*Quantity fields on search_for_products for this — they come from a
   daily AWD snapshot and may be null or stale (null for sellers not enrolled in AWD, and
   can lag the live position even when populated). The three tools above are the source of
   truth.
5. nextToken present? page through it before summarising totals.

KNOWLEDGE TRACK:
6. titan_lessons (query: "AWD" / "Amazon Warehousing and Distribution" / "inventory
   placement") for the Titan-grounded interpretation layer when the operator wants
   strategy, not just the numbers.

→ Report on-hand (in AWD) vs inbound (en route) vs distributable-to-FBA distinctly;
  surface distributionIneligibleReasons for SKUs that couldn't replenish. Sources
  section is still mandatory.
```

Latency: 1-3s per call; replenishment-orders can paginate on large accounts.

## Workflow 8: Build + analyze a Keyword Relevancy dataset

For "which competitors should I track for <ASIN>?" / "set up relevancy tracking for this product" — when no suitable dataset exists yet.

```
0. Knowledge first: titan_lessons (query: "keyword relevancy" / "competitor research")
   for the Titan lens on relevance + competitor selection.
1. get_keyword_relevancy({ asin }) — does a dataset already exist? If availableDatasets
   is non-empty, analyze that instead of creating a duplicate. DATASET CHECK: omitting
   `dataset` applies whichever set upstream lists first (`appliedDataset`) — NOT
   guaranteed to be the right one; an ASIN can carry stale/test/empty sets. Verify
   `appliedDataset.name` matches the product and the rows are real phrases. If it looks
   wrong, re-call with `dataset:{ id }` choosing the `availableDatasets` entry whose name
   matches the product, then reuse that SAME `dataset` on every follow-up call so
   pages/sorts stay comparable.
2. Identify 1-10 competitor ASINs (from the user, or search_for_products / the
   product's category). Confirm them with the operator.
3. propose_create_relevancy_dataset({ datasetName, asin, competitorAsins:[...] })
   — HIL-approved, IMMEDIATE, IRREVERSIBLE (no delete). Returns numeric datasetId.
4. get_keyword_relevancy({ asin, dataset:{ id: <new datasetId> } }) — the new dataset
   is queryable immediately (no processing delay). Analyze relevancy + competitor ranks.
5. Refine: propose_add_relevancy_dataset_asins / propose_remove_relevancy_dataset_asins
   ({ dataSetId, asins:[...] }) to adjust the competitor set, then re-read.
```

→ Synthesize through the Titan lens (which phrases are genuinely relevant, where
  competitors out-rank the seller). Sources section mandatory. Never surface raw
  datasetId / correlationId in prose.

Latency: 1-3s per read; writes are immediate. NO dry-run, NO delete — confirm before creating.

## Workflow 16: Manage Keyword Rank Tracking (reads + writes — REVERSIBLE)

For "track these keywords for <ASIN>", "label/tag my tracked keywords", "where am I ranking and how has it moved". KRT is US/DE/UK/CA only. The writes are HIL-approved, REAL/IMMEDIATE but REVERSIBLE (no dry-run).

```
0. Knowledge first: titan_lessons (query: "keyword rank tracking" / "ranking strategy").
1. Capacity check (before adding): get_keyword_tracking_limits({ asin }) → confirm
   `remaining` > the number you intend to add.
2. See what's already tracked: get_keyword_ranks({ asin, search?, sortBy?, page? }).
   Unranked phrases have organicRank/sponsoredRank = null (read isOrganicRanked /
   isSponsoredRanked) — there is NO 301 sentinel.
3. ADD: propose_track_keywords({ asin, phrases:[...] }) — HIL-approved. Partial-success:
   per-item SUCCESS / ALREADY_TRACKED / ERROR. items[].key echoes the PHRASE, NOT the
   new keywordRankTrackerId.
4. RESOLVE THE ID (required before labeling/tagging a just-added keyword): re-call
   get_keyword_ranks({ asin, search: "<phrase>" }) and read keywordRankTrackerId from the row.
5. LABEL / TAG (by keywordRankTrackerId):
   - get_keyword_labels() → pick a labelId; propose_set_keyword_label({ keywordRankTrackerIds:[id], labelId })
     (labelId: null clears it).
   - propose_add_keyword_tag({ keywordRankTrackerIds:[id], tag })  — creates the tag if new.
6. HISTORY: get_keyword_rank_history({ asin, keywordRankTrackerId, startDate, endDate })
   — span ≤ 360 days. Chart organicRank/sponsoredRank movement + searchFrequencyRank.
7. UNDO if needed: propose_untrack_keywords({ keywordRankTrackerIds }),
   propose_remove_keyword_tags({ tagIds })  (tagId from a row's tags[].tagId).
```

→ Synthesize through the Titan lens (relevance before tracking, where the seller
  ranks vs competitors). Never surface keywordRankTrackerId / tagId / correlationId
  in user-facing prose — use the phrase / label / tag names. Sources section mandatory.

Latency: 1-3s per read; writes are immediate. NO dry-run, but every write is reversible.