Tembi Intelligence

Creates a webshop list, optionally seeded from a selection. Omit `webshops` for an empty list. Returns the new `listId`, which update_leads takes as `addToList`. Idempotent by name: an existing list with the same name comes back with `created:false`, `seeded:0` and its existing id, and is not seeded again; if the name is carried by more than one visible list the call is refused with AMBIGUOUS_NAME. Nothing on this surface deletes a list or a tag, so reuse a name instead of inventing a variant of it. Scoped to the current active market.

create_list

Creates tags by name, idempotently: a name that already exists comes back with created:false and its existing id. Nothing on this surface deletes a tag or a list, so reuse an existing name instead of inventing a variant of it.

create_tags

List or search the queryable values for an analytics dimension Returns the real, queryable values that exist in the analytics data for a dimension, so you can resolve a user's free-text reference to the exact stored value the other tools expect — always prefer this over guessing a value. Values are returned exactly as stored and matched case-insensitively everywhere; stored names vary in style (e.g. 'gls', 'Inpost'). **Two modes, selected by dimension:** - Enumerate — `delivery_provider`, `delivery_method`, `country`, `platform`, `product_category`, `webshop_size`, `growth`, `export_market` (country names of declared export destinations — the values the `export_markets` segment filter takes), `target_country` (ISO codes of cross-border checkout destinations — the values the market-intelligence tools' `target_country` parameter takes), `product_dimension`, `municipality` (local-language names of registered-company municipalities — the values the `municipalities` filter and `stratify_by='municipality'` take): returns the full (or top-N) set of values, ranked by webshop count. - Search — `brand`, `company`, `domain` (high cardinality): a `query` term is **required**; returns ranked name matches. **Each value** carries a `canonical_value` to pass verbatim to other tools, a `label`, and—where meaningful—a `webshop_count` for materiality. Id-keyed dimensions (`product_category`, `product_dimension`, `brand`, `company`, `domain`) also return a `value_id`. Ordinal dimensions (`webshop_size`, `growth`, `product_dimension`) include an `order` (low→high), and `webshop_size` a `score_range`, so comparative phrasing such as 'above-average size' resolves to a contiguous set. Non-selectable placeholders (e.g. 'unknown') are flagged with `is_sentinel: true`. **Scope:** market-specific dimensions (`delivery_provider`, `delivery_method`, `platform`, `product_category`, `webshop_size`, `growth`, `export_market`, `target_country`, `municipality`) default to the caller's home market and can be overridden with a single `country_code`; the `country` dimension lists all available markets. Enumerated values for dated dimensions reflect recent activity (the current market), not all history. **Filtering / example:** for enumerate dimensions, pass `query` to narrow by substring (e.g. 'postn' → 'postnord', 'postnl'). To answer a question about 'Royal Mail', call with dimension='delivery_provider' to find 'royal_mail', then pass that `canonical_value` to the market-intelligence tools. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "dimension": "DimensionName", "mode": "Mode", "country_codes": [ "string" ], "total_values": 1, "returned": 1, "values": [ { "canonical_value": "Canonical Value", "label": "Label", "is_sentinel": true } ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "dimension": { "type": "string", "enum": [ "delivery_provider", "delivery_method", "country", "platform", "product_category", "webshop_size", "growth", "export_market", "target_country", "product_dimension", "municipality", "brand", "company", "domain" ], "title": "DimensionName", "description": "Dimensions whose queryable values can be discovered." }, "mode": { "type": "string", "enum": [ "enumerate", "search" ], "title": "Mode", "description": "How values were resolved: full enumeration vs name search." }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Market scope applied (empty = not scoped / all markets)." }, "total_values": { "type": "integer", "title": "Total Values", "description": "Total distinct values/matches for this dimension, scope, and filter." }, "returned": { "type": "integer", "title": "Returned", "description": "Number of values included in this response." }, "values": { "items": { "properties": { "canonical_value": { "type": "string", "title": "Canonical Value", "description": "The value to pass verbatim to other tools, exactly as stored. Stored names vary in style (e.g. 'gls', 'Inpost'); every tool matches them case-insensitively. For id-keyed dimensions (category/brand) this is the canonical name." }, "label": { "type": "string", "title": "Label", "description": "Human-readable label for matching against user phrasing." }, "value_id": { "title": "Value Id", "description": "Underlying key for id-keyed dimensions (e.g. category_id, brand_id, domain_id). Use when a downstream tool filters on the id rather than the name." }, "webshop_count": { "title": "Webshop Count", "description": "Distinct webshops with this value \u2014 a measure of materiality. Null when not applicable (e.g. search results)." }, "order": { "title": "Order", "description": "1-based rank for ordinal dimensions (low \u2192 high), e.g. small=1 \u2026 very_large=4. Null for non-ordinal dimensions." }, "score_range": { "title": "Score Range", "description": "For 'webshop_size': the [min, max] of the underlying 0\u2013100 size score this bucket covers (e.g. 'large' \u2192 [50, 74]). Null otherwise." }, "is_sentinel": { "type": "boolean", "title": "Is Sentinel", "description": "True when the value is a non-selectable placeholder (e.g. 'unknown', 'collect_yourself') rather than a real carrier/option.", "default": false } }, "type": "object", "required": [ "canonical_value", "label" ], "title": "QueryableValue", "description": "A single queryable value for a dimension." }, "type": "array", "title": "Values" }, "summary_for_llm": { "type": "string", "title": "Summary For Llm", "description": "Pre-rendered narrative listing the most material values for direct LLM use." } }, "type": "object", "required": [ "dimension", "mode", "total_values", "returned", "values", "summary_for_llm" ], "title": "QueryableValuesResponse", "description": "Response from the *get_queryable_values* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_queryable_values

Finds the webshops matching a selection and returns them with lead status, owner and tags as names, not ids. Also the resolver: pass `webshops.domains` and every input that matched no webshop you can see comes back in `unmatched`. A webshop nobody has set a status on reads as the customer’s default status (usually `Open`). Paging is offset-based over live data: when you write while paging, stay on `page: 1` and exclude what you already changed — for example tag each batch and pass that tag in `webshops.excludeTags` — instead of advancing `page`. Omit `webshops` to match everything you can see. Scoped to the current active market.

find_webshops

Fetch a report's rendered HTML + metadata (to read or to clone) Returns a single report's rendered HTML plus its metadata — to preview/read it (e.g. verify what you just pushed) or to clone it locally for editing. Get ``report_id`` from ``list_reports`` or from a prior ``push_report``'s ``id``. The HTML is the figure-injected render the customer sees — numbers are baked in, not fig:token placeholders. ``figures`` is included for provenance only and is NOT in the shape ``push_report`` expects — rebuild bindings from your sources rather than feeding it back. To re-publish an edited clone, re-introduce fig:token placeholders (token wrapped in double curly braces) and bind them in ``figures`` via ``push_report`` (pushing baked-in numbers trips the inline-number guard), and re-stamp the edited HTML with the tembi-report skill. Pass ``release_id`` to fetch a specific version: a prior published version, or a **draft** you just pushed (use the ``release_id`` returned by ``push_report``). Omit ``release_id`` for the current published version — a bare fetch never returns an unpublished draft, and returns **empty** for a report that has never been published (e.g. one you just created), so pass the ``release_id`` to see that draft. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "id": "Id", "title": "Title", "markets": [ "string" ], "required_modules": [ "string" ], "html": "Html", "figures": {}, "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "status": { "title": "Status" }, "markets": { "items": { "type": "string" }, "type": "array", "title": "Markets", "default": [] }, "required_modules": { "items": { "type": "string" }, "type": "array", "title": "Required Modules", "default": [] }, "ai_summary": { "title": "Ai Summary" }, "data_as_of": { "title": "Data As Of" }, "generated_on": { "title": "Generated On" }, "html": { "type": "string", "title": "Html", "description": "Rendered report HTML (figures injected, numbers baked in).", "default": "" }, "figures": { "additionalProperties": true, "type": "object", "title": "Figures", "description": "token -> figure binding used at render (provenance only)." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "id", "title", "summary_for_llm" ], "title": "ReportContentResponse" } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_report_content

Return the authenticated Tembi user's identity, permissions, and market scope Resolves the caller's Auth0 JWT to their Tembi user record and returns the identity, permissions, and market/provider scope needed to parameterise the other tools. **Market scope:** 'country_code' is the user's default/locale market, applied only when a tool call omits one — it is not a restriction. 'market_intelligence_markets' lists the markets the user may actually query. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "user_id": "User Id", "is_admin": true, "custom_only": true, "modules": [ "string" ], "products_access": [ "string" ], "market_intelligence_markets": [ "string" ], "timestamp": "2023-01-01T00:00:00Z" } ``` **Output Schema:** ```json { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "Tembi user ID (Auth0 subject)." }, "email": { "title": "Email", "description": "User's email address." }, "user_name": { "title": "User Name", "description": "Display name as stored in Tembi." }, "language": { "title": "Language", "description": "Preferred language code." }, "country_code": { "title": "Country Code", "description": "The user's default/locale market (ISO 3166-1 alpha-2, e.g. 'DK'). A convenience default applied when a tool call omits a market \u2014 not a restriction. The markets the user may query are in 'market_intelligence_markets'." }, "currency": { "title": "Currency", "description": "User's preferred currency code (e.g. 'DKK')." }, "providers": { "title": "Providers", "description": "Comma-separated delivery provider name(s) (e.g. 'gls' or 'gls,Inpost')." }, "delivery_providers": { "title": "Delivery Providers", "description": "Delivery provider names as a list (e.g. ['gls'])." }, "is_admin": { "type": "boolean", "title": "Is Admin", "description": "Whether the user has admin privileges.", "default": false }, "custom_only": { "type": "boolean", "title": "Custom Only", "description": "When true, the user only has access to their own customer's data.", "default": false }, "modules": { "items": { "type": "string" }, "type": "array", "title": "Modules", "description": "Permission modules the user has access to." }, "products_access": { "items": { "type": "string" }, "type": "array", "title": "Products Access", "description": "Products the user has been granted access to." }, "market_intelligence_markets": { "items": { "type": "string" }, "type": "array", "title": "Market Intelligence Markets", "description": "Markets (ISO country codes) this user may run the market-intelligence tools for. Empty = no explicit restriction (e.g. internal users may query any market)." }, "access_markets": { "title": "Access Markets", "description": "Markets (ISO country codes) this user has access to across Tembi products. None / empty = no explicit restriction (e.g. internal users)." }, "countries": { "title": "Countries", "description": "Countries/markets the customer organisation has access to." }, "domain_business_model": { "title": "Domain Business Model", "description": "Business model filter(s) active for this user (e.g. ['b2c'])." }, "customer": { "description": "Customer/organisation metadata (when requested)." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Server-side UTC timestamp of the invocation." } }, "type": "object", "required": [ "user_id", "timestamp" ], "title": "UserContextResponse", "description": "Response from the *get_user_context* tool.\n\nScoped to what an agent needs to parameterise the other tools \u2014 identity,\npermissions, and market/provider scope." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_user_context

List the reports visible to the calling user Lists every report visible to the authenticated user (own customer scope). Start here to find a report ``id`` before fetching it with ``get_report_content`` or revising it via ``push_report``'s ``report_id``. Each entry: ``id``; ``title``; ``status`` (``draft`` = unpublished, or ``published`` = signed off and customer-visible); ``markets`` (ISO country codes, e.g. ``["DK","SE"]``); ``data_as_of`` (when the underlying figures were sourced); ``generated_on`` (when this version was rendered/pushed). One row per report, showing its latest version. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "reports": [ { "id": "Id", "title": "Title", "markets": [ "string" ] } ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "reports": { "items": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "status": { "title": "Status" }, "markets": { "items": { "type": "string" }, "type": "array", "title": "Markets", "default": [] }, "data_as_of": { "title": "Data As Of" }, "generated_on": { "title": "Generated On" } }, "type": "object", "required": [ "id", "title" ], "title": "ReportSummary" }, "type": "array", "title": "Reports", "default": [] }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "summary_for_llm" ], "title": "ListReportsResponse" } ```

list_reports

The vocabulary behind a selection: owners, tags, lists or statuses. Names and ids together.

list_lead_options

Create or revise an HTML report (draft) in Market Intelligence Creates a new HTML report in the Market Intelligence → Reports section. Always lands as a **draft** — a human publisher signs it off before any customer sees it. There is no publish-from-MCP path. Visibility is locked to **your own customer account** — no other customer, market, or module can see it until a human editor widens visibility in the UI. ``data_as_of`` is optional — omit to default to the current UTC time. By default each push creates a new report keyed by a server-assigned id. To revise an existing report instead, pass its ``report_id`` — the push lands as a new draft version (release) on that report rather than a new one. Always a draft; a publisher still signs off the new version. **Provenance is mandatory:** every number in the HTML must be a fig:token placeholder (token wrapped in double curly braces) bound in ``figures`` to a value sourced from the Market Intelligence tools. HTML with bare numbers in prose is rejected unless ``allow_inline_numbers`` is set. **Restyle stamp required:** the HTML must carry a valid ``tembi-restyle`` stamp (an HTML meta tag the tembi-report skill injects) or the push is rejected with 422. The check is presence-only — the server does not recompute the hash. Run the skill on the HTML **before the first push, not only after edits** — freshly authored HTML is unstamped and will be rejected. Stamp after your last content edit so your own local validate stays meaningful. A fetched clone keeps a stamp that still passes, so the bare-number guard is the only check on baked-in literals. **Confidentiality:** reports are company-scoped — never public/global. **Too large for one call?** If the HTML would not fit in a single response, send it in several calls instead of shortening the report. First call: the opening of the document (doctype, head, style, and the first section) with ``is_final=false`` — the response returns an ``chunk_upload_id``. Each later call: the next section, with that ``chunk_upload_id``, ``seq`` set to the ``next_seq`` you were given, and ``is_final=false``. Last call: the closing section with ``is_final=true`` — the server assembles the document and creates the draft. Chunks are joined with **no separator**: concatenating the html strings you send, in order, must reproduce the stamped file byte-for-byte — end each non-final chunk with its trailing newline (\n). Cut at section boundaries, never inside a tag or a ``<script>``; bind the fig:token placeholder values in the ``figures`` of whichever call uses them. ``title``, ``report_id``, ``ai_summary``, ``data_as_of`` and ``allow_inline_numbers`` are read from the first call and ignored afterwards. Finish and **stamp the whole report first**, then split the stamped file — chunking is only a transfer mechanism, not a way to author in pieces. The restyle stamp travels in whichever section carries the ``<head>``, and the assembled document is checked for it exactly as a single-call push would be. Sections are not validated for style individually. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "id": "Id", "release_id": "Release Id", "content_url": "Content Url", "inline_number_warnings": [ "string" ], "chunk_upload_id": "Chunk Upload Id", "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "id": { "type": "string", "title": "Id", "default": "" }, "release_id": { "type": "string", "title": "Release Id", "default": "" }, "content_url": { "type": "string", "title": "Content Url", "default": "" }, "inline_number_warnings": { "items": { "type": "string" }, "type": "array", "title": "Inline Number Warnings", "default": [] }, "chunk_upload_id": { "type": "string", "title": "Chunk Upload Id", "description": "Set on a non-final chunk; pass it back on the next call.", "default": "" }, "next_seq": { "title": "Next Seq", "description": "The seq the next call must use." }, "chars_total": { "title": "Chars Total", "description": "Characters of HTML accumulated so far." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "summary_for_llm" ], "title": "PushReportResponse" } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

push_report

Renames one tag. Assignments are untouched. Renaming a tag to the name it already has succeeds and changes nothing. Refused with TAG_NAME_TAKEN if another tag already has the new name.

rename_tag