Convious

Use this when the user wants to understand how products are grouped, find a category UUID (e.g. to pass to `browse_products`), or explore the category tree. Results are paged; pass `cursor` to continue. Use `root=true` to start from the top of the tree, then drill in with `parent_category`. Parameters: - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. - `cursor` (optional) — `next` or `previous` URL from a prior response; all other filters are ignored when set. - `parent_category` (optional) — restrict to children of this category UUID. - `root` (optional) — `true` for top-level only; `false` for non-root; omit for all. - `include` (optional) — comma-separated related entities: name, parent_category, images, text.

browse_categories

Use this when the user wants to see what products exist on their account — to find a product ID, check what tickets are on sale, or explore the catalog before doing something with a specific product. Results are paged; pass `cursor` from a previous response to continue. Narrow by category or enabled status to reduce noise. Parameters: - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. - `cursor` (optional) — `next` or `previous` URL from a prior response; all other filters are ignored when set. - `category_id` (optional) — restrict to products in this category. - `enabled` (optional, default `true`) — `false` for disabled-only; omit for both. - `has_external_id` (optional) — filter by whether the product is linked to an external system. - `current_only` (optional, default `false`) — keep only products live today (enabled and inside their validity window). Trims mostly-stale catalogs; filters the current page only, so a page may return zero rows yet still have a `next` cursor. - `include` (optional) — comma-separated related entities: name, account, text, categories, resources, images, external_ids, barcode, taxes, scan_options.

browse_products

Use this to inspect the analytics schema before writing SQL. Call once per session, after reading `get_analytics_skill`; reuse the skill if already loaded for the current connection, account, and permissions. The SQL DDL lists every fact and aggregate table (orders, items, memberships, payments, sales-vs-budget, weather joins) with their columns, measures, and default filters. Retain the schema in context and reuse it for subsequent queries without calling this tool again. Refresh only when the connection, account, or permissions change, a schema update is reported or requested, or the cached schema is no longer available in context. Parameters: - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. Returns `{"account_slug": "...", "view": "...", "schema_ddl": "..."}`.

get_analytics_schema

**Call once per session**, before the first `get_analytics_schema` or `query_analytics` call. It returns the canonical `data-analyst` skill: the Convious data team's playbook on which fact table owns which metric, the demo-account filter, join keys, default filters, how to read the schema, and worked SQL patterns. Read it fully, retain it in context, and apply it to subsequent data questions without calling this tool again. Refresh only when the connection, account, or permissions change, an update is reported or requested, or the cached guidance is no longer available in context. Parameters: - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. Returns `{"account_slug": "...", "skill_name": "...", "skill_markdown": "..."}`.

get_analytics_skill

**Call this FIRST, before `search`, whenever you intend to use structured `filters`.** Returns the live function-calling schema for `search` on this account — the exact per-type filter fields and enum values (order/membership statuses, group-booking date modes, the account's group-booking location UUIDs, etc.), scoped to the result types you can access. The schema is generated from the same serializers `search` validates against, so what it advertises is exactly what `search` accepts. The per-account filters (notably group-booking locations and the available status enums) are dynamic, which is why you read them here rather than guessing. Call once per session per account and cache the result; you only need it when you want to pass `filters` (a plain free-text `q` search needs no schema). Parameters: - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. Returns `{"name": "...", "description": "...", "input_schema": {...}, "types": {...}}`. `input_schema` is the JSON Schema for `search`'s arguments; `types` maps each result type to the permission it requires.

get_search_schema

Liveness probe for the gateway. No parameters. Any authenticated caller can use it.

health

Use this when the user wants to inspect a specific product — its name, pricing type, category membership, barcode settings, validity window, or any other configuration detail. Takes the product UUID, or the numeric product ID that analytics results use; use `browse_products` first if you only have a name. Parameters: - `product_id` (required) — product UUID, or a numeric product ID (e.g. `27686`) as returned by `query_analytics`. Numeric IDs are resolved by matching the analytics product name against the account's catalog, so they only work for products with sales history — prefer the UUID when you have it. An ambiguous or unresolvable numeric ID returns an error listing candidate products to pick from, and an id that is neither a UUID nor digits is rejected outright — use `browse_products` or `search` to find a product by name. - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. - `include` (optional) — comma-separated related entities to expand: name, account, text, categories, resources, images, external_ids, barcode, taxes, scan_options.

look_up_product

Use this when the user wants to see what prices the RTP/NYOP engine would produce under a proposed configuration, without committing the change. Useful for "what would happen if I raised the floor to €18?" or showing projected daily prices before calling `update_pricing`. Window: future dates only, max 60 days. Parameters: - `article_uuid` (required) — product UUID. - `date_from` (required) — ISO8601 date (must not be in the past). - `date_to` (required) — ISO8601 date; window ≤ 60 days. - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `products_list_uuid` (optional but effectively REQUIRED) — category (products-list) context UUID. Without it the engine returns the no-op `identity` model with an empty `prices` list, so always pass the UUID of a category the article belongs to (see `browse_categories`). - `settings_payload` (optional) — proposed settings to evaluate instead of the persisted ones, shaped `{"productData": {"priceSettings": {originalPrice, avgTargetPrice, minAcceptedPrice, gatePrice, stepSize, ...}, "override": {...}}, "accountSettings": {...}}`. Omit to preview the current live settings. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. Returns `{"modelId": ..., "defaultPrice": ..., "pricingStrategy": ..., "prices": [...], "validationMessages": [...]}`.

preview_pricing

Use this when the user asks a data question about their venue — revenue, GMV, refunds, top products, memberships, payment failures, budget vs. actuals, or anything else in the analytics dataset. Load `get_analytics_skill` (the playbook), then `get_analytics_schema` (the column list), once per session. If both are already available in context for the current connection, account, and permissions, query directly without calling them again; apply the cached skill and schema to every query. Refresh the affected guidance only when the connection, account, or permissions change, an update is reported or requested, or cached context is lost. Follow the skill's demo filter, fact-table-per-metric, and default payment-flow filters. SQL rules: `SELECT` or `WITH` only (no DDL/DML); must filter by `account_slug` somewhere. Parameters: - `sql` — the SQL to run. Required for a new query; omit it when paging with `cursor`. - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. - `cursor` (optional) — pass the `next_cursor` from a previous response to fetch the next page of the same result set. When set, `sql` is ignored. Returns `{"account_slug": "...", "sql": "...", "columns": [...], "rows": [...], "row_count": N, "total_row_count": M, "next_cursor": "..."|null}`. Up to 1000 rows per call; if `next_cursor` is non-null, call again with that `cursor` to get the next page. `total_row_count` is the whole result set; `row_count` is this page. Cursors stay valid ~24h.

query_analytics

Use this when the user wants to see how a product is currently priced, or before calling `update_pricing` — the response includes the `version` token required for a safe optimistic-lock write. Returns the original price, RTP/NYOP target and floor, gate price, step size, and the engine's computed defaults. Parameters: - `intent` (required) — use the exact fixed purpose from the input schema's enum. Never include personal data, identifiers, credentials, or user quotes. The server records a fixed purpose. - `product_ids` (optional) — list of product UUIDs, or numeric product IDs (e.g. `27686`) as returned by `query_analytics`. Numeric IDs are resolved to UUIDs first via analytics name-matching, so they only work for products with sales history; any that can't be resolved come back under `unresolved_product_ids` instead of being dropped. Omit to read every currently-live product on the account (bulk mode). - `account` (optional) — inferred from your session; pass explicitly when you have access to more than one. Returns `{"priceSettings": [{originalPrice, avgTargetPrice, minAcceptedPrice, gatePrice, stepSize, pricingType, version, lastModifiedAt, lastModifiedBy, ...}]}`, plus `unresolved_product_ids` when a supplied numeric ID could not be resolved. Bulk mode pages through the whole account catalog and adds `resolved_product_count` (and `partial: true` only if an internal page cap is hit).

read_price_settings