Tools reference

By
The Quable Team

At the time of writing, the Quable MCP server exposes 35 tools, 2 prompts and a few resources. Your AI assistant reads the description of each tool and chooses which one to call: you normally don't call tools yourself, but knowing them helps you write precise requests and understand what the assistant does.


Overview

Domain Tools
Session and server test_credentials, get_user_info, server_time, get_pim_url, skill_word_count
Catalog structure list_locales, list_document_types, list_completenesses, list_attributes, search_classification, search_attribute-sets, update_attribute-set
Products get_product, search_products, create_product, update_product
Variants get_variant, search_variants, create_variant, update_variant
Assets get_asset, get_asset_file, search_asset, update_asset
Select options list_predefined-values, update_predefined-value
Links add_asset_to_product, remove_asset_from_product, add_link, remove_link
Exports list_export_profiles, get_export_options, trigger_export, get_export_status, get_export_file

Session and server

test_credentials

Checks that the instance name and token sent in the headers are valid. Use it to test a new connection.

Parameters: none.
Returns: {"status": "valid credential"}, or an authentication error.

get_user_info

Returns the profile of the token's user. Call it at the start of a session so the assistant knows which locale to use by default.

Parameters: none.
Returns: localesAvailable (active data locales), localeDefault, localeI18nDefault (interface language), permissions (permissionFeatures, permissionField, permissionCatalog, damPermissionCatalog), admin, active, timezone, username, email, firstName, lastName, dateLogged.

server_time

Returns the current UTC time of the server. Does not call your instance and needs no authentication.

Returns: {"utc_now": "2026-11-19T10:42:00+00:00"}

get_pim_url

Builds a clickable link to a product or asset page in the Quable PIM interface.

Parameter Type Required Description
entity_type product | asset yes Kind of page.
legacy_id string or number yes The numeric legacy_id found in tool results. Not the product or asset code.

Returns: {"url": "https://your-instance.quable.com/#classification/product-new/12345/edit"}. A missing or non-numeric legacy_id returns an error: the tool never guesses a link.

skill_word_count

Counts the visible words of a text. HTML tags, comments and scripts are removed and entities decoded first, so a rich-text value counts only what a reader sees. Useful to check the length of a generated description. Needs no authentication.

Parameter Type Required Description
text string yes Text or HTML to count.

Returns: {"word_count": 128}


Catalog structure

These tools tell the assistant how your PIM is configured. Most of them are called by the pim-bootstrap prompt.

list_locales

Lists the active data locales of the instance.

Parameters: none.
Returns: a list of {id, label, fallback?}. id is the code to use in other tools (e.g. fr_FR). fallback is the locale used when a value is missing.

list_document_types

Lists document types (product types) and link types.

Parameter Type Required Description
locale string no Language of the name field (e.g. fr-FR). Default en-US.

Returns: {document_types: [{id, name, object_type, has_variant}], link_types: [{id, name}]}. has_variant tells whether the type accepts variants. Link type ids are used by add_link and remove_link.

list_completenesses

Lists the completeness rules configured on the instance. It does not return scores: read them on a product with get_product (view completeness) or filter with search_products.

Parameter Type Required Description
locale string no Language of the name field. Default en-US.

Returns: a list of {id, name, document_type, required_attributes, required_links: [{id, minimum}]}.

list_attributes

Finds attribute codes, for example from an approximate name.

Parameter Type Required Description
search string no Case-insensitive filter on code and name.
document_type_id string no Restrict to one document type. Without it, attributes of all types are returned.
locale string no Language of the name field. Default en-US.

Returns: a list of {id, name, type, documentTypeId, group}. Types simple_select and multi_select are select attributes (also called combo and multicombo): use list_predefined-values to get their options.

search_classification

Resolves classification (category) ids from a name or id.

Parameter Type Required Description
query string no Matched on id and labels in every locale, ignoring case, accents, - and _.
classification_id string no One id, or several comma-separated. Unknown ids are returned in missing_ids.
catalog_id string no Restrict to one catalog, e.g. PIM for product classifications. Other catalogs are channels or DAM folders.
locale string no Language of label and path.
limit integer no Page size, default 30, max 50.
offset integer no Start position, default 0.

Returns: {items: [{id, label, path, parent_id, catalog_id, active, legacy_id}], total, returned, offset, missing_ids}. Labels are not unique: the same name can exist under several parents, so check path.

search_attribute-sets

Lists attribute sets, i.e. which attributes apply to the products of a document type and count for completeness.

Parameter Type Required Description
id string no Filter on the set id (case-insensitive).
search string no Partial match on id and name.
document_type_id string no Restrict to one document type.
locale string no Language of the name field.
limit integer no Max rows, default 50.

Returns: {items: [{id, code, name, document_type_id, attributes}], total, returned}. attributes lists the attribute codes of the set.

update_attribute-set

Creates or updates an attribute set. Idempotent by code.

Parameter Type Required Description
code string yes Attribute set id.
labels JSON string on create Locale → label, e.g. {"en-US": "Jacket attributes", "fr-FR": "Attributs veste"}. Merged with existing labels on update.
document_type_id string on create Document type of the set. Cannot be changed afterwards.
attributes JSON string no Array of attribute codes, e.g. ["attr_color", "attr_size"]. Replaces the composition. Omit it to keep the current one. An empty array is rejected.

Products

get_product

Reads one product (document) by its exact id. To read several known products, the assistant calls it once per id rather than searching.

Parameter Type Required Description
product_id string yes Exact document id.
views array no Sections to return: basic, attributes, classifications, tags, completeness, links, assets, variants, workflow. basic is always included.
output_locales string no Comma-separated data locales to keep, e.g. fr_FR,en_US. Default: all active locales.
attributes string no Comma-separated attribute codes to keep. Requires attributes in views.
locale string no Interface locale for translated labels.

Returns: the basic view (id, documentType, active, attributeSet, dateCreated, dateModified, mainAssetThumbnailUrl, legacy_id) plus the requested sections, and a _meta block:

{
  "id": "REF-001",
  "attributes": { "product_name": { "fr_FR": "Veste", "en_GB": "Jacket" } },
  "completenesses": { "completeness_e_commerce": { "fr_FR": 85, "en_GB": 100 } },
  "_meta": {
    "views": { "used": ["basic", "attributes", "completeness"], "omitted": ["links", "assets", "..."] },
    "output_locales": { "used": ["fr_FR", "en_GB"], "omitted": [] }
  }
}

Section keys in the result: completeness → completenesses, links → documentLinks, assets → assetLinks, workflow → workflows. In _meta, omitted means not requested, not does not exist.

search_products

Searches and filters products when their ids are not known.

Parameter Type Description
search string or array A string runs a full-text search. A list of up to 8 filename tokens (e.g. ["tshirt_red", "4568"]) runs orphan matching: it returns scored matches (with matched_on, score, legacy_id) and no_match instead of items.
include_variants boolean With a token list, also match variant codes.
document_type_id string Filter on document type.
classification_id string Filter on one classification.
classification_ids string Several classifications, as ["id1","id2"] or id1,id2.
completeness_id string Completeness rule to filter on. Requires completeness_locale and completeness_value.
completeness_locale string Locale the completeness filter is evaluated in, e.g. fr_FR.
completeness_value string Score, e.g. 100. Exact match unless completeness_operator is set.
completeness_operator gt | gte | lt | lte Turns completeness_value into a threshold.
attribute_filters JSON object or string See Attribute filters.
attribute_filter_string string Raw REST API query string. Takes precedence over attribute_filters.
sort_by dateCreated | dateModified | id | documentType Sort on a document field.
sort_by_completeness string Sort on a completeness rule's score, in the locale given by locale.
sort_by_attribute string Sort on an attribute value.
order_direction asc | desc Default desc.
limit / offset integer Pagination, default 20 / 0. limit is capped at 50.
locale string Locale in which filters and sorts are evaluated when the field has no locale of its own.
views, output_locales, attributes   Same as get_product, applied to each item.

Set at most one of sort_by, sort_by_completeness and sort_by_attribute.

Returns: {items, total, limit, offset, _meta}.

Example: the 10 products with the best Spanish e-commerce score, without filtering:

{
  "sort_by_completeness": "completeness_e_commerce",
  "order_direction": "desc",
  "locale": "es_ES",
  "limit": 10
}

Attribute filters

Used by search_products, search_asset and search_variants:

Filter Meaning
{"color": "red"} Exact value
{"color": ""} Value is missing
{"color": ["red", "blue"]} Any of the values
{"date_expiration": {"before": "2026-08-31"}} Before a date (also "now")
{"date_launch": {"after": "now"}} After a date
{"name": {"contains": "jacket"}} Contains a text, search_variants only

create_product

Creates a product with its classification, attribute set and values.

Parameter Type Required Description
document_code string yes New unique code. Refused if already used.
document_type_id string yes Document type, from list_document_types.
document_name string yes Product name, written to the <document_type_id>_name attribute.
classification string yes Classification id, from search_classification.
attribute_set string yes Attribute set of that type, from search_attribute-sets.
attributes JSON string no Attribute values, same formats as update_product. Each attribute must belong to the type and to the attribute set.
locale string no Locale of document_name. Default: the user's locale.

Invalid input is refused before anything is created.
Returns: {status, message, document, missing_required, not_persisted}. missing_required lists required attributes still empty. not_persisted lists values the PIM did not store: retry them with update_product.

update_product

Partially updates a product: only the keys you send change. If the PIM does not persist a value (for example a character limit is exceeded), the tool returns an error instead of reporting success.

Parameter Type Required Description
document_id string yes Exact document id.
attributes JSON string yes Payload, see below.
locale string no Interface locale of the returned document. Does not choose which locale is written.

Top-level keys of the payload:

Key Description
attributes Attribute code → value, see formats.
active Boolean.
classification {"id": "classification-id"}, a single classification.
attributeSet {"id": "attribute-set-id"}
id Optional. Omit it or set it to document_id. A different value renames the product code.

The document type cannot be changed after creation.

{
  "attributes": {
    "product_description": { "fr_FR": "Nouvelle description", "en_GB": "New description" },
    "product_color": [{ "id": "red" }],
    "product_weight": 1.2
  }
}

Returns: {status, message, document}, where document has the same shape as get_product.

Attribute value formats

Attribute type Format Example
Text, translatable (textfield, textarea, htmlEditor) Locale → value {"fr_FR": "Rouge", "en_GB": "Red"}
Text, not translatable String "ABC-123"
Number Number 42.5
Checkbox Boolean or string true, "1", "false"
Date / time String "2026-11-19 00:00:00" / "14:30"
Single select (combo) Array of exactly one option code [{"id": "red"}]
Multi select (multicombo) Array of option codes [{"id": "red"}, {"id": "blue"}]
Raw (brut) JSON string "[{\"key\": \"value\"}]"

To clear a value, send null or an empty string.


Variants

get_variant

Reads one variant (SKU) with every attribute of the variant type.

Parameter Type Required Description
variant_code string yes Variant code. Case and trailing spaces are ignored.
locale string no Keep only this locale in translated values. Default: all locales.

Returns: {found, variant_code, legacy_id, product_code, name, active, sequence, date_created, date_modified, attributes, missing_required, assets: [{asset_id, link_type, sequence}]}. attributes lists every attribute allowed by the parent's attribute set, null when never set. An unknown code returns found: false instead of an error.

search_variants

Lists the variants of a product, or searches variants across the catalog.

Parameter Type Description
product_code string Parent product. Its variants are returned in sequence order. Omitted: all variants, by code.
attribute_filters JSON object or string See Attribute filters. A select matches its option code or label. Unknown attributes are refused.
fields array or string Attribute codes to return.
locale string Locale in which text filters are evaluated. Default: the user's locale.
limit / offset integer Default 20 / 0, limit max 50.

Returns: {items: [{variant_code, legacy_id, product_code, name, active, sequence, attributes}], total, limit, offset}.

create_variant

Creates a variant under an existing product. The product's type must accept variants (has_variant in list_document_types).

Parameter Type Required Description
product_code string yes Parent product code.
variant_code string yes New unique code, max 150 characters.
attributes JSON string no Variant attributes, same formats as update_product, e.g. {"quable_sku_name": {"fr_FR": "Veste M"}, "sku_ean": 3700000000001}.

A variant follows its parent's attribute set: values of attributes outside that set are refused.
Returns: {status, message, variant: {id, legacy_id, product_code, name, sequence, active}, missing_required, not_persisted}.

update_variant

Changes attribute values of a variant. The code, parent and status are never changed.

Parameter Type Required Description
variant_code string yes Variant code.
attributes JSON object or string yes Attribute code → value.
locale string no Lets a translatable text be sent as a plain string for this locale.
  • A select is replaced by the full list sent, never merged. [] or null clears it.
  • A translatable text only changes the locales sent.
  • Values the PIM would drop or garble are refused before writing, and the result is read back.

Returns: {status: "updated" | "partially_updated", message, variant_code, product_code, attributes, not_persisted, missing_required}.


Assets

get_asset

Reads an asset's metadata: name, original filename, size, thumbnail and preview URLs, attributes, classifications and links. No file content.

Parameter Type Required Description
asset_id string yes Asset code.
locale string no Interface locale.

get_asset_file

Downloads an asset's content so the assistant can read it.

Parameter Type Required Description
asset_id string yes Asset code.
rendition thumbnail | original no Default: original for PDF, CSV and spreadsheets, thumbnail otherwise.
mode auto | text | document no PDF handling, default auto.
locale string no Interface locale.

What you get, by file type:

Type Result
Image A native image block: the model sees the picture. The thumbnail is enough for recognition and tagging.
PDF, mode: auto or text The text layer of the PDF, up to 75,000 characters (truncated: true beyond). auto returns an error for a scanned PDF with no text layer.
PDF, mode: document The PDF itself as a document block. Keeps the layout (tables, columns) and works for scans, but costs more context.
CSV, XLS, XLSX, XLSB, ODS {mode: "table", format, sheets: [{name, rows, total_rows, total_columns}]}. Formula cells hold their last computed value; dates are ISO 8601.

Other file types are rejected: use get_asset for their metadata and URLs. See size limits.

search_asset

Searches DAM assets.

Parameter Type Description
query string Full-text search.
classification string DAM folder (classification) id, or several comma-separated.
tags string Tag id, or several comma-separated.
original_filename string Filter on the uploaded filename.
linked_to_document object Assets linked to a product: {"link_type": "article_images", "document_code": "SKU-1"}. Both keys are required.
orphans_only boolean Only assets linked to no product or variant.
created_after / created_before string Creation date range.
modified_after / modified_before string Modification date range.
attribute_filters JSON object or string See Attribute filters, e.g. {"date_expiration": {"before": "now"}} for expired assets.
attribute_filter_string string Raw REST API query string. Takes precedence over attribute_filters.
sort_by dateCreated | dateModified | id | name Sort field.
sort_order asc | desc Default desc.
limit / offset integer Pagination, default 20 / 0.
locale string Interface locale.

Returns: a compact paginated list. Each item has a legacy_id for get_pim_url.

update_asset

Partially updates an asset's attributes.

Parameter Type Required Description
asset_code string yes Asset code, e.g. 800488-1_I_P.jpg.
attributes JSON string yes Attribute code → value, same formats as products.
locale string no Interface locale.

For select attributes on assets, prefer the shape returned by get_asset: an array of {id, labels}, where id is the option code.

{
  "qua_asset_non_translatable_text": "Label",
  "qua_asset_textfield": { "fr_FR": "texte", "en_GB": null },
  "qua_asset_multicombo": [{ "id": "season_winter", "labels": { "en_GB": "Winter", "fr_FR": "Hiver" } }]
}

Returns: {status, message, asset}.


Select options

list_predefined-values

Lists the options of a select attribute (types simple_select / multi_select). Use it to find the code behind a label before filtering or updating, or to check that a code is free.

Parameter Type Required Description
attribute_id string yes Select attribute code, from list_attributes.
search string no Case-insensitive filter on code or label.
locale string no Locale used to fill label. All translations are always in labels.

Returns: a list of {code, attribute_id, labels, label, description, legacy_id}.

update_predefined-value

Creates or updates an option of a select attribute. Idempotent: creates the option when the code is new, updates its labels otherwise.

Parameter Type Required Description
attribute_id string yes Select attribute code.
code string yes Option code.
labels JSON string yes Locale → label, e.g. {"en_GB": "Red tag", "fr_FR": "Tag rouge"}. Merged with existing labels.
description JSON string no Locale → description.

Returns: {status, message, predefined_value}, where status says whether the option was created or updated.


add_asset_to_product

Links an asset to a product. The product is the link origin, the asset the target.

Parameter Type Required Description
asset_code string yes Asset code.
document_code string yes Product code.
link_type string no Link type id. Resolved automatically when only one product → asset link type exists.
sequence integer no Position in the gallery, default 1.
force boolean no Link even if the asset is already linked elsewhere. Default false.
locale string no Interface locale.

remove_asset_from_product

Removes the link between an asset and a product.

Parameter Type Required Description
asset_code string yes Asset code.
document_code string yes Product code.
link_type string no Required only when several links exist between the two.
locale string no Interface locale.

Creates a link of any type between two objects: product → product (cross-sell, upsell, replacement), product → asset, etc. One link per call.

Parameter Type Required Description
origin string yes Origin object code.
target string yes Target object code.
link_type string yes Link type id from list_document_types (link_types), never a label.
locale string no Interface locale.

If the link already exists, returns already_linked: true without creating a duplicate.

Removes a link of any type. One link per call. Give either link_code, or origin + target + link_type.

Parameter Type Description
link_code string Link id, for a direct deletion.
origin / target / link_type string Identify the link when its id is not known.
locale string Interface locale.

If the link no longer exists, returns already_removed: true without an error.


Exports

Exports are asynchronous and follow four steps. See the export workflow.

list_export_profiles

Lists the export profiles saved in the PIM, with their UUID for trigger_export.

Parameter Type Required Description
search string no Search term passed to the export profiles API.
locale string no Interface locale.

get_export_options

Step 1: discovers what can be exported.

Parameter Type Required Description
model string no Returns the exportable columns of this model. Must be qualified as <base>.<type_id>, e.g. document.qua_document or link.<link_type_id>. A bare document returns HTTP 400.
extension csv | xlsx no Returns the formatting options of this format.
locale string no Interface locale.

Returns: the allowed export models, plus columns and format options when requested.

trigger_export

Step 2: starts an export and returns a process_id immediately. Give exactly one of export_profile_id or export_profile.

Parameter Type Description
export_profile_id string UUID of a saved profile, from list_export_profiles.
export_profile JSON string Inline profile, see below.
locale string Locale override.
upload_location string Remote delivery, e.g. sftp://host/path or ftp://host/path. The file is then not downloadable inline.
callback JSON string Webhook called when the export ends, e.g. {"url": "https://example.com/hook", "headers": {"X-Token": "..."}}.
portal_id string Portal to export from, if not the default one.

Inline profile, all columns (default):

{ "model": "document.qua_document", "extension": "csv", "locales": ["en_GB", "fr_FR"] }

Inline profile with a column selection (only when you ask for specific columns or headers):

{
  "model": "document.qua_document",
  "extension": "csv",
  "locales": ["fr_FR"],
  "mappings": [
    { "attributeCode": "document_code", "attributeType": "unlocalized_text", "name": "document", "position": 0 }
  ]
}

For localized attributes in mappings, add the locale in parentheses after the code, e.g. "qua_textfield (fr_FR)". Use get_export_options with model to get the exact column codes and types.

get_export_status

Step 3: polls an export.

Parameter Type Required Description
process_id string yes From trigger_export.
locale string no Interface locale.

Returns: {process_id, status, files: [{id, status}], startDate, endDate, hint}. status is pending, running, finished, failed or canceled. hint tells the assistant what to do next: poll again in about 10 seconds, download the file, or report that the file was delivered to the remote location or that the export failed.

get_export_file

Step 4: downloads the exported file.

Parameter Type Required Description
file_id string yes From files[].id in get_export_status.
locale string no Interface locale.

Quable delivers exports as a zip archive: the tool unzips it and returns the CSV or XLSX file itself (filename, mimetype, base64 content). Files above 250 KB return metadata only, with too_large: true. In that case, reduce the scope (fewer columns, locales or products), download the file from the Quable interface, or use upload_location.


Prompts

Prompts are ready-made instructions the agent can load.

Prompt Description
pim-bootstrap Start here. Tells the assistant to load your PIM structure (get_user_info, list_locales, list_document_types, list_completenesses) and to always use exact codes, never labels.
server_status_prompt Asks the assistant to check the server's health and metadata.

Resources

URI Description
server://info Server name, version and website.
skill://pim-links/SKILL.md Guidance for the assistant on giving links to PIM pages with get_pim_url.
skill://mcp-basics/SKILL.md Basic operational checks.