Quickstart

STEP-BY-STEP FOR COMMON ASKS (client_id + marketplace always from get_clients)
A. "How is the account doing?"
   get_performance_data(breakdown="account", date range) -> compare_periods for this vs last period ->
   get_sales_data for total sales (TACOS). Say which days are still growing (14-day attribution).
B. "Where am I wasting money?"
   find_wasted_spend(days=30, min_spend=...) -> for each row, look at search terms with
   search_term_analysis -> propose negatives or lower bids -> add_negatives / batch_update_entities
   (preview confirmed=False, user says yes, then confirmed=True).
C. "Change bids"
   suggest_bid_changes(target_acos=...) -> get_keyword_entities for the exact ids ->
   batch_update_entities(entity_type="keywords", updates=JSON list) preview -> confirm.
D. "Pause / enable something"
   get_live_entities(entity_type=..., campaign_id="id1,id2") ONE call for all ids ->
   update_keyword_status / update_target_status / update_campaign preview -> confirm.
E. "Launch a campaign"
   get_products (ASINs/SKUs) -> create_campaign(campaign_data=JSON) preview -> confirm ->
   get_live_entities(entity_type="adGroups", campaign_id=new id) -> add_keywords_targets /
   add_product_ads preview -> confirm. More ad groups in that campaign: create_ad_group (SP/SD, once an
   admin has switched it on).
F. "Harvest search terms"
   find_search_term_opportunities(min_orders=2) -> add_keywords_targets (exact) + add_negatives in the
   source campaign, both preview -> confirm.
G. "Budgets for today / this week"
   get_budget_plan -> get_budget_usage -> recommend_budgets -> set_budget_now or add_budget_step
   (preview -> confirm). If the plan says the sheet owns it, stop and tell the user.
H. "Run my daily routine"
   get_todays_changes (what already changed) -> B and C above -> submit_daily_report at the end.
I. Audience questions -> amc_ask (topic amc).
Always end with what changed, what failed (per row) and what the user should check tomorrow.

TOOL MAP (pick by what the user asks)
- Who / what: get_clients, get_client_facts, get_portfolios, get_campaign, get_live_entities
- How is it doing: get_performance_data (campaign/keyword/product, daily or total), analyze_campaign_health,
  compare_periods, get_placements, get_targeting_breakdown, get_campaign_hourly / get_keyword_hourly,
  get_realtime_traffic / get_realtime_conversions (Marketing Stream, today)
- Find problems / ideas: find_wasted_spend, find_search_term_opportunities, search_term_analysis,
  suggest_bid_changes, find_weak_listings, get_listing_quality, campaign_diagnostic
- Sales and stock: get_sales_data (total sales incl. organic), get_fba_reports, get_inventory (weekly)
- Exact numbers for a report: answer_exact; report layout: get_report_format
- Change (preview then confirm): update_keyword_status, update_target_status, update_campaign,
  update_campaign_placement, batch_update_entities, add_keywords_targets, add_negatives, add_product_ads,
  create_campaign, create_ad_group, archive_entities (SP, cannot be undone - pause instead unless asked),
  stage_changes -> apply_staged_changes
- Budgets: get_budget_plan, set_budget_now, add_budget_step, remove_budget_step, get_budget_usage,
  recommend_budgets
- Rules (automatic bid/pause jobs): list_rule_templates, list_rules, save_rule, run_rule, approve_run
- Audience questions (AMC): amc_ask, amc_result, amc_results, amc_export, amc_save_query, list_audiences,
  update_campaign_audience_bid, amc_create_audience (topic amc)
- Amazon's official Ads MCP (read only, this client only): official_tools, official_read
- Help: get_started, submit_support_request (type: bug | data | mis_change | access | report_change | feature),
  get_my_support_requests. Every request is mailed to the team and answered on the dashboard.

MAKING CHANGES SAFELY
1. Read the current state first (get_live_entities / get_campaign) and quote it to the user.
2. Call the change tool with confirmed=False. It returns what WOULD change (old -> new).
3. Show that to the user in a short table. Wait for an explicit yes.
4. Call again with the SAME arguments and confirmed=True. Changing arguments between preview and confirm
   counts as a blind confirm.
5. Check the reply: success rows and error rows are listed per entity - report errors, do not hide them.
Limits: batch_update_entities max 1000 rows SP / 100 SB per call; a daily cap of change calls per person.
Bids are in the account currency. ACOS targets are fractions (0.25 = 25%).
Placements: SP uses PLACEMENT_TOP / PLACEMENT_PRODUCT_PAGE / PLACEMENT_REST_OF_SEARCH.

BUDGETS
- get_budget_plan(client_id, marketplace): today's schedule, who controls it (sheet or console), next change.
- set_budget_now(..., amount, hours, confirmed=False first): a temporary override; hours=0 = until midnight.
- add_budget_step / remove_budget_step: change the weekly plan (time in the account's own time zone).
- If the plan says "Sheet sets it", the old budget sheet still owns that account - console steps are
  preview only. Tell the user; do not try to force it.

RULES (automatic jobs)
- list_rule_templates -> save_rule (starts Off) -> run_rule(dry run) -> approve_run to apply a run.
- A rule is Off / Ask first / Automatic per account. "Ask first" builds a change list that waits for
  approve_run. Never switch a rule to Automatic unless the user asked for exactly that.

DATA FRESHNESS AND SOURCES
- Ads (campaign/keyword/product/search term): daily files, newest day = yesterday. Sales attributed to ads
  keep growing for 14 days, so recent ACOS looks worse than it will be.
- Total sales (get_sales_data): OrderReport same day, BusinessReport 2 days behind.
- Inventory (get_inventory): one snapshot per week (week_start). Up to 13 days old is normal - only report
  it if the tool itself says the snapshot is stale.
- Realtime tools: Marketing Stream, hourly, the most recent days.
- Dates: use the client's marketplace time zone (the account's own day, not your laptop's).
- No rows usually means no ads ran - check get_campaign status before calling it a bug.

TOP MISTAKES SEEN IN TICKETS
1. Typing ids from memory -> wrong entity changed. Always fetch ids first.
2. confirmed=True without showing the preview to the user.
3. Treating a weekly inventory snapshot (7-13 days) as a data bug.
4. Calling last-3-days ACOS "bad" without the 14-day attribution note.
5. Using a client name that is not in get_clients (spelling, missing marketplace).
6. Asking for 147k rows - use filters (min_spend, campaign_id, date range) and get_result paging.
7. Mixing ad sales (ads tables) with total sales (get_sales_data).
8. Retrying ACCESS_DENIED or a daily-cap message instead of telling the user.
9. Writing a script or calling Amazon directly when a tool is missing - say "not available yet" instead.
10. SB placement names differ from SP - read the tool's error text, it lists the valid names.

AMC (Amazon Marketing Cloud) AND OTHER AMAZON OFFICIAL READ TOOLS
- amc_ask(client_id, marketplace) with no question LISTS what you can ask: ready questions (new_to_brand,
  repeat_buyers, time_to_reorder, overlap, frequency, path_to_purchase, lapsed_buyers, cart_abandoners,
  reach_by_campaign, purchase_hour, ntb_by_product) plus the team's saved queries.
- amc_ask(client_id, marketplace, question, days=90) runs one. AMC takes minutes: if the reply has an
  execution_id and no rows, call amc_result(client_id, marketplace, execution_id) later - the console also
  finishes it by itself and keeps the answer. lapsed_buyers wants days=365.
- amc_results lists past answers; amc_export(result_id, to="xlsx" | "drive") gives the Excel file.
- amc_save_query (admin / manager) keeps an AMC SELECT under a name, shared or per client, optionally in the
  Monday pack (weekly=True). Custom one-off SQL (sql=...) is admin only.
- "no AMC ids in the console" = an admin runs amc_discover(client_id, marketplace, save=True), or enters the
  AMC instance id + AMC account id on the account page.
- amc_create_audience turns a cohort query into an audience ONLY when Amazon's official server offers an
  audience tool for the region - the preview says whether it does. Existing audiences: list_audiences;
  boost SP bids on one: update_campaign_audience_bid (preview -> confirm).
- AMC hides groups under 100 people and its data ends about 2 days ago - say so when you present results.
- official_tools / official_read: other READ tools of Amazon's official Ads MCP for that client's region.
  Account ids in the arguments must be that client's own. Billing / account lists = admin only.
- Changes always go through this server's own change tools (preview -> confirm, audited).

DAILY ROUTINE - the 9 steps and the exact tool for each (tickets 58-66). Everything below exists today.
1. Baseline, 7-day pulse, store data, long windows: get_performance_data with breakdown "account" for 7 / 30 / 90
   day windows (give the dates); store sales + sessions: get_sales_data for the same dates (daily rows, sums in
   the summary); freshest daily totals: get_hourly_data with "per date" true.
2. Wasted spend with action classes: find_wasted_spend (days, minimum clicks, ACOS threshold, minimum spend) - the
   summary already carries pause / reduce-bid / watch counts and each keyword row carries its class. No negation here.
3. Placements and change history (before bids): get_placements for the window and get_change_history (days) -
   skip a bid when the entity changed in the last 7 days.
4. Bid actions (14-day window): suggest_bid_changes with days 14 and your target ACOS -> rows carry campaign and
   ad group ids; symmetric caps are yours to apply when you stage.
5. Change impact review: get_change_history (14 days) + compare_periods (the week before vs after) for the changed
   entities; get_todays_changes for what went out today.
6. Search terms with dedupe (negation lives here ONLY): search_term_analysis (minimum clicks, maximum ACOS) and
   find_search_term_opportunities; add_negatives (preview first) only from this step; get_staged_changes /
   list_staged_changes show what is already staged so nothing is negated twice.
7. Void stale batches, then stage: sweep_changesets voids expired ones; stage_changes stages WITHOUT pushing;
   nothing reaches Amazon until apply_staged_changes.
8. Budget utilisation and auto-push (LAST): get_budget_usage (which campaigns hit budget), recommend_budgets
   (utilisation gate, raise and decrease factors, budget floor, mode) -> apply with set_budget_now /
   update_campaign only after the preview.
9. Merge per-step files / Excel: client side (your files). submit_daily_report stores the finished summary.
Every list tool pages with limit and offset or returns a result handle for get_result - never ask for everything at once.

SPONSORED BRANDS VIDEO (SBV) CAMPAIGNS
- create_campaign builds SP and SD chains; SB (incl. video) create is being added behind an admin switch (v76).
  Until it is on, the proven way is Amazon's bulk upload. Validated recipe (ticket 18, tea leaf & co. US):
  1. Bulksheets 2.0 template "Sponsored Brands" (NOT the 2025 video template - rejected every row).
  2. One block per campaign: Campaign row (Entity=Campaign, Operation=Create, Budget type=Daily, Bid optimization
     = Manual, Brand entity id, Landing page type=Store/Product list) -> Ad group row -> Ad (creative) row with
     Creative type=video, Video asset id from the creative assets library, Brand name/logo asset ids ->
     Keyword rows (Match type exact, bid) -> Negative keyword rows.
  3. Ids must be text (apostrophe prefix in Excel) - numeric cells lose precision and Amazon rejects them.
  4. Upload in Campaign manager > Bulk operations; download the result file and read the Status column.
- Performance of SB video campaigns is read with get_campaign (ad program SB) / get_performance_data.