mcp-playbook — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited mcp-playbook (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
The MCP exposes affiliate/distribution features. Product onboarding tools are temporarily hidden. 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.
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.
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.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.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.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.list_affiliate_orders (TC dimension — the canonical "我分销卖了多少" answer; target_collaboration_id REQUIRED), list_customer_creator_orders (🚨 naming trap — CA dimension, NOT distribution GMV).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).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).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.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.manage_sample_auto_approval (get/update rules), manage_sample_applications (list/approve/reject the manual queue).list_shops, list_products, get_product_detail, list_creator_categories.Renamed tools — never call the old names:list_email_templates→manage_email_templateswithaction:'list';list_shop_orders→list_affiliate_orders;list_segments/list_journeys→manage_segment/manage_journeywithaction:'list'(list returns both official + custom entries).
Product onboarding is temporarily unavailable. Do not claim that an affiliate automation creates a new TikTok Shop listing, and do not call historical product-listing tool names.
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 paramsOnly skip a phase when the user explicitly supplied that data. Don't invent defaults for shop or products.
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.
Read completeness rules:
get_creator_detail: select the creator.s market first and pass region; when a shop is known, also pass its shop_cipher. Never reuse a user_id across markets without resolving scope again.get_affiliate_content_products: always pass the shop_cipher of the shop that produced the content_id; a shop-wide product overview without shop scope is invalid.Partial result or non-empty structuredContent.partial_errors, report which subsection failed. Do not reinterpret missing metrics, dashes, or empty arrays from that subsection as real zero/no-data values.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.
| Path | Entry | Produces | When |
|---|---|---|---|
| Automation-wrapper (default) | preview_target_collab → create_target_collab / create_tc_dm_automation | An automation that owns a TC — templates, follow-ups, schedule | User says "建一个推广 / 自动化 / outreach" |
| Direct entity | preview_target_collab_direct → create_target_collab_direct | A bare TC, no wrapper / DM / follow-ups; manage via update_target_collab_direct, cancel_target_collaboration, add_creator_to_target_collaboration | User has exact `creator_open_ids` (NOT user_ids, NOT handles) and wants the offer pushed now, or batch work via create_bulk_tc_operation |
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.
"公开合作 / 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.
When asked which creators in a TC can be removed, audit evidence first. A TC-level count or an invitation status such as NORMAL does not identify which creator joined the showcase, posted TC content, or applied for a sample.
list_target_collaborations with the authorized region/shop and read the required pages. Its pagination.count=10000 can be a backend cap, not an exact total. If a list row says 6 invited but detail lists 50, report the conflict and stop; do not choose one count as truth.get_target_collaboration_detail(target_collaboration_id=<UUID id from the list>, shop_cipher=<same shop>, include_sample_audit=true). The detail endpoint requires the internal UUID. The audit internally queries sample applications with the distinct tts_target_collaboration_id (TikTok TC ID); sending the UUID to the sample endpoint yields code 101. Do not swap these IDs manually. If querying the generic sample list directly, pass that TikTok numeric ID as a string in manage_sample_applications(action='list', target_collaboration_id=...), never the detail UUID.has_free_sample only means samples are offered. Group totals, global video counts, and NORMAL are not per-creator evidence of showcase/content/sample activity.create_bulk_tc_operation(remove_creators), update_target_collab_direct, or another write tool from an audit request. A later removal requires separate account-specific reconciliation, an explicit candidate list, and explicit user confirmation.| Tool | Answers | When |
|---|---|---|
list_automations | "What does the list look like?" | Browsing / finding an ID / filtering by status+type |
get_automation_detail | "What is this configured to do + overall stats?" | Name/ID → config / shop / product / filter / overview |
get_automation_task_results | "What did this task actually do?" | Per-creator outreach results or TC bulk-operation metrics |
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 only when the automation has one unambiguous matching task. Draft automations return empty (start first). If a TC automation has multiple tasks, call get_automation_detail, choose the intended task, and pass its task_id; never silently use the first task.Treat task_type as the contract for interpreting TC task results. Numeric strings such as "103" mean the same thing as numbers.
task_type | Meaning | Report as |
|---|---|---|
101 | Create / initial TC outreach | Per-creator invitation outcomes |
102 | Add creators | Planned creators, actually added creators, failures |
103 | Remove creators | Planned removals, actually removed creators, failures |
104 | Add products | Planned products, actually added products, failures |
105 | Remove products | Planned removals, actually removed products, failures |
106 | Edit TC settings | Fields requested, success/failure, failure reason if present |
107 | Cancel TC | Cancellation outcome and failure reason if present |
creator_planned / product_planned are the intended scope before execution; creator_added, creator_removed, product_added, and product_removed are actual outcomes. They describe different stages of the same operation: never add them together and never relabel a removal as Invited.excute_result; execute_result is also accepted. Interpret either using the selected task_type, not with the generic TC invitation table.result: "Success!" is an execution outcome, not a failure reason. Show failure reasons only for failed/skipped entries or explicit failure fields.task_type is unknown, say that the subtype is unsupported and preserve the raw result. Do not guess a task meaning, synthesize a missing reason, or force the payload into another task's table.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").clone_and_modify_automation + delete_automation the old one.Treat every list response as a page unless completeness is proven by the response.
list_affiliate_content, list_conversations, get_conversation_messages, and product/video performance breakdowns. Pass every returned next_page_token back unchanged as page_token.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.total is absent and the page is full, describe the result as a page and preserve the possibility of more data.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.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.ACTIVATE (also the Copy-flow silently drops non-ACTIVATE products). Tell the user to reactivate; no workaround.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.list_target_collaborations first → loop per TC. OC dimension not supported.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.| Param | Effect | Default | |
|---|---|---|---|
| `reply_handling: 'continue' \ | 'stop_on_reply'` | stop pinging creators who replied | continue |
skip_creators_with_prior_replies: bool | skip creators with prior replies | false | |
skip_messaged_within_days: number (0=off) | skip anyone messaged within N days | off |
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`.
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.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.
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.manage_sample_auto_approval get/update sets the rule thresholds; manage_sample_applications list uses region + optional decimal shop IDs in shop_id_list (preserve the exact ID string; do not round a 19-digit ID through a JavaScript number; omit 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. To filter the list to one TC, use its tts_target_collaboration_id (TikTok numeric ID, as a string) from list_target_collaborations; the internal id/UUID is only for get_target_collaboration_detail, not this sample filter. For per-TC cleanup evidence, prefer get_target_collaboration_detail(include_sample_audit=true) instead of inferring from the generic sample queue. Backend code 101 (bad parameters), code 102 (rate limit), or incomplete pagination means the applications are unknown, not zero; do not use such a result to clear a creator for removal.
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.confirm:true. Surface the plan, then wait.preview_target_collab filter schema: every field shape, enum buckets, the ×100 / no-×100 rules, and a natural-language→filter example.~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.