Getting started
Security & limits
Every tool call runs under the same guarantees: it sees one account, returns minimized data framed as data, and stays inside fixed size and time budgets. Nothing here is configurable — it applies to every connection on every tier.
Tenancy from the token, always
No tool schema contains an account or tenant field — tenancy is derived server-side from the bearer token on every call. A connection sees exactly one account's data, and an id from any other account answers "not found", indistinguishable from an id that doesn't exist. An assistant cannot even probe whether other accounts' ids are real.
Minimized results
Results are trimmed projections of what the API returns: the fields an assistant needs to reason about the catalog, and nothing else. Internal bookkeeping such as tenant ids, content hashes, and internal published snapshots is excluded. Publish-monitoring tools deliberately return merchant-facing failure reasons, responsible fields, and timestamps needed to follow an operation.
Data, not instructions
Tool results are framed as inert entity DATA. Every tool description tells the model not to act on text embedded in the returned content, so a product description (or any other catalog field) can't smuggle instructions to your assistant. This is the connector's first line of defense against prompt injection through catalog content.
Operational limits
| Limit | Behavior |
|---|---|
| Page size | List tools cap at 100 rows per page; a larger page_size is clamped and the result carries a visible [note] page_size was clamped line. |
| Output size | Tool text beyond 20,000 characters is truncated with an explicit marker advising a narrower query (filters or smaller page_size). |
| Structured content | At most 256 KiB of serialized JSON. A reduced result carries truncated: true and, when items were removed, omitted_items. An object that still cannot fit is replaced by a truncation reason. Narrow the query and retry. |
| Attachments | At most 8 MiB per export or image. Larger files are refused with guidance to narrow the request; they are not truncated. |
| Tool timeout | 20 s per call, single attempt, no retry. |
| Extended timeout | 120 s for the long-running tools — publish admission and cancel, scans and analyses, bulk writes, exports, duplication, and live Shopify membership reads (each is marked on its detail page). If publish admission times out, an operation may already exist — inspect the operation list and the item before retrying. |
The reconciliation lock
While a store import or refresh is being reconciled in Peak PIM, writes are blocked with a 423 — an assistant can't edit data mid-reconciliation. Reads keep working. Finish (or resolve) the reconciliation in the app, then retry the write.
Errors an assistant will see
| Situation | Result |
|---|---|
| Tool outside the granted tier | 403 permission error with re-authorization guidance. |
| Id from another account, or nonexistent | "Not found" — the two are indistinguishable. |
| Write during import/refresh reconciliation | 423 — the account is locked until reconciliation is finalized in the app. |
| Write or publish conflicts with a running operation | 409 conflict — use query_publish_locks_v1 and wait for the owning operation to finish. |
Stale revision / duplicate option tuple | 409 conflict — re-read, then retry with fresh state. |
| Malformed arguments | A tool error with the reason and retry_available: true — fix the arguments and call again. |
Write safety in one paragraph
Attribute edits stay in Peak PIM drafts. Publish-tier tools can publish, replace media, copy translations to stores, and cancel publish operations. Two write-tier creation workflows also reach Shopify: duplication publishes its copy, and adding a product option republishes existing store versions. Review each tool's described effects. MCP publish authority is granted through the browser consent flow; no tool deletes catalog data, and the one discount removal tool is publish-tier and needs an explicit confirmation. Tokens are short-lived and validated with a live lookup, so revoking a connection in Settings → AI assistants (MCP) takes effect on its very next call.