> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tool Reference > Input schemas, output shapes, and example calls for every tool exposed by the Closient MCP server. 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](/guides/mcp-install). For error semantics see [MCP Error Contract](/guides/mcp-errors). ## 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](/guides/mcp-errors) for the code table. * **Tool annotations** (`readOnlyHint`, `idempotentHint`, etc.) are documented separately in [MCP Tool Annotations](/guides/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:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ping", "arguments": {} } } ``` ```json theme={null} { "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:** ```json theme={null} { "name": "validate_gtin", "arguments": { "gtin": "614141123452" } } ``` ```json theme={null} { "valid": true, "error": null, "normalized": "00614141123452", "length": 12 } ``` ## `resolve_gtin` Apply the [GS1 Digital Link resolver-rule hierarchy](/guides/digital-link-resolution) 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:** ```json theme={null} { "name": "resolve_gtin", "arguments": { "gtin": "00614141123452", "link_type": "gs1:pip" } } ``` ```json theme={null} { "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:** ```json theme={null} { "name": "lookup_product", "arguments": { "gtin": "00614141123452" } } ``` ```json theme={null} { "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:** ```json theme={null} { "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` | 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:** ```json theme={null} { "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](/guides/digital-link-resolution) 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](/guides/mcp-authentication). Anonymous calls and calls with a token that doesn't include `qr:generate` return JSON-RPC error code `-32002` (`forbidden`). **Example:** ```json theme={null} { "name": "generate_qr_url", "arguments": { "gtin": "00614141123452", "batch": "LOT-A1", "serial": "SN-0001" } } ``` ```json theme={null} { "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](/guides/mcp-authentication) for the OAuth flow and [MCP Identity Propagation](/guides/mcp-identity) 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:** ```json theme={null} { "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` | 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:** ```json theme={null} { "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:** ```json theme={null} { "name": "set_product_ingredients", "arguments": { "gtin": "00614141123452", "raw_text": "Water, Sugar, Cocoa (Processed with Alkali), Salt. Contains: Milk. May Contain: Tree Nuts." } } ``` ## See also * [Install the MCP Server](/guides/mcp-install) * [Quickstart — 2 minutes to first resolution](/guides/mcp-quickstart) * [Authentication](/guides/mcp-authentication) * [MCP Error Contract](/guides/mcp-errors) * [MCP Identity Propagation](/guides/mcp-identity) * [MCP Tool Annotations](/guides/mcp-tool-annotations)