# MCP tools > Every tool on the TradeCatalog MCP server, its inputs, who can use it and what it returns. Tools use your current workspace role on every call. Read-only connections keep working. Making changes requires the additional `tradecatalog:write` scope. Consequential actions show a Confirm/Cancel card in compatible clients, with a signed-in review link as a fallback, and run only after you approve. Results are JSON text; the original lookup tools format prices, while management tools use integer minor currency units and basis points (100 = 1%). Most tools take a `workspace`: the workspace address from `list_workspaces`, like `northgate`. The AI app normally calls `list_workspaces` first on its own. When a tool can’t do something, for example you aren’t staff at that workspace or the customer doesn’t exist, it returns an error message the AI app can read and act on, like “No customer "OAK99". Use list_customers for account codes.” When a supplier’s catalog is prices only for the selected customer, `set_basket_quantity`, `send_order` and `reorder` return that error. `get_basket`, `list_buyer_orders` and `get_buyer_order` still work, so existing orders stay readable. The supplier sets this in Settings, and can override it per customer (`ordering`: `follow`, `prices_only` or `can_order` on `update_customer`). When the supplier has switched off price-list downloads, `download_my_price_list` returns an error and the signed-in CSV link answers 403. `quote_configured_product` reads the selected buyer account's line price for `productId`, `qty` and optional `configuration`, without changing a cart. `set_configured_basket_line` creates a separate line or updates/removes its exact `lineId` (`qty: 0` removes). Supply the full specification on edits. Re-read `get_basket` after changes and review all selections, measures and current prices before `send_order`. A specification or pricing-version change invalidates the old review even if the total is unchanged. Staff can use `save_product_family` for shared variant metadata and `save_ordering_draft` for a reviewed advanced-pricing draft. The latter requires Pro and global pricing permission; publication uses the existing price-change review. Product imports accept optional family, order increment and ordering definitions. See [trade catalog setup](/docs/guides/trade-catalogues). ## Set up a supplier workspace `create_workspace` creates a Free supplier workspace for the signed-in, verified person, after they confirm a card. Ask for the business name, product currency, timezone and country. The person becomes its owner. No subscription or payment is created. Then call `list_workspaces` again and use the returned address for product and customer setup. Reviewer and guest logins cannot create workspaces. Free includes up to 100 products and connected AI apps. Each SKU counts, including hidden and inactive products. At the allowance, existing products, edits and orders keep working; creating more products is unavailable. Explain this entitlement without promoting upgrades or starting subscription checkout in the plugin. ## list_workspaces Supplier workspaces you work in, and trade portals where you buy. Start here. **Who:** anyone signed in. **Inputs:** none. ```json { "supplierWorkspaces": [ { "workspace": "northgate", "name": "Northgate Fixings", "role": "owner" } ], "tradePortals": [ { "workspace": "hartley-timber", "supplier": "Hartley Timber", "yourAccount": "Northgate Fixings", "accountId": "example-account-id" } ] } ``` ## search_products Search a catalog by SKU, manufacturer reference, name, brand or category. Returns up to **25** products. **Who:** staff and buyers. | Input | Type | Required | Description | | ----------- | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `workspace` | string | yes | Workspace address. | | `query` | string | yes | What to search for. Empty lists products by name. | | `accountId` | string | buyers with more than one account | Select your exact account from `list_workspaces`. | | `customer` | string | no | Staff only: a customer’s account code or name, to see their prices and only what they can see. Ignored for buyers. | - **Buyers** always see their own account’s prices and only active products they can see. - **Staff** see list prices and every product, or a named customer’s view. ```json { "supplier": "Northgate Fixings", "pricesFor": "Oakfield Joinery", "taxNote": "ex VAT", "products": [ { "sku": "HX-8510", "name": "Hex bolt M10 x 50 zinc", "unit": "Box of 100", "availability": "in_stock", "price": "£15.73", "listPrice": "£18.50", "why": "Brand discount −15%" } ] } ``` When the supplier has switched off **Show customers the standard price beside their own price**, a buyer’s results leave out `listPrice` and `why`, and `get_buyer_product`, `get_basket` and `get_buyer_order` carry no list price or price reason either. Try: “Search Northgate for M10 hex bolts at Oakfield’s prices.” ## download_products_csv and download_my_price_list These tools return a link to an existing CSV download in TradeCatalog. Open it while signed in; returning a link does not download or send the file into chat. - `download_products_csv`: staff choose `workspace` to download that supplier's product list. - `download_my_price_list`: buyers choose `workspace` and the exact `accountId` from `list_workspaces` to download only that account's agreed prices. - `download_my_price_list_pdf`: the same account, as a branded PDF (Pro). Both tools are blocked when the supplier has turned off price-list downloads. ## check_price What a customer pays for a SKU at a quantity, and which rule set the price. **Who:** staff only. | Input | Type | Required | Description | | ----------- | ------- | -------- | -------------------------- | | `workspace` | string | yes | Workspace address. | | `customer` | string | yes | Account code or name. | | `sku` | string | yes | The SKU. | | `qty` | integer | no | 1 to 1,000,000. Default 1. | ```json { "customer": "Oakfield Joinery", "sku": "HX-8510", "name": "Hex bolt M10 x 50 zinc", "qty": 20, "unitPrice": "£15.73", "lineTotal": "£314.60", "listPrice": "£18.50", "why": "Brand discount −15%", "taxNote": "ex VAT" } ``` Try: “What does OAK01 pay for 20 of HX-8510, and why?” ## list_customers Trade customers with account codes, contact emails, active status and account discount. **Who:** staff only. **Inputs:** `workspace`. ```json [ { "accountCode": "OAK01", "name": "Oakfield Joinery", "email": "accounts@oakfieldjoinery.co.uk", "active": true, "discount": "5%" } ] ``` Try: “Which customers have no discount set?” ## list_orders Recent orders, newest first, up to **50**. **Who:** staff see every customer’s orders; buyers see their own account’s. | Input | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------------------------------- | | `workspace` | string | yes | Workspace address. | | `status` | string | no | `new`, `pending`, `acknowledged`, `processed`, `dispatched`, `completed` or `cancelled`. | ```json [ { "reference": "SO-000142", "customer": "Oakfield Joinery", "status": "new", "total": "£314.60", "poNumber": "PO-88231", "placed": "2026-09-27T07:48:12.000Z" } ] ``` Try: “Any new orders since yesterday? Total them up by customer.” ## recent_activity The activity log of changes to customers, discounts and prices, newest first, up to **50** entries. Optionally one customer’s history. **Who:** staff only. Owners and admins see the whole log; other staff see only changes about customers they can see. | Input | Type | Required | Description | | ----------- | ------ | -------- | --------------------- | | `workspace` | string | yes | Workspace address. | | `customer` | string | no | Account code or name. | ```json [ { "when": "2026-09-26T14:21:03.000Z", "who": "Jo Hartley", "customer": "Oakfield Joinery", "what": "Set Northgate brand discount to 15% (was 12.5%)" } ] ``` Try: “Who changed Oakfield’s prices this month?” ## Notes - Customer names and account codes are matched without regard to case. An exact account code is safest. - `list_workspaces` returns buyer `accountId` values. Supply the intended one to `search_products` and every buyer action. Never guess between accounts. - Page product searches with `offset` and the returned `nextOffset`. Use `list_buyer_orders` for an explicitly selected buyer account. ## Changes and confirmations Buyer cart edits, marking updates read and creating unpublished price drafts run immediately when authorized. Other writes return `awaiting_confirmation`, an `actionId` and a `reviewUrl`. ChatGPT and compatible clients display a card with the exact workspace and proposed change: choose **Confirm** or **Cancel** without leaving the conversation. Clients without cards use the signed-in review link. Reviews expire after 15 minutes and execute at most once. Disconnecting the app or removing the required workspace access invalidates pending reviews. Changed order carts and price-change previews require a new review. Use `get_action_status` to read the outcome; a pending request is not a completed action. The `decide_action` helper is available only to the card UI. Its short-lived confirmation capability is hidden from model output and bound to the requesting person, OAuth connection and proposal. A model message or an action ID cannot approve a change. The same role, snapshot, expiry and single-use checks apply to both card and browser approvals. Every buyer action requires your exact `accountId`. For `send_order`, copy the cart `fingerprint` into `expectedBasket`, alongside `expectedTotal`. Prices, quantities and account are checked again before sending. Use the separate handoff tools for work that finishes in the signed-in app: owners use `open_api_key_settings`, `download_workspace_export` and `open_logo_settings`; staff use `open_import_page`, `open_product_image_upload` and `open_product_file_manager`. The two product handoffs require a tenant-checked `productId`. File links from `get_product` and `get_buyer_product` require your signed-in browser; returning a link has not read the document or completed an upload, removal, export or credential creation. Platform administration is never delegated through OAuth. ## Approved customer lists Staff use `get_customer` to read the customer's catalog scope and approved products. `set_catalogue_scope` changes between `all` and `approved`. `approve_products` adds explicit products or a category; `unapprove_product` removes one product. These changes require review of the exact customer, current list and affected products. Category membership is checked again at confirmation. Buyers remain limited to their selected account and products visible to that account. ## Supplier and buyer tools `create_workspace` is available even when `list_workspaces` is empty. It creates a Free supplier workspace and owner membership only after confirmation. The optional `/mcp/account` connection also offers `open_billing`: owners can open secure subscription billing and confirm payment in Stripe, then check `get_settings` for the resulting state. Billing links do not complete payments. The standard `/mcp` connection used by the ChatGPT plugin does not expose `open_billing`. See [sign-up and billing](/docs/mcp#sign-up-and-pay-with-an-agent). MCP 3.0.0 exposes every model-callable operation upfront with its own name, description, input schema and annotations. The previous `bulk_products` and `open_workspace_action` tools are replaced by the individual operations below; refresh your client’s tool definitions after updating. The MCP `tools/list` response is the authoritative input schema. The following tools supplement the lookup tools above: | Tool | Purpose | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `open_api_key_settings` | Owner only: return the signed-in API settings page for creating credentials. Opening the link does not create a key. Never ask users to paste secrets into chat. | | `download_workspace_export` | Owner only: return the signed-in full workspace export link. The user must open the link to download it; this tool does not read or transfer the export. | | `open_logo_settings` | Owner only: return the signed-in branding settings page for uploading a supplier logo. Opening the link does not upload or change the logo. | | `open_import_page` | Staff: return the signed-in file import page. The user uploads and reviews the file in TradeCatalog; opening the link does not import anything. | | `open_product_image_upload` | Staff: return the signed-in editor for an existing product to upload an image. Opening the link does not upload or change an image. | | `open_product_file_manager` | Staff: return the signed-in editor for an existing product to upload or remove product files. Opening the link does not read, upload or remove files. | | `delete_workspace` | Owner only: permanently delete this workspace, its catalog, customer access and images, and cancel its subscription. Requires signed-in review and typing the workspace name. This cannot be undone in the app. | | `get_workspace` | Staff: current role, catalog and order totals. Amounts are integer minor currency units; percentages are basis points (100 = 1%). | | `get_catalogue_options` | Staff: list category and brand IDs for catalog and discount changes. | | `get_product` | Staff: product fields, current list price, visibility, customer restrictions, images and attached files (spec sheets). | | `save_product` | Create or edit a product. Read the current product first and preserve fields the user did not ask to change. listPrice is in minor units; existing-price changes use the app price-change flow. Requires review. | | `set_product_image` | Choose the main photo, or clear it. Clearing removes that photo from the gallery and the next one becomes the main photo. Requires review. | | `create_category` | Create a named category, optionally beneath a parent category. Requires review. | | `update_category` | Rename or move a category. Its products remain in it. Requires review. | | `delete_category` | Remove a category and its category discount rules. Products and child categories move up one level. Requires review. | | `hide_products` | Staff: hide explicit product IDs from buyers without deleting them. Requires review. | | `show_products` | Staff: make explicit product IDs active. Customer catalog restrictions still apply. Requires review. | | `move_products` | Staff: move explicit product IDs to one category, or pass null to remove their category. Requires review. | | `delete_products` | Staff: permanently delete explicit product IDs, including their prices, images and cart lines. Historical orders retain their copies. Requires review. | | `clear_catalogue` | Owner only: permanently remove every product, price and photo. Requires signed-in review and typing the current deletion phrase. | | `get_customer` | Staff: customer terms, price list, catalog scope, approved products, discount rules, agreed prices, buyers and pending invitations. `priceLists` are the lists you can assign with `update_customer`. Assigning a different non-Standard price list requires Pro. | | `create_customer` | Create a trade account. Its contact email can sign in as that account, so confirm the address. Requires review. | | `update_customer` | Change customer details, account code (`accountCode`; unique per supplier ignoring capitals, omit to keep), contact login email, extra update emails (`notifyEmails`), active status, the whole-list percentage (`discountBp`, 0 to 10,000) and its `adjustment` (`discount` or `markup`; omit to keep), ordering (`follow`, `prices_only` or `can_order`) and `priceListId` (null is Standard). Basis points: 100 = 1%. Read get_customer first. Requires review. Assigning a different non-Standard price list requires Pro. | | `save_discount_rule` | Set a customer category, brand or product percentage, in basis points (0 to 10,000). `adjustment` is `discount` or `markup`; omit it for a discount. The most specific rule wins and nothing stacks. Changes prices immediately. Requires review. Requires Pro. | | `remove_discount_rule` | Remove the selected customer discount rule. Prices may rise immediately. Requires review. | | `set_fixed_price` | Set a customer-specific product price in integer minor currency units. Optional `note` is a remark; `noteVisible` shows it to that customer. `internalNote` stays staff-only. Requires review. Requires Pro. | | `end_fixed_price` | End a fixed customer price now so normal discount rules apply. Requires review. | | `list_staff` | Staff: list the workspace team and pending invitations. | | `invite_staff` | Owner only: email an invitation granting staff or owner access. Requires review of recipient and role. | | `invite_buyer` | Staff: email an invitation to a specific customer account. Requires review of recipient and account. | | `remove_buyer` | Remove one membership from the named customer account. Requires review. | | `preview_product_import` | Preview parsed rows without importing. Do not silently repair uncertain source prices. | | `import_products` | Import at most 100 parsed rows. listPrice goes to priceList (omit for Standard); listPrices names other lists. Each list’s changes join one draft. Requires review. Image URLs may be fetched. | | `import_customers` | Import at most 100 customers. Optional priceList names their list; adjustment is discount or markup. An unknown list name is an error. Requires review. | | `preview_agreed_prices` | Preview up to 2,000 agreed prices (account code, SKU, integer minor-unit price and an optional note) without saving. Pro only. Unknown accounts and SKUs are reported and skipped. When an account and SKU are repeated, the last row is used. | | `import_agreed_prices` | Save up to 2,000 agreed prices for existing accounts and SKUs. Pro only. Each price is versioned from now, in batches of 100. Unknown rows are skipped. Requires review. | | `list_import_layouts` | List this supplier’s saved column mappings. | | `save_import_layout` | Save a reusable column mapping for this supplier. Requires review. | | `list_price_changes` | List drafts and scheduled or published price changes. | | `draft_price_change` | Create a draft percentage price change for one price list (`priceListId`; omit for Standard). One batch never mixes lists. Signed basis points: 600 = +6%, from −90% to +100%. Does not publish or email customers. Requires Pro. | | `preview_price_change` | Read the impact, warnings, fixed prices and scheduling clashes before publishing. | | `publish_price_change` | Publish now or at an ISO timestamp, optionally emailing customers (on publish or at a scheduled `notifyAt`) and changing agreed prices. Requires review of the current preview; changed previews invalidate approval. Pro is required except for immediate Standard-price imports without emails or agreed-price changes. | | `cancel_price_change` | Cancel a scheduled price change. Customers may be emailed a cancellation. Requires review. | | `discard_price_draft` | Permanently discard an unpublished price change. Requires review. | | `get_staff_order` | Staff: order lines, customer, notes and status history. | | `set_order_status` | Accept, process, complete or cancel an order using the app’s allowed transitions. May email the buyer. Requires review. | | `get_settings` | Read supplier settings and subscription state; no payment credentials are returned. | | `save_settings` | Owner only: change business details, order recipients, currency, directory listing, search preferences whether customers see the standard price beside their own (`showStandardPrice`; `false` shows only their own price), how products are ordered for customers (`productOrder`: `name`, `sku`, `category` or `custom`; `category` follows the Categories page order, A to Z by name within each category, uncategorised last), which catalog columns they see and in what order (`catalogueColumns`), the heading for each product’s trade deal note (`dealLabel`), whether the branded customer sign-in hides the staff sign-in link (`hidePortalStaffLink`; owner or admin, default false), whether staff page subtitles and how-to links are hidden (`hideStaffGuides`; owner or admin only, default false), whether the sign-in page opens on username and password (`loginUsernameFirst`; owner or admin only, default false so email stays first), and which parts of the branded PDF price list to print (`pdfShowLogo`, `pdfShowDate`, `pdfShowSupplierName`, `pdfShowCustomerName`, `pdfShowPageNumbers`; each true by default, false hides that part). Read current settings first. Requires review. | | `list_api_keys` | Owner only: list key labels and scopes. Never returns secrets. | | `revoke_api_key` | Owner only: disconnect an API integration immediately. Requires review. | | `list_news` | Staff: list announcements, including expired posts. | | `post_news` | Publish an announcement to buyers, now or from `startsLocal` (supplier time). Optional `endsOn` hides it at `YYYY-MM-DDTHH:mm` in the supplier timezone, or at the end of a `YYYY-MM-DD`. emailCustomers also emails subscribers when it starts. Requires review of the exact message and audience. | | `remove_news` | Remove a published announcement. Sent emails cannot be recalled. Requires review. | | `list_support_tickets` | Owner and Admin only: list this workspace’s support tickets. | | `get_support_ticket` | Owner and Admin only: read messages on a ticket belonging to this workspace. | | `open_support_ticket` | Owner and Admin only: send a support request to Happy Webs. Requires review of the exact message. | | `reply_to_support` | Owner and Admin only: send a reply to an existing support conversation. Requires review. | | `get_buyer_product` | Read a visible product with prices and attached files (spec sheets) for the explicitly selected account. | | `get_basket` | Read current quantities and prices for your explicitly selected customer account. | | `set_basket_quantity` | Set an absolute quantity (0 removes the line). Only changes your cart; does not send an order. | | `send_order` | Send the selected account’s cart to the supplier, with buyer email copy. Requires signed-in review of exact products, quantities, prices, PO and notes. If the cart changes, request a fresh review. Copy expectedBasket from get_basket.fingerprint. | | `list_buyer_orders` | Read orders for the explicitly selected account. | | `get_buyer_order` | Read lines and status history for an order belonging to the selected account. | | `reorder` | Add available products from a past order to your cart at current prices. Does not send an order. Requires review. | | `get_buyer_updates` | Read current news, your price changes and unread updates for the selected customer account. | | `mark_updates_read` | Mark the selected account’s currently available updates as read. | | `get_action_status` | Read the result of a review requested by this connection. | Staff order entry uses `preview_customer_order` then reviewed `create_customer_order` with exact prices and a retry UUID. Processing uses `set_order_status` with public `note`, private `internalNote`/`correctionReason`, and `expectedRevision`. Reviewed `set_order_delivery` records a customer-visible delivery method and optional courier, reference and HTTPS link. These tools follow the member’s current permissions and customer scope. See [Orders](/docs/api/orders) for the fields and behavior.