get_config_schema
ChatGPTLists the rule columns a shop configuration rule can use, with the ops each column allows, its value kind and known values. Call it to read what a listed rule matches. kind: channels (columns per connected datasource, plus channel groups and categories), customer_segments (composite columns with their "where" and "at" sides), custom_category_clusters (columns per data mart), datasource_rules (actions and columns per connected datasource; pass datasource_id to narrow). Conditions: {"all":[...]} (AND), {"any":[...]} (OR), {"not":{...}} (stored as the negated ops, e.g. not equals becomes not_equals; it cannot wrap between or raw), or a comparison {"field":"<column>","op":"<op>","value":...}. field is a column name, friendly name or classifier from get_config_schema. ops: equals/not_equals (case-sensitive), like/not_like (case-insensitive, % is the wildcard, without % an exact case-insensitive match), contains/not_contains/starts_with/not_starts_with (case-insensitive), in/not_in (list), gt/gte/lt/lte, between (value [min,max]), is_empty/is_not_empty (no value). There is no ends_with and no regex. Each column allows only the ops get_config_schema lists. A list value on a single-value op means any of them, and on not_equals/not_like/not_contains/not_starts_with none of them; on a list-typed column the list is the value itself. Dates are yyyy-MM-dd. {"raw":{...}} is a stored fluid expression this language cannot express.
get_report_schema
ChatGPTThe vocabulary a shop supports for a report: all breakdown dimensions (including the shop's custom categories with their labels), all metric columns available to you, and valid parameter values. Call it when unsure which dimensions or metrics exist, or when the user asks what breakdowns are possible. The given shop_id may belong to any Klar account this connection is granted access to - most connections have exactly one, but some span several; see list_shops for the current set. Reports: revenue_and_profit (query_revenue_and_profit); marketing_flex (query_marketing_flex); attribution_deep_dive (query_attribution_deep_dive); influencer_flex (query_influencer_flex).
list_channels
ChatGPTLists the shop's marketing channels in priority order with their rules per datasource, conditions in the compact rule language (null = every row of that datasource). Higher number wins: a row matching several channels goes to the channel with the highest priority (list_channels lists them in that order). Ties have no defined order. These rules decide which channel a report row is credited to; get_config_schema kind channels explains their columns and ops.
list_custom_categories
ChatGPTLists the shop's custom categories (called groups in the Klar app) with their clusters in order (priority 1 first; display order in the Klar app only, it does not decide which cluster a row matching several gets) and each cluster's rules per data mart in the compact rule language. In the reports a custom category dimension is the category of that name and its values are the cluster names. get_config_schema kind custom_category_clusters explains the columns.
list_customer_segments
ChatGPTLists the shop's customer segments, default ones included (editable: false), with each rule in the compact segment language (null = no rule yet). A rule is {"all":[...]} (customers matching every condition) or {"any":[...]} of conditions on a composite column: "where" is what must be true and "at" narrows it (an order number, a product or a point in time, depending on the composite). get_config_schema kind customer_segments lists each composite's where and at columns.
list_datasource_rules
ChatGPTLists the customization rules of each connected datasource (exclude orders, set financial status, ...): id, name, action and condition in the compact rule language. The actions apply to the datasource's orders, costs or events before any report sees them. get_config_schema kind datasource_rules explains the actions and columns.
list_shops
ChatGPTLists the shops the caller is authorized to query, grouped by Klar account. accounts is an array of {name, shops: [{shop_id, name}]}, one entry per account this connection has access to - most connections have exactly one, but some are granted several. Every report result names the account it came from, so always attribute an answer to the account it belongs to rather than assuming there is only one. shop_id values are opaque tokens: pass them to other tools exactly as returned, never edit or construct one yourself. They may expire - if a query tool reports an invalid shop id, call list_shops again to get a fresh one. An account that could not be resolved right now (for example its access was revoked) appears in skipped instead of accounts; this does not affect the other accounts returned. The top-level shops and account fields mirror the primary account for backward compatibility and will be removed in a future release - prefer accounts. Use an account name to tell the user which account you are reporting on, e.g. after switch_account.
query_attribution_deep_dive
ChatGPTAttribution deep dive for a shop over a date range: how orders (sum_attr_orders), new customers (sum_new_customers), revenue (sum_net_revenue, sum_gross_revenue), cost (sum_cost) and contribution margins attribute to marketing touchpoints under a chosen attribution model (attribution_model: last_touch, first_touch, data_driven, linear, ...) and attribution window. Group by channel_name, channel_group, campaign_name, ad or product dimensions, or date/week/month/quarter. Use query_marketing_flex for campaign spend/ROAS without an attribution model. Use this ONLY for attribution-model questions ('how do channels compare under first-touch?'); use query_marketing_flex for spend/ROAS reporting and query_revenue_and_profit for plain revenue. Attributed values are model-dependent shares, not bookkeeping revenue - different models give different splits over the same orders. Requires the 'attribution' feature on the account's Klar plan. Result rows are keyed by dimension label. Compute relative ranges ('last week', 'the last 30 days') from the current date, preferring to end them yesterday - today's data is incomplete; the range used comes back as date_range, so state it in your answer. Monetary values are in the shop's own currency (no conversion) - don't assume a currency symbol. Present tabular results to the user as markdown tables. Always read warnings before answering: it reports truncation, re-sorting, and why a result is empty. This report has no backend totals row: totals is computed here by summing every matching row (all of them, not just the returned slice), so it stays usable when the result is truncated; rate/ratio metrics cannot be summed and are null in it. When rows_overlap is true the summed totals overcount by the overlap - a warning explains. Dimensions and metrics are validated against the shop's live data and your own access: when unsure of a name, call get_report_schema, or make a best-guess call - the error lists everything available to you, including its custom categories, so you can retry immediately. Calls are rate limited per tool, so prefer one broad query over many narrow ones. A shop_id may belong to any Klar account this connection is granted access to - most connections have exactly one, but some span several. Every result names the account it came from in account.name; always attribute the answer to that account rather than assuming there is only one, especially when comparing results across different calls.
query_influencer_flex
ChatGPTInfluencer/creator performance for a shop over a date range: costs (incl. fixed vs variable), attributed orders and revenue, roas/gross_roas, cac, cpo, sessions, conversion_rate, follower/reach efficiency (cpm, cost_per_follower, reach_share) and purchase-timing buckets - grouped by up to 5 dimensions (influencer_name, campaign_name, platform, type_of_partnership, category, post_type, posting_date, date, discount_code, UTM fields, advertised_sku, custom dimensions, brackets). Use this ONLY for influencer/creator questions; use query_marketing_flex for channel-level marketing and query_revenue_and_profit for plain revenue. Result rows are keyed by dimension label. Compute relative ranges ('last week', 'the last 30 days') from the current date, preferring to end them yesterday - today's data is incomplete; the range used comes back as date_range, so state it in your answer. Monetary values are in the shop's own currency (no conversion) - don't assume a currency symbol. Present tabular results to the user as markdown tables. Always read warnings before answering: it reports truncation, re-sorting, and why a result is empty. When truncated is true the rows are a top-N slice while totals cover the whole selection, so don't sum the rows. When rows_overlap is true, the grouping counts one order under several values, so the rows overlap and their shares do not add to 100%. When totals_are_deduplicated is false, totals is overstated by that same overlap - rank the values but never quote those totals as the period's figures; when it is true, totals is the trustworthy whole-selection figure even if the rows overlap. Dimensions and metrics are validated against the shop's live data and your own access: when unsure of a name, call get_report_schema, or make a best-guess call - the error lists everything available to you, including its custom categories, so you can retry immediately. Calls are rate limited per tool, so prefer one broad query over many narrow ones. A shop_id may belong to any Klar account this connection is granted access to - most connections have exactly one, but some span several. Every result names the account it came from in account.name; always attribute the answer to that account rather than assuming there is only one, especially when comparing results across different calls.
query_marketing_flex
ChatGPTMarketing performance for a shop over a date range: spend (cost), ROAS, CAC (cac_cost), CPO, sessions, clicks, impressions, conversion rate, channel-attributed purchases and revenue, alongside order/revenue/margin metrics - grouped by up to 5 dimensions (channel_name, channel_group, channel_category, campaign, term, content, date, calendar_week, calendar_month, quarter, country, custom categories), with metric filters, sorting, and a bounded row limit. This report has NO server-side dimension or customer-type filters: to narrow to specific values, group by the dimension and read the rows you need; for new-vs-existing customer splits or filtered revenue, use query_revenue_and_profit. Use this ONLY for questions about marketing: ad spend, channel efficiency, ROAS, CAC, CPO, sessions, clicks, impressions, attribution. Its order and revenue figures come from the marketing view and differ slightly from the revenue report - for plain revenue, AOV, order-count or profit questions that are not about marketing performance, use query_revenue_and_profit instead. Result rows are keyed by dimension label. Compute relative ranges ('last week', 'the last 30 days') from the current date, preferring to end them yesterday - today's data is incomplete; the range used comes back as date_range, so state it in your answer. Monetary values are in the shop's own currency (no conversion) - don't assume a currency symbol. Present tabular results to the user as markdown tables. Always read warnings before answering: it reports truncation, re-sorting, and why a result is empty. When truncated is true the rows are a top-N slice while totals cover the whole selection, so don't sum the rows. When rows_overlap is true, the grouping counts one order under several values, so the rows overlap and their shares do not add to 100%. When totals_are_deduplicated is false, totals is overstated by that same overlap - rank the values but never quote those totals as the period's figures; when it is true, totals is the trustworthy whole-selection figure even if the rows overlap. Dimensions and metrics are validated against the shop's live data and your own access: when unsure of a name, call get_report_schema, or make a best-guess call - the error lists everything available to you, including its custom categories, so you can retry immediately. Calls are rate limited per tool, so prefer one broad query over many narrow ones. A shop_id may belong to any Klar account this connection is granted access to - most connections have exactly one, but some span several. Every result names the account it came from in account.name; always attribute the answer to that account rather than assuming there is only one, especially when comparing results across different calls.
query_revenue_and_profit
ChatGPTAggregate a shop's revenue/profit KPIs over a date range, grouped by up to 5 dimensions (customer_type, customer_order_count, channel, product, UTM, calendar, custom categories, ...), with dimension and metric filters, sorting, and a bounded row limit. Result rows are keyed by dimension label. Compute relative ranges ('last week', 'the last 30 days') from the current date, preferring to end them yesterday - today's data is incomplete; the range used comes back as date_range, so state it in your answer. Monetary values are in the shop's own currency (no conversion) - don't assume a currency symbol. Present tabular results to the user as markdown tables. Always read warnings before answering: it reports truncation, re-sorting, and why a result is empty. When truncated is true the rows are a top-N slice while totals cover the whole selection, so don't sum the rows. When rows_overlap is true, the grouping counts one order under several values, so the rows overlap and their shares do not add to 100%. When totals_are_deduplicated is false, totals is overstated by that same overlap - rank the values but never quote those totals as the period's figures; when it is true, totals is the trustworthy whole-selection figure even if the rows overlap. Dimensions and metrics are validated against the shop's live data and your own access: when unsure of a name, call get_report_schema, or make a best-guess call - the error lists everything available to you, including its custom categories, so you can retry immediately. Calls are rate limited per tool, so prefer one broad query over many narrow ones. A shop_id may belong to any Klar account this connection is granted access to - most connections have exactly one, but some span several. Every result names the account it came from in account.name; always attribute the answer to that account rather than assuming there is only one, especially when comparing results across different calls.
switch_account
ChatGPTDisconnects the current Klar account(s) so the user can connect a different one. Call this when the user asks to switch, change, or connect a different Klar account, or to change WHICH set of Klar accounts is connected: reconnecting is the only way to add, drop, or replace accounts in the connected set, since the account picker only appears during the sign-in this tool triggers. This tool does NOT choose the new account, and it does NOT itself produce a sign-in prompt. Sign-in is lazy: the client prompts the user only when a Klar request finds no valid token. So after calling this tool, in the SAME turn: (1) tell the user a sign-in prompt may appear, (2) call list_shops immediately to trigger it and expect that call to fail as unauthorized, which is the expected trigger and not an error to report, (3) keep retrying list_shops, ONE call roughly every 20-30 seconds for up to 2 minutes, until it succeeds - do not stop to ask the user whether they have signed in; reconnection often completes in ~20 seconds without any user action. Do not retry faster: every unauthorized call can open ANOTHER browser sign-in prompt, and stacked prompts make the user sign in twice - if the user reports several prompts, tell them to use only the newest one. When list_shops succeeds, tell the user which account is now connected, using the account name it returns. Call switch_account at most once per switch: never call this tool (or several tools at once) to "retry" a switch that is already in progress.
