Native playbooks

The get_playbook tool exposes these workflows directly to a connected model. A playbook is an ordered recipe, not a permission. It grants nothing: every step uses the same tools your connector already holds, so a read-only connector runs the read steps and stops where a playbook would write.

Golden rule

1. Discover the shop and region with list_shopee_shops, list_lazada_shops, or list_tiktok_shops. Never guess an identifier.
2. Start with a small diagnostic or summary call.
3. Drill into a signal's suggested tool only when the question requires that detail.
4. State the date range, local currency, and any uncertainty from estimated COGS or settlement lag.
5. Report or simulate first. If the next step writes, name the tool and the exact change, and wait for the user's go-ahead — then say plainly what changed.

cite-basis

Use this for every figure the assistant reports. It is the one playbook that applies to all the others.

Workflow

1. Name the tool, the shop, and the exact date range the tool returned — not the range that was asked for.
2. State the assumptions: VAT view, explicit versus inferred COGS, and realized versus order-based.
3. Relay the [DataGlass call basis] block that ends every tool result rather than paraphrasing it away.
4. When a number disagrees with Seller Center, check the definition before suspecting missing data. Seller Center GMV counts every order placed; a DataGlass realized overview counts settled lines only, so recent days read low by design.
5. Remember that Shopee buckets settled lines on the order date and backfills, while TikTok and Lazada bucket on the settlement date and do not.

Example scenarios

• Why doesn't this match what Seller Center shows me?
• Which exact date range and VAT setting did you use for that number?
• Is this figure realized or order-based?

getting-started

Use this when the user has just connected DataGlass or does not know which shops and data are available.

Workflow

1. List shops for the relevant marketplaces.
2. Explain that shop tools require the returned shop identifier and region.
3. Clarify that realized values are cancellation-adjusted, money is local currency, and the connector is read-only until a write scope is approved.

Example scenarios

• Show all shops I can analyze and group them by marketplace.
• Which region and currency does each connected shop use?
• What can I learn from DataGlass before we analyze a specific shop?

shop-health-check

Use this for a quick, all-round assessment of one shop or a compact portfolio view.

Workflow

1. Call diagnose_shop with a 30-day lookback for one shop.
2. Relay the headline plus warning and critical signals.
3. Follow a signal's suggestedTool only when the user wants evidence.
4. Use get_financial_overview instead when the request covers all shops.

Example scenarios

• Give {shopName} a 30-day health check and flag urgent risks.
• What changed this week compared with last week?
• Summarize profit and margin across all connected shops.

why-profit-dropped

Use this to root-cause a decline in realized profit, GMV, or sales.

Workflow

1. Start with diagnose_shop and read KPI deltas and signals[].
2. For GMV or profit decline, inspect platform product breakdowns and profit rankings.
3. For margin compression, inspect cost, commission, and commission-impact tools.
4. Check missing COGS and settlement lag before calling the decline final.
5. Check ads when spend rose or True ROAS fell, then summarize the largest driver first.

Example scenarios

• Why did realized profit drop in {period}? Rank the causes.
• GMV is stable but margin fell. Which cost line changed?
• Is this decline real, or could missing COGS or unsettled orders explain it?

improve-low-margin

Use this to find thin-margin or loss-making products and evaluate remedies.

Workflow

1. Read the platform financial overview and note loss-makers and COGS coverage.
2. Rank or break down the worst products.
3. Confirm explicit, inferred, or missing cost with get_product_costs.
4. Test a price, discount, or COGS remedy with the platform simulation tool.
5. Retrieve price-buffer or margin-defense recommendations when fee pressure is the cause.

Example scenarios

• Which products lose the most money, and why?
• Find low-margin products with the greatest total profit impact.
• Compare a price increase, discount reduction, and COGS reduction for the worst product.

debug-ads

Use this to find weak campaigns and retrieve profit-aware bid, budget, or target-ROAS guidance.

Workflow

1. For Shopee, sort get_shopee_ads_performance by profit-adjusted ROAS ascending.
2. Confirm suspect performance with corrected or product True ROAS.
3. Retrieve Shopee target-ROAS, ads, or GMS recommendations. For TikTok, use GMV Max campaigns, True ROAS, budget, and target-ROAS recommendations.
4. Explain the recommendation and the evidence behind it. With PAT_ADS_WRITE granted, apply it with apply_shopee_target_roas or change a live campaign with control_ad_campaign — but state the current versus proposed value and get an explicit go-ahead first, because both change real spend immediately. revert_shopee_target_roas undoes an applied target. Without the scope, hand the user the numbers and the link.

Example scenarios

• Which campaigns have the weakest True ROAS this month?
• Find ads that look profitable in the marketplace but lose money after all costs.
• Where should I raise, hold, or cut budget, and why?

defend-margin-commission

Use this when a marketplace commission-rate change may compress margin.

Workflow

1. Retrieve the platform commission overview and impact for the effective date.
2. Read the matching Shopee or TikTok margin-defense actions.
3. Validate a selected price or discount adjustment with a profit simulation.
4. Present the expected impact, smallest safe adjustment, and effective date.

Example scenarios

• How much will the upcoming commission increase cost by product?
• What is the smallest adjustment that preserves our current margin?
• Compare raising price with reducing discount for the most exposed products.

plan-restock

Use this to decide what to reorder, how much to buy, and why.

Workflow

1. Retrieve open inventory alerts.
2. Read the (s,S) reorder plan by variant.
3. Use forecast and demand charts to explain the suggested quantity.
4. Check open purchase orders so inbound units are not ordered twice.

Example scenarios

• Which SKUs need restocking now?
• Build a reorder plan that accounts for forecast demand and inbound stock.
• Which products look overstocked or slow-moving?

check-cogs

Use this to identify products whose profit depends on missing or inferred product cost.

Workflow

1. Read cogsCoverage from the shop financial overview.
2. Retrieve product costs and distinguish explicit, inferred, and missing values.
3. Use get_estimated_margin for the Shopee shop-level inference when needed.
4. Prioritize products where a real entered cost would most improve profit confidence.

Example scenarios

• Which products are missing explicit COGS?
• How much reported profit depends on estimated costs?
• Rank the missing-cost products by likely distortion to profit.

simulate-price-change

Use this to test a price, discount, or COGS change before the seller decides whether to act.

Workflow

1. Find the product and retrieve its current unit economics.
2. Run exactly one platform-specific simulation for each proposed scenario.
3. Compare current and simulated profit and margin, including assumptions.
4. Describe the result as a what-if; nothing is written.

Example scenarios

• What happens to margin if I raise this product's price by 5%?
• Compare a 15% discount with a 10% discount.
• What unit COGS would this product need to reach a 20% margin?

conventions

Use this when a request fails because of date, platform, identifier, pagination, VAT, or money conventions.

Workflow

1. Re-resolve shop and product identifiers rather than guessing.
2. Use YYYY-MM-DD calendar dates, YYYYMMDD conversion datadates, and ISO 8601 timestamps.
3. Preserve all TikTok identifiers as strings.
4. Follow nextCursor for another page only when necessary.
5. State local currency and whether inferred COGS or VAT settings affect the answer.

Example scenarios

• Which dates will you use for last month and its comparison period?
• Resolve the correct shop and product IDs for this question.
• Explain why payout, realized profit, and True ROAS answer different questions.

Retrieve a playbook

Call get_playbook without a playbook value to receive the index, or provide one exact name:

{
  "playbook": "why-profit-dropped"
}

The runtime response is the source of truth for the workflow text available to the connected assistant.