MCP Tool Reference

This page is the authoritative reference for the tools the Closient MCP server registers via tools/list. Every tool described here is a thin wrapper around the same service-layer functions used by the REST API — if a call would succeed via the REST API for the authenticated principal, it succeeds via MCP, and vice versa. For installation see Install the MCP Server. For error semantics see MCP Error Contract.

Conventions

GTIN inputs accept GTIN-8, GTIN-12, GTIN-13, or GTIN-14 with or without leading zeros. Closient normalizes everything to GTIN-14 internally — the normalized form is echoed back in the response.
Optional fields in the input schema default to None/null and are omitted from the resulting query when not supplied.
Errors are returned as JSON-RPC error objects with an RFC 9457 Problem Details payload in data. See MCP Error Contract for the code table.
Tool annotations (readOnlyHint, idempotentHint, etc.) are documented separately in MCP Tool Annotations.

`ping`

Health probe. Returns the string "pong". Useful from an agent preamble to verify the MCP connection is live before issuing real calls. Input: no arguments. Output: string — always "pong". Auth: none. Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "ping", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "content": [ { "type": "text", "text": "pong" } ] }
}

`validate_gtin`

Pure GTIN validation — check digit, length, format. No catalog lookup, no auth.

Field	Type	Required	Description
`gtin`	`string`	yes	A GTIN-8/12/13/14 string. Leading zeros are accepted but not required.

Output:

Field	Type	Description
`valid`	`boolean`	Overall validity.
`error`	`string` \| `null`	Human-readable reason if invalid.
`normalized`	`string` \| `null`	Zero-padded GTIN-14 if valid.
`length`	`integer`	Original GTIN length (before normalization).

Example:

{
  "name": "validate_gtin",
  "arguments": { "gtin": "614141123452" }
}

{
  "valid": true,
  "error": null,
  "normalized": "00614141123452",
  "length": 12
}

`resolve_gtin`

Apply the GS1 Digital Link resolver-rule hierarchy and return the destination the resolver would redirect to for a given GTIN. Use this to learn what page (or external URL) a brand has configured for a product without actually following the redirect.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN.
`link_type`	`string`	no	GS1 link-type CURIE such as `gs1:pip` or `gs1:recallStatus`. When omitted, the default link-type rule wins.

Output:

Field	Type	Description
`destination_url`	`string`	Where the resolver would redirect.
`destination_type`	`string`	`HOSTED_PAGE` or `CUSTOM_URL`.
`fallback_applied`	`boolean`	`true` when no rule matched and the default was used.
`product_found`	`boolean`	Whether a Product row exists for the GTIN.
`matched_rule_scope`	`string` \| `null`	`PRODUCT`, `BRAND`, `ORGANIZATION`, `GLOBAL`, or `null`.

Example:

{
  "name": "resolve_gtin",
  "arguments": { "gtin": "00614141123452", "link_type": "gs1:pip" }
}

{
  "destination_url": "https://www.closient.com/01/00614141123452",
  "destination_type": "HOSTED_PAGE",
  "fallback_applied": false,
  "product_found": true,
  "matched_rule_scope": "PRODUCT"
}

`lookup_product`

Look up the structured catalog record for a GTIN. Returns found: false (rather than an error) when the GTIN is unknown so agents can branch on the boolean without try/except plumbing.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN.

Output:

Field	Type	Description
`found`	`boolean`	Whether the GTIN is in the catalog.
`gtin`	`string` \| `null`	Normalized GTIN-14 if found.
`name`	`string` \| `null`	Product name.
`brand`	`string` \| `null`	Brand name.
`description`	`string` \| `null`	Product description.
`data_source`	`string` \| `null`	Origin of the record (`manual`, `off`, etc.).
`metadata`	`object`	Flat string-to-string developer metadata. `{}` when unset.

Example:

{ "name": "lookup_product", "arguments": { "gtin": "00614141123452" } }

{
  "found": true,
  "gtin": "00614141123452",
  "name": "Sample Cereal",
  "brand": "Acme Foods",
  "description": "Whole-grain breakfast cereal.",
  "data_source": "manual",
  "metadata": { "internal_sku": "ACM-1234" }
}

`search_products`

Natural-language search across the Closient catalog. Combines pgvector semantic search with PostgreSQL full-text lexical search and (optionally) PostGIS-based geographic boosting.

Field	Type	Required	Description
`query`	`string`	yes	Free-text search string. Example: `"organic oat milk"`.
`filters`	`object`	no	Flat `{key: value}` dict applied to structured metadata. Useful keys: `brand`, `category_id`, `country_of_origin`.
`geo_lat`	`number`	no	Latitude (WGS84) — requires `geo_lng`.
`geo_lng`	`number`	no	Longitude (WGS84).
`limit`	`integer`	no	Max results. Defaults to `20`.

When both geo_lat and geo_lng are present, results within 50 km are boosted by proximity. Output:

Field	Type	Description
`items`	`array`	Ordered by relevance (highest score first). Each item has `gtin`, `brand`, `category`, `net_content`, `country_of_origin`, `price_min`, `price_max`, `score`, `distance_km`.
`total`	`integer`	Number of items returned.
`query`	`string`	Echo of the input query.

Example:

{
  "name": "search_products",
  "arguments": {
    "query": "gluten-free pasta",
    "geo_lat": 40.7128,
    "geo_lng": -74.0060,
    "limit": 5
  }
}

`get_product_detail`

Comprehensive product record — attributes, images, ingredients, nutrition facts. Use after search_products (or whenever a GTIN is already in hand) to fetch everything in one round-trip.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN.

Output:

Field	Type	Description
`found`	`boolean`	`false` for unknown GTINs; other fields are then null/empty.
`product`	`object` \| `null`	Compact summary (gtin, name, brand, category, description, image_url, net_content, country_of_origin).
`images`	`array`	`{url, title, description, priority, is_primary}` rows ordered by priority then creation time.
`ingredients`	`array`	`{name, percentage_of_weight, priority}` rows.
`nutrition`	`object` \| `null`	`{serving_size, servings_per_container, label_format, nutrients: [{name, amount, unit, daily_value_pct}, ...]}` or `null`.
`hosted_page_url`	`string`	The canonical hosted-page path (`/01/{gtin14}`).

`compare_products`

Side-by-side comparison of 2-5 products by GTIN. Unknown GTINs appear as found: false columns rather than raising — partial comparisons are useful.

Field	Type	Required	Description
`gtins`	`array<string>`	yes	2-5 GTINs. Order is preserved in the response.

Output:

Field	Type	Description
`items`	`array`	One column per requested GTIN — `{found, gtin, product}`.
`attributes`	`array`	Aligned attribute rows — `{name, values}` where `values[i]` corresponds to `items[i]`. Currently: `brand`, `category`, `net_content`, `country_of_origin`, `price_min`, `price_max`.

Example:

{
  "name": "compare_products",
  "arguments": { "gtins": ["00614141123452", "00614141999999"] }
}

`check_availability`

Find nearby physical stores carrying a specific product. Returns active in-store offers within radius_km, ordered by ascending distance. When no offers exist for the product, the response is structurally well-formed (empty locations) rather than an error so agents can confidently say “no nearby availability” without exception handling.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN.
`lat`	`number`	yes	Latitude (WGS84) of the search origin.
`lng`	`number`	yes	Longitude (WGS84).
`radius_km`	`number`	no	Maximum search radius in km. Defaults to `25`.

Output:

Field	Type	Description
`gtin`	`string`	Normalized GTIN-14 echoed for convenience.
`radius_km`	`number`	Echo of the search radius.
`locations`	`array`	`{retailer, store_name, address, city, region, postal_code, distance_km, price, currency, inventory_status}` rows.
`total`	`integer`	Number of locations returned (may be `0`).

`generate_qr_url`

Build the canonical GS1 Digital Link URL for a GTIN, optionally with batch/lot and serial qualifiers. The returned URL is what should be encoded into a 2D barcode (QR or Data Matrix). When scanned, the URL hits Closient’s resolver at /01/{gtin14}[/10/{batch}][/21/{serial}] and returns the linkset or redirects to the destination per the resolver rules.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN — normalized to GTIN-14 in the URL.
`batch`	`string`	no	Batch / lot identifier (GS1 AI 10).
`serial`	`string`	no	Unique serial (GS1 AI 21).

Output:

Field	Type	Description
`qr_url`	`string`	The canonical Digital Link URL.
`gtin14`	`string`	Normalized GTIN-14 used in the URL.
`host`	`string`	Host portion of the URL (from `SITE_URL`).

Auth: OAuth 2.0 bearer token with qr:generate scope. See Authentication. Anonymous calls and calls with a token that doesn’t include qr:generate return JSON-RPC error code -32002 (forbidden). Example:

{
  "name": "generate_qr_url",
  "arguments": {
    "gtin": "00614141123452",
    "batch": "LOT-A1",
    "serial": "SN-0001"
  }
}

{
  "qr_url": "https://www.closient.com/01/00614141123452/10/LOT-A1/21/SN-0001",
  "gtin14": "00614141123452",
  "host": "www.closient.com"
}

Product write tools

Every tool in this section requires an OAuth 2.0 bearer token issued via the authorization_code grant (an end-user token — client_credentials tokens have no user to attribute writes to and are rejected). The caller must additionally hold organization membership with the permission noted per tool: CONTRIBUTE (OWNER, MANAGER, or EDITOR role) for most tools, or OWNER/MANAGER specifically for create_product. See Authentication for the OAuth flow and MCP Identity Propagation for how the acting user is threaded through to the audit trail. Two scopes gate this family: products:write (create_product, update_product) and dashboard:write (everything else — images, documents, videos, nutrition, ingredients).

`create_product`

Create a new product and claim it for an organization — the first step of brand-owner product entry for a GTIN not yet in Closient’s catalog.

Field	Type	Required	Description
`gtin`	`string`	yes	A GTIN-8/12/13/14, leading zeros optional.
`product_name`	`string`	yes	Display name.
`organization_id`	`string`	no	The organization’s public identifier — either the 22-char shortuuid form (as returned everywhere else in the API) or a dashed UUID. Omit to use the caller’s org automatically (only unambiguous with exactly one OWNER/MANAGER membership).
`description`	`string`	no	Long-form description.
`country_of_origin`	`string`	no	ISO 3166-1 alpha-2 code.
`net_content`	`string`	no	Free text, e.g. `"340g"`.
`metadata`	`object`	no	Stripe-style flat developer metadata.

Output: compact product summary — {gtin, name, brand, category, description, image_url, net_content, country_of_origin}. Auth: products:write scope; caller must be OWNER or MANAGER of the target organization.

`update_product`

Update basic info, structured net content, dimensions/weight, or GPC classification on a claimed product — all share a single field allowlist (Product.BRAND_EDITABLE_FIELDS), so one tool covers all three.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN.
`updates`	`object`	yes	Flat `{field: value}` map. Unrecognized keys are ignored. `brand`/`manufacturer` accept a plain name string (looked up case-insensitively, created if no match). Editable fields: `product_name`, `brand`, `category_id`, `description`, `usage_instructions`, `country_of_origin`, `primary_language`, `manufacturer`, `brand_product_page_url`, `net_content_value`, `net_content_uom`, `length`/`width`/`height`/`depth` + their `_uom`, `gross_weight`/`net_weight` + their `_uom`, `gpc_segment_code`/`gpc_family_code`/`gpc_class_code`/`gpc_brick_code`.

Output: compact product summary (same shape as create_product). Auth: products:write scope; caller needs CONTRIBUTE permission on the owning organization. Example:

{
  "name": "update_product",
  "arguments": {
    "gtin": "00614141123452",
    "updates": {
      "net_weight": "340",
      "net_weight_uom": "GRM",
      "gpc_brick_code": "10000045"
    }
  }
}

`upload_product_image`

Upload an image and attach it to a claimed product.

Field	Type	Required	Description
`gtin`	`string`	yes	A valid GTIN.
`image_base64`	`string`	yes	Base64-encoded image bytes. An optional `data:image/...;base64,` prefix is tolerated.
`filename`	`string`	yes	Used to name the stored file; actual format is sniffed from the bytes.
`title`	`string`	no
`is_primary`	`boolean`	no	Marks this the hero image, unsetting any existing primary. Defaults to `false`.

Output: {id, url, title, is_primary, priority}. Auth: dashboard:write scope; caller needs CONTRIBUTE permission.

`delete_product_image`

Delete an image from a claimed product. Immediate and permanent.

Field	Type	Required	Description
`gtin`	`string`	yes
`image_id`	`string`	yes	The `id` from `upload_product_image` or `get_product_detail`.

Output: {deleted: true, image_id}.

`upload_product_document`

Upload a PDF (spec sheet, safety data sheet, certificate) and attach it to a claimed product. Non-PDF content is rejected. Dispatches an async metadata/thumbnail extraction task; the response reflects the upload itself, not the enrichment (visible on a subsequent get_product_detail).

Field	Type	Required	Description
`gtin`	`string`	yes
`file_base64`	`string`	yes	Base64-encoded PDF bytes.
`filename`	`string`	yes
`title`	`string`	no
`description`	`string`	no

Output: {id, url, title, description, file_size_bytes}.

`update_product_document`

Partially update a document’s title/description, and optionally replace its file, on a claimed product.

Field	Type	Required	Description
`gtin`	`string`	yes
`document_id`	`string`	yes
`title`	`string`	no	Omit/null to leave unchanged.
`description`	`string`	no	Omit/null to leave unchanged.
`file_base64`	`string`	no	Supply together with `filename` to replace the file, or omit both.
`filename`	`string`	no

Output: {id, url, title, description, file_size_bytes}.

`delete_product_document`

Delete a document from a claimed product. Immediate and permanent.

Field	Type	Required	Description
`gtin`	`string`	yes
`document_id`	`string`	yes

Output: {deleted: true, document_id}.

`add_product_video`

Attach a YouTube video link to a claimed product. YouTube only — Closient does not host video files.

Field	Type	Required	Description
`gtin`	`string`	yes
`youtube_url`	`string`	yes	Any URL format YouTube supports; rejected if no video ID can be extracted.
`title`	`string`	no
`description`	`string`	no
`priority`	`integer`	no	Lower sorts first. Defaults to `0`.

Output: {id, youtube_url, video_id, title, description, priority}.

`update_product_video`

Partially update a video attached to a claimed product.

Field	Type	Required	Description
`gtin`	`string`	yes
`video_id`	`string`	yes
`updates`	`object`	yes	Flat map of any of `youtube_url`, `title`, `description`, `priority`.

Output: same shape as add_product_video.

`delete_product_video`

Delete a video from a claimed product. Immediate and permanent.

Field	Type	Required	Description
`gtin`	`string`	yes
`video_id`	`string`	yes

Output: {deleted: true, video_id}.

`set_product_nutrition`

Create or wholesale-replace a product’s entire nutrition-facts panel — the header plus every nutrient row — in one call. Reconciles nutrients against what’s already stored by nutrient_type: matched rows are updated, new types are created, and rows omitted from this call are deleted. This is not a merge/patch operation — always pass the complete label.

Field	Type	Required	Description
`gtin`	`string`	yes
`serving_size`	`string`	yes	Free text as printed, e.g. `"1 cup (240ml)"`.
`nutrients`	`array<object>`	yes	Each row: `{nutrient_type, amount, unit, daily_value_pct?}`. `nutrient_type` is one of the model’s `NutrientType` choices (`CALORIES`, `TOTAL_FAT`, `SATURATED_FAT`, `TRANS_FAT`, `CHOLESTEROL`, `SODIUM`, `TOTAL_CARBS`, `DIETARY_FIBER`, `TOTAL_SUGARS`, `ADDED_SUGARS`, `PROTEIN`, `VITAMIN_D`, `CALCIUM`, `IRON`, `POTASSIUM`, …). `unit` is one of `G`, `MG`, `MCG`, `KCAL`, `KJ`, `IU`, `ML`. Duplicate `nutrient_type` values in the same call are rejected.
`serving_size_g`	`number`	no
`servings_per_container`	`number`	no
`label_format`	`string`	no	One of `US_FDA` (default), `EU`, `CA_CFIA`, `AU_NZ`, `UK`.

Output: {serving_size, servings_per_container, label_format, nutrients: [{nutrient_type, amount, unit, daily_value_pct}, ...]}. Example:

{
  "name": "set_product_nutrition",
  "arguments": {
    "gtin": "00614141123452",
    "serving_size": "1 cup (240ml)",
    "nutrients": [
      { "nutrient_type": "CALORIES", "amount": 150, "unit": "KCAL" },
      { "nutrient_type": "SODIUM", "amount": 200, "unit": "MG" }
    ]
  }
}

`set_product_ingredients`

Set a product’s ingredient statement from raw label text — Closient parses it into structured substance mentions automatically (splitting out a “may contain” / cross-contamination section, resolving each mention to a known substance where possible). Wholesale-replaces any previously parsed ingredient list for the product; there is no incremental “add one ingredient” tool over MCP today. Mirrors the ingredients field on the public PATCH /products/{gtin} REST endpoint.

Field	Type	Required	Description
`gtin`	`string`	yes
`raw_text`	`string`	yes	The ingredient statement exactly as printed on the label.

Output: {raw_text, ingredients: [{name, raw_text, match_type, confidence, is_sub_ingredient}, ...]}. name is null when the parser couldn’t resolve a mention (match_type: "UNRESOLVED"). Example:

{
  "name": "set_product_ingredients",
  "arguments": {
    "gtin": "00614141123452",
    "raw_text": "Water, Sugar, Cocoa (Processed with Alkali), Salt. Contains: Milk. May Contain: Tree Nuts."
  }
}

Getting Started

Developer Questions

User Guides

Technical Guides

MCP Server

Agent Skills

Compliance

Concepts

API Reference

Resources

MCP Tool Reference

Conventions

`ping`

`validate_gtin`

`resolve_gtin`

`lookup_product`

`search_products`

`get_product_detail`

`compare_products`

`check_availability`

`generate_qr_url`

Product write tools

`create_product`

`update_product`

`upload_product_image`

`delete_product_image`

`upload_product_document`

`update_product_document`

`delete_product_document`

`add_product_video`

`update_product_video`

`delete_product_video`

`set_product_nutrition`

`set_product_ingredients`

See also

​Conventions

​ping

​validate_gtin

​resolve_gtin

​lookup_product

​search_products

​get_product_detail

​compare_products

​check_availability

​generate_qr_url

​Product write tools

​create_product

​update_product

​upload_product_image

​delete_product_image

​upload_product_document

​update_product_document

​delete_product_document

​add_product_video

​update_product_video

​delete_product_video

​set_product_nutrition

​set_product_ingredients

​See also

Conventions

`ping`

`validate_gtin`

`resolve_gtin`

`lookup_product`

`search_products`

`get_product_detail`

`compare_products`

`check_availability`

`generate_qr_url`

Product write tools

`create_product`

`update_product`

`upload_product_image`

`delete_product_image`

`upload_product_document`

`update_product_document`

`delete_product_document`

`add_product_video`

`update_product_video`

`delete_product_video`

`set_product_nutrition`

`set_product_ingredients`

See also