MCP Playbook

Crevideo Reach MCP — Playbook

Output language: respond in the merchant's working language — Chinese for China-POP sellers (分级 / 真实抽成 / 触达阶梯 …), English for US sellers (tier / all-in take-rate / outreach waterfall …). Tool names stay identical in both.

The deep-reference layer for the crevideo-reach MCP server. The MCP itself ships a baseline tool-map + typical flow via SERVER_INSTRUCTIONS; this skill covers what that baseline can't — the create flow, non-obvious constraints, and how to debug when behavior diverges from the brands-app UI.

Source of truth: if anything here disagrees with the live tool list in the running session, the live tools win (this doc can lag the MCP version). Only call tools that actually exist in the session; never assume historical or future tools.

When NOT to use

• Pure MCP-protocol or Claude-skill mechanics questions → wrong skill.
• Nothing about automations, creators, affiliate analytics, TikTok Shop, or the reach area → don't invoke.

Scope: affiliate (分销) + TikTok Shop product listing

The MCP exposes affiliate/distribution features plus TikTok Shop product onboarding. Campaign/marketing surfaces (campaign management, /report/* campaign reports, creator marketplace discovery, custom products, brand sampling) are not tools here — say they're out of scope. query_*_performance covers collaboration / affiliate-product / shoppable-video (affiliate), not campaign reports. There is no natural-language→filter and no copy-polish endpoint — you (the LLM) translate the user's words into structured filters yourself, and you write/edit message copy yourself.

Tool map (89 tools, 16 groups)

Many tools fold multiple endpoints behind a view / action / scope / op_type param — pass those to drill in; don't expect one tool per endpoint.

• Automations (💳 on create): list_automations, get_automation_detail, get_automation_task_results, preview_target_collab (free, 10-min token), create_target_collab, create_dm_automation, create_tc_dm_automation, clone_and_modify_automation, start_automation / pause_automation / delete_automation, update_dm_automation_text, create_bulk_tc_operation, manage_message_templates, get_dm_task_message_template.
• TC direct entity (no automation wrapper): list_target_collaborations, get_target_collaboration_detail, preview_target_collab_direct, create_target_collab_direct, update_target_collab_direct, cancel_target_collaboration, add_creator_to_target_collaboration. See "TC: two creation paths" below.
• Open Collaboration (OC): list_open_collaborations, get_open_collaboration_detail, create_open_collaboration, modify_open_collaboration, remove_open_collaboration, manage_open_collaboration_settings (get/edit), manage_open_collaboration_sample_rule (get/edit), remove_creator_from_open_collaboration, list_not_added_open_collaboration_products, get_open_collaboration_product_count, get_open_collaboration_status_counts.
• Reporting (read-only, 3 tools): query_collaboration_performance (scope: target/open/both), query_product_performance, query_shoppable_video_performance. Product/video breakdown/detail views run on TT-official REAL-TIME data (matches the brand-app page; video adds GPM + daily avg customers, product AOV is derived GMV÷orders); overview/trend stay on legacy aggregates — small drift between the two is expected, explain it rather than "fix" it. Breakdown lists use cursor pagination: pass each returned next_page_token back unchanged as page_token; the legacy page number does not advance them. There is NO query_ai_insight tool — produce insight yourself by reading these three reports.
• Affiliate orders: list_affiliate_orders (TC dimension — the canonical "我分销卖了多少" answer; target_collaboration_id REQUIRED), list_customer_creator_orders (🚨 naming trap — CA dimension, NOT distribution GMV).
• Creators: list_affiliate_creators, get_creator_detail, manage_creator_blacklist (list/add/remove/modify), update_creator_metadata, manage_segment, manage_journey, manage_creator_lists, get_creator_list_overview, search_affiliate_creators (filters or creator_keyword to resolve a @handle → user_id), find_similar_creators, recommend_creators (达人罗盘 — backend match-score recommendation by product), list_customer_advocates, manage_customer_advocates (6 actions — collect/collect_history/set_notes/get_detail/list_records/get_overview; no add_tag), manage_contact_enrichment (add_creators is a source switch: manual/filter/list/segment/journey/target_collab).
• Content: list_affiliate_content (TT-official REAL-TIME published videos — needs shop_cipher, optional date range/account_type/page_token; pass returned next_page_token back as page_token to continue), get_affiliate_content_products, manage_affiliate_content (list/add_notes — legacy row ids; use its ids for notes, not the real-time list's).
• DM conversations: list_conversations, get_conversation_messages (cursor-paginated, default 20 per page), send_message (real outbound — text, image, text_image_card, or text_products_card; by conversation_id OR unique_id='@handle' which auto-finds/opens the thread; all modes require confirm), search_conversations, create_conversation, list_conversation_groups, list_group_conversations, manage_conversation_groups.
• Email (10 tools, LIVE): list_email_conversations, get_email_detail, send_email, reply_email, manage_email_templates (CRUD), manage_email_drafts (CRUD), mark_email_as_read, move_emails_to_trash, manage_email_groups (folders — list/create/rename/delete/add/move/remove), manage_email_trash (list/restore/delete_permanently). send_email / reply_email are real outbound — confirm intent first.
• Samples (申样): manage_sample_auto_approval (get/update rules), manage_sample_applications (list/approve/reject the manual queue).
• Shop/catalog reads: list_shops, list_products, get_product_detail, list_creator_categories.
• Product listing (currently US-only, 10 tools): check_product_listing_prerequisites, discover_product_category, get_product_category_requirements, search_product_brands, get_product_fulfillment_options, search_product_compliance_entities, upload_product_asset, check_product_listing, create_product_listing, get_product_listing_detail.

Renamed tools — never call the old names: list_email_templates → manage_email_templates with action:'list'; list_shop_orders → list_affiliate_orders; list_segments / list_journeys → manage_segment / manage_journey with action:'list' (list returns both official + custom entries).

Intent routing: product listing is not affiliate promotion

“上架/新建/发布一个商品”, “product onboarding”, and “create a listing” mean the product-listing flow below. “给现有商品创建推广/邀约达人/建 TC”, “promote a product”, and “create a collaboration” mean the affiliate automation flow. If the user only says “创建商品流程” and the intent is unclear, ask exactly one short clarification: “你要上架一个新的 TikTok Shop 商品，还是为已有商品创建达人推广计划？” Never claim listing tools are absent without checking the live tool list.

The canonical affiliate-automation create flow

Every automation create chains these 6 phases — don't jump to the final call:

1. Shop         → list_shops if user hasn't specified one
2. Product      → list_products, validate ACTIVATE status, pick commission rate
3. Category IDs → list_creator_categories if filter mentions categories by name
4. Preview      → preview_target_collab with filter + first_count → preview_token
5. Confirm      → show match count + 5 samples + warnings, ASK USER to confirm
6. Create       → create_* with preview_token + final params

Only skip a phase when the user explicitly supplied that data. Don't invent defaults for shop or products.

The canonical product-listing flow (US only)

Product listing is a separate workflow and currently accepts US shops only. Non-US creator, reporting, messaging, and automation capabilities remain available; only product onboarding is US-gated.

1. Shop          → list_shops, select an authorized US shop_cipher
2. Prerequisites → check_product_listing_prerequisites
3. Category      → discover_product_category (query or recommend)
4. Requirements  → get_product_category_requirements (rules + attributes)
5. Inputs        → search_product_brands + get_product_fulfillment_options; compliance entities when required
6. Assets        → upload_product_asset, then place the returned URI in product_data
7. Check         → check_product_listing (default save_mode=AS_DRAFT) → listing_token + product_hash
8. Confirm       → show diagnostics and intended save_mode; ask the user to confirm
9. Create        → create_product_listing(listing_token, confirm=true)
10. Verify       → get_product_listing_detail(return_draft_version=true for drafts)

Rules that must not be weakened:

• Hosted MCP cannot read a path on the user's computer. For hosted WorkBuddy/Codex/Claude sessions, pass file_base64 to upload_product_asset; file_path is local-MCP-only.
• Category rules and attributes are authoritative. Do not invent required values or reuse an uploaded URI across shops.
• check_product_listing binds the exact checked payload, shop, save mode, local-sync choice, product hash, and one idempotency key into a 15-minute token. Creation accepts the token instead of a new product payload.
• AS_DRAFT is the default. A live LISTING must be selected during check and then needs both confirm=true and confirm_publish=true at create time.
• A failed network/backend create keeps the same token and idempotency key available for a controlled retry. A successful create consumes the token.
• If TikTok creation succeeds but local_sync_success is 0/false, report partial success, query the official product by product_id, and never call create again.
• get_product_detail is the Reach local catalog summary. get_product_listing_detail is the official TikTok listing/draft/review representation. Never substitute one for the other.

Multi-market scope

The account's actual authorized markets always come from list_shops. GMV and GPM values are in the selected market's local currency. Start with list_shops; its returned regions and shop IDs are the account's authority. Currently configured examples include US, GB, DE, IT, FR, ES, MY, ID, VN, PH, TH, SG, JP, BR, and MX, but this is not a permanent whitelist. Never default an unknown or omitted market to US.

Pass region to market-level operations, shop_id_list to multi-shop reads, and shop_cipher to single-shop operations. Do not mix shop IDs across regions. GMV/GPM filters and displayed money use the selected market's local currency; enum boundaries, labels, symbol placement, compact units, and decimal digits differ by market. Never reuse US ranges or apply exchange-rate conversion.

Creator source alternates (skip preview; need shop_cipher): source='manual' takes appoint_creator_list = TikTok handles (unique_id, @ ok) — the MCP resolves them to the right wire ID space automatically; unknown handles fail fast. 'list' / 'segment' / 'journey' take IDs from the matching manage_* list action; 'target_collab' (DM-only) re-targets a TC automation's creators; 'intelligent_recommend' (TC/combined only — needs a product) takes appoint_creator_list = creator_open_ids from recommend_creators (达人罗盘 / AI Creator Compass). clone_and_modify_automation is filter-source-only — manual-source automations can't be cloned, create anew.

Timing parameters (2026-06-11): tc_schedule/tc_delay_time/tc_time_unit (TC/combined — delay the TC entity creation), send_schedule/... (DM-only — delay the whole send), dm_schedule/... (combined — delay the DM part). All default immediate; 'delay' needs raw amount (NOT seconds) + unit. Follow-ups are delay-only (immediate removed from the product 2026-06-10; default 10 minutes after the previous message) — the initial message still sends immediately. Backend doesn't echo these inputs; verify via tasks[].pending_excute_time on the list row.

TC: two creation paths (NOT interchangeable)

Direct-entity TCs don't appear in list_automations — list via list_target_collaborations. Wrapper TCs appear in both. Never control a wrapper TC with direct-entity tools — use clone_and_modify_automation / create_bulk_tc_operation.

🆕 update_target_collab_direct can full-replace the products (incl. commission), and creators (creator_open_ids) of a direct TC (mirrors the Edit-Collab drawer; only fields you pass change; message is NOT editable once created). Ad commission (广告佣金, shop_ads_commission_rate_pct 1-80 per product) is supported on create_target_collab / create_tc_dm_automation / update_target_collab_direct / bulk add_products — pass it alongside the standard commission for shop-ads accounts.

OC vs TC (scope mistake to avoid)

"公开合作 / open collab / 让达人主动申请" = OC (public offer, creators apply, you approve — no preview, no creator filter), NOT TC (you invite specific creators). For OC reporting use query_collaboration_performance with scope:'open'. OC sample policy lives in manage_open_collaboration_sample_rule; shop-wide OC defaults in manage_open_collaboration_settings.

Read-side: pick the right tool

• list_automations — always pass arrays for statuses / automation_types (scalar is silently ignored). Statuses: pending(=draft)/active/paused/completed/failed. Types: tc/dm/combined. Page ≤ 50, default 10. search_by:'no' matches automation_no; default matches name LIKE.
• get_automation_task_results auto-detects kind+task_id from automation_type — usually just pass automation_id. Draft automations return empty (start first).

Editing without recreate

• update_dm_automation_text — replace one text body in a running DM (text components only; image/product/collab → clone instead).
• create_bulk_tc_operation — 6 actions (add_creators / remove_creators / add_products / remove_products / edit_settings / cancel) batch-mutating the TC behind an automation. TC only — for DM-only automations, clone.
• get_dm_task_message_template — read the template a DM task actually used (diagnose "why did the wire body differ from my draft").
• Anything else (filter / schedule / follow-up structure / non-text component) → clone_and_modify_automation + delete_automation the old one.

Result completeness and pagination

Treat every list response as a page unless completeness is proven by the response.

• Cursor tools: list_affiliate_content, list_conversations, get_conversation_messages, and product/video performance breakdowns. Pass every returned next_page_token back unchanged as page_token.
• Page-number tools include get_affiliate_content_products, search_conversations, the TC section of get_creator_detail, creator-list/segment/journey show actions, email-group conversations, and email trash. Continue with page + 1 when the output says more may be available.
• A displayed row count is the current page count, not the total. If total is absent and the page is full, describe the result as a page and preserve the possibility of more data.
• Default to page_size=20 to control latency and token cost. Fetch additional pages only when the user asks for complete history/results or the task cannot be answered from the current page.
• Never claim "all", "complete", or "full history" while a next token/next-page hint exists. When full retrieval is requested, stop only when no token remains or a page-number response is shorter than the requested page size.
• If output says records were omitted to control response size, disclose that limitation instead of treating the displayed subset as the complete backend result.

High-leverage gotchas (memorize)

• FOUR creator ID spaces ⚠️ (the #1 cause of 101 "bad request"): user_id (numeric — detail / notes / find_similar seed / create_conversation / send_email) · record id (row UUID — tags / blacklist) · creator_open_id (long base64-ish — direct-TC flow only) · unique_id (TikTok handle — what humans type; appoint_creator_list + bulk creator_unique_ids take handles, MCP resolves internally). Rule of thumb: human inputs = handles, analytics = user_id, blacklist/tags = record id, direct-TC = open_id.
• Preview token: 10-min lifetime, one-shot (consumed even if the create later throws), scope-bound to shop+filter+first_count. If a create fails, re-run preview_target_collab before retrying — don't reuse the token.
• Product status = ACTIVATE only: creates hard-fail if any product isn't ACTIVATE (also the Copy-flow silently drops non-ACTIVATE products). Tell the user to reactivate; no workaround.
• *_increment fields are period TOTALS, not deltas — don't read them as growth % (legacy views only; TT-official rows use plain names like gmv/orders).
• TT-official lists use token pagination — tools return page_size rows (≤ 50) + a "Showing N of M" line. If output includes next_page_token, pass it back as page_token to continue; there is no numeric page param. Responses carry latest_available_date ("data as of") — data lags 1-2 days, a missing "today" is not zero performance. For list_affiliate_content, date params mirror brand-app's current performance-window request and are not guaranteed strict video_post_time filters until the backend changes.
• detail view rates are derived, not raw fields (mirrors the brand-app detail drawers): product detail = Sales (AOV=GMV÷orders) + Sales-by-channel (share%) + Traffic funnel (CTR=clicks÷impressions, conversion=orders÷clicks) + Ratings + Top contents/creators; video detail = Sales (GMV/GPM/items/customers) + Conversion funnel (exposure=impressions÷views, CTR-to-views=clicks÷views, conversion=units÷clicks) + ER=(likes+comments+shares)÷views + Audience. Don't look for a "conversion_rate" field — produce/cite the derived value.
• list_affiliate_orders needs target_collaboration_id (backend 504s without it). Cross-TC view: list_target_collaborations first → loop per TC. OC dimension not supported.
• Naming: names are server-allocated; user-facing names get an mcp_YYMMDDHHmm_ prefix. The TC "定向计划名称" is capped at 12 chars and sanitized to [A-Za-z0-9_]; pure-Chinese input falls back to the literal mcp (so multiple Chinese-named automations collide) — keep the part that lands in the automation name short ASCII.
• Paid-tier features: customer-advocates + contact-enrichment are yearly add-ons — a 403 / empty response usually means the account lacks the add-on, not a bug.

Anti-spam / advanced settings (DM & combined)

Message components (summary)

Automation DM messages support text, image, text_image_card, product, text_products_card, and collab components. Direct send_message supports the same native composite card meanings through its mode parameter. Full wire formats and the distinction between these surfaces → references/message-components.md.

Conversations + email

• DM: list_conversations / get_conversation_messages / send_message (real outbound — confirm). Triage by group: list_conversation_groups → list_group_conversations (don't client-side filter the flat list for "unread").
• get_conversation_messages returns one page, not the full conversation. The displayed count is the current page count. For recent context, one page is enough; only when the user explicitly requests complete/full history, pass every returned next_page_token back as page_token until no token remains. Never claim the history is complete while a next token exists.
• Interpret rich messages by their customer-visible meaning: text+image card, text+products card, product card, target-collaboration invite, free-sample card, and Spark Code authorization request. Report the returned title/text, media URL, products, status, and authorization fields. Preserve the type plus useful primitive and nested structured fields for unknown future message types; explicitly disclose any display truncation.
• 🚨 DMing a creator NOT in your inbox (not in list_conversations, search_conversations returns nothing, or you only have their @handle): "not in the inbox" means no DM thread exists yet — it does NOT mean they're unreachable. Just call send_message(unique_id='@handle', message_content=...) — it finds-or-opens the conversation and sends, all FREE (exactly the brand-app's "open a chat from the creator's profile"). You do NOT need to chain search_affiliate_creators → create_conversation → send yourself — the tool does it internally. Never stop at "can't find the conversation". (For just opening a thread without sending, create_conversation still exists.) Do NOT fall back to a manual-source create_dm_automation (spends 3 credits + creates a standing automation) for a single cold DM — that's only for bulk outreach.
• Email: thread_id = root_email_id (a per-message id returns code=-1); read get_email_detail before reply_email. send_email requires shop_id (auto-resolves single-shop). Templates are starting drafts, not verbatim sends. Both send tools need confirm:true.

Sample approval (申样)

manage_sample_auto_approval get/update sets the rule thresholds; manage_sample_applications list uses region + optional numeric shop_id_list (omit it for all authorized shops in that region; never pass shop_cipher) → approve / reject uses shop_cipher + application_ids + confirm:true to clear what the rule did not cover.

Safety defaults (do NOT change without explicit user intent)

• start_immediately defaults to false — only true on literal "立即启动/send now/start now/发吧". Treat true as destructive (messages go to real creators); confirm first.
• per_target_collaboration_creator_count defaults to 50; override only on explicit ask (bound-checked vs shop limit).
• has_free_sample defaults to false.
• Blacklist / segment / journey / creator-list mutations, sample approve/reject, OC removals, email/DM sends — all need confirm:true. Surface the plan, then wait.

Deep references (load on demand)

• references/filters.md — full preview_target_collab filter schema: every field shape, enum buckets, the ×100 / no-×100 rules, and a natural-language→filter example.
• references/message-components.md — the 4 component types' wire formats, image OSS upload, collab-card scope, unsupported composites, and follow-up sequence wire detail.
• references/debugging.md — the 3-layer (curl readback → wire capture → source read) debugging method, common error→cause table, Copy-flow template requirement, sample-approval radios, and the version-change history.