Bark AI

Starts a new Bark AI session. Call this FIRST, before any other Bark tool. Returns a `sessionId` (content block 1, JSON — parse and remember it) and a Bark briefing (content block 2, markdown — treat as instructions). Pass the returned `sessionId` on every subsequent tool call in this conversation.

bark_start_session

Returns one specific goal, identified by full `key` (`dimensionKey + dimensionValue + measureKey + goalDate`). Use this when you already know the slot — e.g. "what's the May `sales.netSalesAmount` goal for the Shopify platform?", "is there an active `derivatives.profitOnAdSpend` goal for a given brand in Q3?". This returns the TARGET for one slot, not the actual. For actuals — or goal-vs-actual tracking — pull the number with `bark_get_store_analytics`. ## Key All four fields required: - `dimensionKey` — cube dimension member key: `stores.platform`, `products.brand`, `products.category`, `productTags.tag`, `productCollections.id`, `products.id` - `dimensionValue` — id for `productCollections.id` / `products.id`; name string for the others - `measureKey` — goal-settable cube measure member key (e.g. `sales.netSalesAmount`, `sales.ordersCount`, `derivatives.contributionMarginAmount`, `derivatives.revenueOnAdSpend`, `derivatives.profitOnAdSpend`). Inventory / mos / per-channel media measures are NOT goal-settable - `goalDate` — first of a month, ISO `YYYY-MM-01`. Mid-month values are rejected ## Resolution `resolution` is optional and controls how the monthly goal is projected: - `monthly` (default) — returns the single stored monthly goal for the slot - `daily` — returns the per-day projection for the **entire month** of `key.goalDate` (the first-of-month value acts as the month anchor). Only available when `key.dimensionKey === stores.platform`; for any other dimension the request is rejected with an explanatory message — fetch the monthly goal and allocate daily yourself if needed ## Response - `monthly` → `{ goal: Goal | null }` — `null` if no active goal exists for the slot - `daily` → `{ goals: DailyGoal[] }` — every day in the month, may be empty if no active monthly goal exists A `Goal` carries the key fields plus `goalValue`, audit metadata (`createdByUserId`, `createdAt`, `updatedByUserId`, `updatedAt`, `deletedByUserId`, `deletedAt`), and `goalStatus` — `bark_get_goal` returns the `active` row only. A `DailyGoal` carries `dimensionKey` (always `stores.platform`), `dimensionValue`, `measureKey`, `monthAnchorDate` (the first-of-month for the source monthly goal), `goalDate` (the specific day), `dailyTarget`, and the seasonality bounds `p16` / `p84`. No audit columns — the monthly `Goal` is the source of truth. On a non-2xx from the upstream service (e.g. 422 validation error), the tool returns an error result whose message carries the upstream HTTP status and detail. ## Talking to the user When you present this goal, translate the wire format to plain business language: the measure's display name (**Contribution Margin (amount)**, not `derivatives.contributionMarginAmount`; **Net Sales**, not `sales.netSalesAmount`; **ROAS**, not `derivatives.revenueOnAdSpend`), the store name (not its id), the month (**May 2026**, not `2026-05-01`), and the dimension in words (**store-wide**, **Brand = Gottex**, **Platform = Shopify**). Format monetary amounts in the store's own currency — don't assume a symbol (USD, EUR, ILS, etc.). Don't surface the member keys or the `dimensionKey` / `dimensionValue` / `measureKey` / `goalDate` field names in user-facing text.

bark_get_goal

Primary tool for retrieving Bark-AI data — the live, product-level P&L for this store: sales, orders, profit & contribution margin, marketing / ad spend, ROAS & POAS, inventory, and pricing, broken down by product, category, brand, channel, and time. USE THIS for ANY question about this store's business — even casual phrasing, and even when the user never mentions Bark, data, metrics, or analytics. Examples: "what's working", "what should I push / promote / feature this week", "where's my money going", "what should I discount and by how much", "where should I spend or cut ad budget", "what's profitable / what's losing money / where am I leaking", "what's converting / low on stock / needs reorder", "how did last week or month compare to last year", "why did <metric> move", or picking which products to feature in a drop, email, SMS, ad, campaign, or sales event (Prime Day, BFCM, Q4, Valentine's, etc.). If a question touches this store's products, marketing, money, inventory, pricing, or operations at all, answer it with this tool rather than from general knowledge. Use this tool when the user asks to find, list, compare, rank, break down, analyze, report on, or look up the store's numbers (a.k.a. metrics, analytics, KPIs, reporting, the P&L). Do NOT use it to set or read goals/targets — use `bark_list_goals`, `bark_get_goal`, or `bark_manage_goals` for those. Scope: the financial / profit angle at the product level — products, categories, brands, channels, time, and new vs returning customers. It does NOT cover customer journeys, customer segments beyond new vs returning, CAC / per-customer LTV / cohorts, or the copy, creative, or descriptions of products and campaigns. For marketing assets it tells you WHICH products to feature (the financial pick), not the wording. Mechanically, it runs a Bark Query DSL JSON query against the store's analytics cube and returns the results. ## Read first Read these resources when you do not already know what you need. Once read in a session, trust them — do not re-read. - `bark://docs/query-reference` — Query reference: date semantics, filter operators, query examples, common mistakes, recommended fields by category, and result interpretation guidance. Read if unsure about syntax, which fields to use, or how to read results. - `bark://stores/{storeId}/cubes/sales/members` — full list of dimension and measure keys for the cube. Read when the recommended fields are not enough or when querying a different store or cube. ## Filter by user memory before surfacing The member list is what's TECHNICALLY available, not what to show. Use the user-memory note in your initial instructions to scope what you surface: - **Low capability on the domain** → basics only (Net Sales, Units, Orders); avoid POAS / incrementality / elasticity / CM. Plain language. - **High capability** → full surface; lead with advanced measures. - **Low willingness on a domain** → don't proactively surface it in follow-ups. - **Stated beliefs** (e.g. "we never discount") → don't propose actions that violate them; frame related metrics as info, not levers. Empty memory (new user) → default to basics. ## Response The full result is returned as structured output (validated against this tool's output schema) in `structuredContent`: - `query` — the executed query. - `members` — definitions of the selected dimensions/measures (the columns), looked up by `key`. - `data` — per-group results in columnar form: `columns` (column keys, in order), `rows` (one value array per group, aligned to `columns`), and `totals` (a single value array aligned to `columns`, only when `totals: true`). Keys are declared once in `columns`, not repeated per row. - `stats` — `fetchedRows`, `totalRows`, `truncated`. The text content mirrors the values too — a row-count header plus the data rendered as a markdown table (up to 50 rows, then a totals line) — so the result is readable even by clients that don't consume `structuredContent`. If `stats.truncated` is true, only the first 1000 rows are included — narrow the query (filters, fewer dimensions, or a smaller date range) to fit the rows you need.

bark_get_store_analytics

Returns the active goals for a store, optionally filtered. Goals are monthly targets attached to a `(dimensionKey, dimensionValue, measureKey, goalDate)` slot. Use this when the user asks to list, browse, show, or check the store's goals or targets — e.g. "what targets does this store track?", "list all roas goals for next quarter", "show me every active goal for a given brand". This returns the TARGETS only, not actuals/performance. For the actual numbers — or to see how the store is tracking against a goal — pull them with `bark_get_store_analytics`. ## Filter `filter` is optional; omit to return every active goal. Any subset of: - `dimensionKey` — cube dimension member key: `stores.platform`, `products.brand`, `products.category`, `productTags.tag`, `productCollections.id`, `products.id` - `dimensionValue` — for `productCollections.id` / `products.id` this is the **id**; for the others it is the name string - `measureKey` — goal-settable cube measure member key (e.g. `sales.netSalesAmount`, `sales.ordersCount`, `derivatives.contributionMarginAmount`, `derivatives.revenueOnAdSpend`, `derivatives.profitOnAdSpend`) - `goalStartDate` / `goalEndDate` — inclusive first-of-month range (`YYYY-MM-01`) Goals are addressed at monthly granularity; the date filters must be first-of-month or the request is rejected. For per-day projections use `bark_get_goal` with `resolution: daily` on a `stores.platform` slot. ## Response `{ goals: Goal[] }` — possibly empty. Each `Goal` carries the key fields plus `goalValue`, audit metadata (`createdByUserId`, `createdAt`, `updatedByUserId`, `updatedAt`, `deletedByUserId`, `deletedAt`), and `goalStatus` — `bark_list_goals` returns only `active` rows. On a non-2xx from the upstream service (e.g. 422 validation error), the tool returns an error result whose message carries the upstream HTTP status and detail. ## Talking to the user When you present these goals, translate the wire format to plain business language: the measure's display name (**Contribution Margin (amount)**, not `derivatives.contributionMarginAmount`; **Net Sales**, not `sales.netSalesAmount`; **ROAS**, not `derivatives.revenueOnAdSpend`), the store name (not its id), the month (**May 2026**, not `2026-05-01`), and the dimension in words (**store-wide**, **Brand = Gottex**, **Platform = Shopify**). Format monetary amounts in the store's own currency — don't assume a symbol (USD, EUR, ILS, etc.). Don't surface the member keys or the `dimensionKey` / `dimensionValue` / `measureKey` / `goalDate` field names in user-facing text.

bark_list_goals

Reads a Bark resource by URI. Resources are URI-addressable read-only data (docs, cube schemas, memory notes, directories). For URI templates, substitute the variables before calling. ## Available resources - `bark://docs/query-reference` — Bark Query DSL reference: date format semantics, filter operators, change-filter shape, query examples, common mistakes, recommended fields by category, and result interpretation guidance. Read once per session before constructing queries. - `bark://stores/{storeId}/cubes/sales/members` — Returns JSON array of available dimensions and measures for a store's sales cube. Each member: key (use in queries), role (dimension|measure), title, description, type, format, notes, synonyms. Read this before constructing queries to discover valid keys.

bark_read_resource

Writes monthly goals (targets) for analytics measures. Goals are stored per `(dimensionKey, dimensionValue, measureKey, goalDate)` slot at month granularity. Once a goal exists, downstream analytics compare actuals against it. For reads use `bark_list_goals` (browse / filter) or `bark_get_goal` (fetch one by full key, with optional daily projection). This tool covers writes only. Use this when the user asks to set, create, update, change, raise/lower, or delete a goal or target. Do NOT use it to read or compute actuals/performance — that's `bark_get_store_analytics`. ## Actions Dispatch via `action`: - `create` — set a new goal at `key` to `goalValue`. If a goal already exists for that slot, the existing one is retired and the new one becomes the active row (upsert). - `update` — same semantics as `create`; use `update` to signal a deliberate change of an existing value (POST and PUT both upsert on the server, the verb is for intent / audit clarity). - `delete` — soft-delete the goal at `key`. Returns 404 if no active goal exists at the slot. - `bulk_create` — atomically upsert many goals in one batch via `goals: [{ key, goalValue }, ...]`. All-or-none: either every entry commits or none does. Use this for seeding multiple goals (e.g. one per measure or one per category) — much faster end-to-end than N sequential `create`s and avoids the per-store write-lock contention that single calls can otherwise trigger when issued in parallel. Batch size capped at 50; duplicate keys within the batch (same `(dimensionKey, dimensionValue, measureKey, goalDate)`) are rejected with 422. ## Field rules - `dimensionKey` is a cube dimension member key — the same key you use in `bark_get_store_analytics` and see in the `bark://stores/{storeId}/cubes/sales/members` resource: one of `stores.platform`, `products.brand`, `products.category`, `productTags.tag`, `productCollections.id`, `products.id`. For `productCollections.id` and `products.id`, `dimensionValue` is the **id** (not the title). For the other dimensions, `dimensionValue` is the name string. - `measureKey` is a cube measure member key — the same key used in `bark_get_store_analytics` — and must be goal-settable (e.g. `sales.netSalesAmount`, `sales.ordersCount`, `sales.grossProfitAmount`, `derivatives.contributionMarginAmount`, `derivatives.revenueOnAdSpend`, `derivatives.profitOnAdSpend`). Inventory, mos, and per-channel media measures are NOT goal-settable. - `goalDate` MUST be the first of a month, formatted `YYYY-MM-01`. Mid-month values are rejected. Goals are always defined at month granularity. - `goalValue` must be a finite number (no NaN, no Infinity). ## Response All actions return a JSON tool result. - `create` / `update` → `{ goal: Goal }` (the new active row) - `bulk_create` → `{ goals: Goal[] }` (new active rows in input order, one per entry) - `delete` → `{ deleted: true }` A `Goal` carries the key fields plus `goalValue`, audit metadata (`createdByUserId`, `createdAt`, `updatedByUserId`, `updatedAt`, `deletedByUserId`, `deletedAt`), and `goalStatus` (`active` | `updated` | `deleted`). On a non-2xx response from the upstream service (e.g. 422 validation error, 404 on delete), the tool returns an error result whose message carries the upstream HTTP status and detail — surface that message rather than retry blindly. ## Talking to the user Cube member keys and the schema field names are the wire format — use them in the tool call, never in what you say to the user. When you confirm, ask, or summarize, translate to plain business language: - measure → its display name: **Contribution Margin (amount)**, not `derivatives.contributionMarginAmount`; **Contribution Margin %**, not `derivatives.contributionMarginPercentage`; **Net Sales**, not `sales.netSalesAmount`; **ROAS**, not `derivatives.revenueOnAdSpend`. - store → its name (e.g. **Gottex**), not its id. - dimension → words: **store-wide** (no breakdown), **Brand = Gottex**, **Platform = Shopify** — not `dimensionKey` / `dimensionValue`. - month → **May 2026**, not `2026-05-01`. - monetary amounts → the store's own currency. Don't assume a symbol — stores may be USD, EUR, ILS, etc.; format in whatever currency the store reports in. So to disambiguate a contribution-margin target you ask "Contribution Margin as an amount or as a percentage?" — never by naming `derivatives.contributionMarginAmount` vs `derivatives.contributionMarginPercentage`. Never surface the field names `dimensionKey`, `dimensionValue`, `measureKey`, `goalDate`, or `goalValue` in user-facing text.

bark_manage_goals

Reads a Bark skill (reusable playbook / guideline) by `skillKey`. Use this when the session briefing advertises a skill that looks relevant to the current task — fetching it returns the full markdown body to apply as instructions.

bark_read_skill