Tools reference · Trenz MCP

Trenz MCP has 18 tools. Your assistant chooses the tool and fills in the parameters from your request, so you rarely need this page to use Trenz. It helps when you read the assistant's steps or want to ask for something specific.

Each tool is marked Reads data or Can change things. On ChatGPT Pro only tools that read data are available; see Connect ChatGPT.

Common values:

Countries: us, gb, th, my, vn, mx, id, ph, sg, jp, br, fr, de, es, it.
Entities: products, creators, videos, sellers (shops), ads, lives (livestreams), creatives (ad creatives).

Product research

These tools read TikTok Shop market data. They do not use credits.

`search`

Reads data

Finds TikTok Shop products, creators, videos, shops, ads, livestreams or ad creatives. This is where data questions start; use get_detail for full data on a result. With an uploaded photo, it finds visually similar products.

Parameter	Type	Required	Description
`entity`	string	Yes	One of the entities above.
`country`	string	Yes	Country code.
`keyword`	string	No	Full-text search.
`category`	string	No	Category ID or exact name, in English or Chinese. A wrong value returns the list of valid categories.
`sort`	string	No	`field:asc` or `field:desc`. Fields depend on the entity, for example `sold_7d`, `gmv_30d` or `price` for products and `followers` or `engagement` for creators.
`filters`	object	No	Ranges and flags for the entity, for example `min_sold_7d`, `max_price` or `free_shipping` for products, `min_followers` or `has_contact` for creators.
`limit`	integer	No	Results per call, 1 to 10. Default 10.
`offset`	integer	No	Item offset for the next page.
`image_os_key`	string	No	Products only. The `os_key` of a photo uploaded with `upload_file`. Image search uses only `country` and returns one page.

Sort fields by entity:

Entity	Sort fields
`products`	`daily_sold`, `sold_7d`, `sold_30d`, `gmv_7d`, `gmv_30d`, `price`, `rating`
`creators`	`followers`, `follower_growth_7d`, `avg_views`, `engagement`, `gmv_30d`, `video_gmv_30d`
`videos`	`views`, `likes`, `engagement`, `sold_30d`, `gmv_30d`, `launch_time`
`sellers`	`sold_7d`, `gmv_7d`, `total_sold`, `total_gmv`, `product_count`, `rating`
`ads`	`cost`, `days`, `engagement`, `gmv`, `views`
`lives`	`audience`, `peak_audience`, `gmv`, `sold`, `start_time`
`creatives`	`engagement`, `gmv`, `gpm`, `likes`, `plays`

`get_detail`

Reads data

Full data for one product, creator, video, shop, ad, livestream or ad creative, using an ID from search.

Parameter	Type	Required	Description
`entity`	string	Yes	One of the entities above.
`id`	string	Yes	The item's ID.
`country`	string	Yes	Country code.
`include`	string	No	Extra sections, comma-separated. Products and shops: `core`, `channel`. Creators: `core`, `channel`, `portrait` (audience). Videos, ads and livestreams: `core`. Ad creatives: `analysis`. Each extra section counts as another call.
`verbose`	boolean	No	`true` returns every SKU instead of a summary. Default `false`.

`get_related`

Reads data

Connections between items: who sells a product, what a creator promotes, what buyers say in reviews, and similar or competing items. When going from a creator, video or ad to its products, sales and GMV are the ones that creator, video or ad drove.

Parameter	Type	Required	Description
`entity`	string	Yes	`products`, `creators`, `videos`, `sellers`, `ads` or `lives`.
`id`	string	Yes	The item's ID.
`relation`	string	Yes	Depends on the entity (see below).
`country`	string	Yes	Use the same country as the call that returned the ID.
`page`	integer	No	Starts at 0.
`page_size`	integer	No	1 to 10. Default 10.

Entity	Relations
`products`	`creators`, `videos`, `reviews`, `similar`, `lives`
`creators`	`products`, `videos`, `similar`, `lives`
`videos`	`products`, `reviews`, `similar`
`sellers`	`products`, `creators`, `videos`
`ads`	`products`, `similar`
`lives`	`products`, `similar`

`rankings`

Reads data

Market leaderboards for products, shops and creators. For your own accounts and posts, the assistant uses the social tools instead.

Parameter	Type	Required	Description
`action`	string	Yes	Which ranking (see below).
`country`	string	Yes	Country code.
`params`	object	No	`date` (YYYYMMDD) and `granularity` (`daily`, `weekly` or `monthly`) for most rankings, plus `category`, `sort`, `page` (from 1) and `page_size` (up to 20).

Action	Ranking
`products_top_selling`	Best-selling products.
`products_most_promoted`	Products promoted by the most creators, videos and livestreams.
`products_new_arrivals`	Recently listed products gaining sales. Filter with `listed_from` and `listed_to`.
`sellers_top_selling`	Best-selling shops.
`sellers_most_promoted`	Shops promoted by the most creators.
`creators_commercial`	Creators by sales they drive.
`creators_growth`	Creators by follower growth.
`creators_agencies`	Creator agencies over the last 30 days.

AI content

AI generation uses trenz.ai credits at the same price as on the website. Failed tasks are refunded automatically.

`ai_generate`

Can change things

Starts an AI generation or analysis task and returns a task_id. The assistant then checks it with check_task.

Parameter	Type	Required	Description
`type`	string	Yes	What to generate (see below).
`params`	object	Yes	`prompt` for generation types, plus the options for that type. Images and reference media are passed as `{ "url": ... }`.

Type	Generates	Main parameters
`seedance`	Video (Seedance 2.0 Pro)	`prompt`, `aspect_ratio`, `duration` (4 to 15 s), `resolution` (`720p` or `1080p`), `images`, `reference_videos`, `reference_audios`, `audio`
`seedance_fast`	Video (Seedance 2.0 Pro Fast)	Same as `seedance`, 720p only
`wan26`	Video from an image	`prompt`, `image`, `duration` (5, 10 or 15 s), `resolution`
`happyhorse`	Video	`prompt`, `images`, `aspect_ratio`, `duration` (3 to 15 s), `resolution`
`gpt_image`	Images (GPT Image 2)	`prompt`, `function_type` (`general_edit`, `ai_clothing`, `product_image`, `digital_avatar`, `handheld_product`), `ratio`, `image_size` (`1K`, `2K`, `4K`), `images`
`nanobanana`	Images	Same as `gpt_image`
`script_breakdown`	Script and structure of a TikTok video	`video_id`, `language`, `country_code`
`review_analysis`	Summary of a product's buyer reviews	`product_id`, `country_code`

`check_task`

Can change things

Checks an ai_generate task and returns the result when it is done. Checking progress does not count toward your 7-day allowance, except for video script breakdowns.

Parameter	Type	Required	Description
`task_id`	string	Yes	The ID returned by `ai_generate`.

`canvas`

Can change things

Builds AI canvases: image, video, text and audio nodes joined by links that give each generation its context. Creating a canvas requires Pro or Scale. Edits must include the canvas's current expected_revision.

Parameter	Type	Required	Description
`action`	string	Yes	What to do (see below).
`params`	object	Depends	Parameters for the action.

Action	What it does	Main parameters
`create`	Creates an empty canvas.	`name`
`load`	Returns a canvas and its current revision.	`canvas_id` (omit for your default canvas)
`list`	Lists your canvases.	`limit`, `cursor`
`delete`	Deletes a canvas.	`canvas_id`, `expected_revision`
`apply`	Applies a batch of edits: add, update or remove nodes and links, attach assets, rename.	`canvas_id`, `expected_revision`, `operations` (1 to 200)
`generate`	Generates the content of one node.	`canvas_id`, `expected_revision`, `target_node_id`, `prompt`, `generation`
`share_create`	Creates a public read-only link.	`canvas_id`
`share_view`	Reads a shared canvas.	`token`
`share_clone`	Copies a shared canvas into a new canvas.	`token`, `name`
`hydrate`	Returns preview URLs valid for 24 hours.	`refs`

`canvas_tasks`

Reads data

Checks the generation tasks started on a canvas. It never changes the canvas.

Action	What it does	Main parameters
`detail`	Status, results and preview URLs of one task.	`task_id`
`batch_detail`	Status of several tasks.	`task_ids`

`assets`

Reads data

Browses your Trenz asset library, for example to use an asset on a canvas. Files sent with upload_file do not appear here.

Action	What it does	Main parameters
`list`	Lists assets.	`keyword`, `content_type` (`image`, `video`, `text`), `source` (`creation`, `upload`, `tiktok_shop`), `perf_tier` (`fire`, `good`, `mid`, `low`), `sort_by`, `order`, `limit`, `offset`
`detail`	Returns one asset.	`id`

`upload_file`

Can change things

Gets an upload link for your own image or video, used for publishing, adding a file to a canvas, or image search. It returns a url to upload to (valid for 180 seconds), a signed_url to read the file (valid for 24 hours), and the os_bucket and os_key that other tools take.

Parameter	Type	Required	Description
`file_name`	string	Yes	File name with extension.

These tools work on the social accounts you connected to trenz.ai. Publishing, replying, deleting and changing your showcase act on your real accounts; Trenz instructs the assistant to confirm with you first.

`social_accounts`

Can change things

Lists your connected accounts and creates links to connect new ones. The numeric id from list is the account ID the other social tools take.

Action	What it does	Main parameters
`list`	Lists connected accounts, with lifetime metrics.	`keyword`, `platforms`, `statuses`, `sort_by`, `page`, `page_size`
`detail`	Returns one account.	`account_id`
`disconnect`	Disconnects an account.	`account_id`
`update_remark`	Sets a note on an account.	`account_id`, `remark`
`get_tiktok_auth_url`	Link to connect a TikTok account.
`get_tiktok_shop_auth_url`	Link to connect a TikTok Shop creator, official or marketing account. Seller Center shops are authorized separately.	`type` (region)
`get_instagram_auth_url`	Link to connect an Instagram Business or Creator account.
`get_facebook_auth_url`	Link to connect Facebook Pages.
`login_qrcode`	TikTok QR code to scan in the TikTok app, with a link to a page that shows the code.
`login_check`	Checks whether the QR code was scanned.	`token`

`social_publish`

Can change things

Publishes videos, images and text posts, schedules them, and tracks their status and history.

Action	What it does	Main parameters
`upload_and_publish`	Publishes or schedules a post to one or more accounts.	`video_title`, `publications` (account, title, description, `scheduled_at`, `platform_config`), `content_type` (`video`, `image`, `text`), `bucket_name` and `bucket_key` for video, `media_items` for images, `dry_run`
`records`	Lists published, scheduled, draft, failed and cancelled posts.	`status`, `platform`, `search`, `sort_by`, `start_time`, `end_time`, `page`
`detail`	Returns one post.	`publication_id`
`session`	Checks the progress of a publish request.	`session_token`
`platform_videos`	Lists the videos on one account.	`platform_account_id`, `limit`
`refresh`	Refreshes a video's metrics.	`platform_account_id`, `platform_video_id`
`export`	Exports post records to an Excel file.	`platform`, `start_time`, `end_time`
`check_info`	Checks an uploaded file before publishing.	`bucket_name`, `object_key`
`reschedule`	Moves a scheduled post.	`publication_id`, `scheduled_at`
`cancel`	Cancels a scheduled post.	`publication_id`
`cancel_session`	Cancels a publish request.	`session_token`

platform_config sets per-platform options such as privacy, comments, AI-generated disclosure, music, location and the TikTok Shop product to link.

`social_comments`

Can change things

Reads, replies to, hides, likes and deletes comments on your posts.

Action	What it does	Main parameters
`list`	Lists comments.	`platform_account_ids`, `platforms`, `platform_video_id`, `keyword`, `owner_replied`, `is_read`, `sort_by`, `limit`
`managed_replies`	Lists replies to one comment.	`platform_account_id`, `platform_comment_id`
`create`	Posts a comment on a video.	`platform_account_id`, `platform_video_id`, `text`
`reply`	Replies to a comment.	`platform_account_id`, `platform_video_id`, `platform_comment_id`, `text`
`hide`	Hides or shows a comment.	`platform_account_id`, `platform_comment_id`, `hidden`
`like`	Likes or unlikes a comment.	`platform_account_id`, `platform_video_id`, `platform_comment_id`, `action`
`delete`	Deletes your own comment. Use `hide` for other people's comments.	`platform_account_id`, `platform_video_id`, `platform_comment_id`
`sync`	Fetches the latest comments from the platform.	`platform_account_id`, `platform_video_id`

`social_messages`

Can change things

Reads and replies to direct messages on WhatsApp, WhatsApp Business, LINE, TikTok, Facebook and Instagram.

Action	What it does	Main parameters
`channels`	Lists your messaging channels.	`platform_type`, `status`, `filter_unread`
`unread_count`	Unread message counts.	`channel_ids`
`conversations`	Lists conversations in a channel.	`channel_id`, `keyword`, `filter_unread`, `filter_tag`
`tag_counts`	Conversation counts by tag.	`channel_id`
`conversation_detail`	Returns one conversation.	`conversation_id`
`list`	Lists messages in a conversation.	`conversation_id`, `limit`, `keyword`, `mark_as_read`
`send`	Sends a message.	`conversation_id`, `message_type`, `content` or `media`, `reply_to`
`remark`	Sets a note on a conversation.	`conversation_id`, `remark`
`upload`	Gets an upload link for a file to send in a message.	`file_name`, `content_type`

mark_as_read sends a read receipt the contact can see.

`social_analytics`

Reads data

Performance of your own accounts over a period.

Action	What it does	Main parameters
`overview`	Totals across your accounts.	`start_time`, `end_time`, `platform`
`account_trend`	Metrics for each account.	`start_time`, `end_time`, `sort_by`, `platforms`
`top_videos`	Your best videos by a metric.	`metric` (`views`, `likes`, `comments`, `shares`, `gmv`), `start_date`, `end_date`, `limit`
`top_products`	Your best products by a metric.	`metric` (`gmv`, `orders`, `video_count`), `start_date`, `end_date`, `limit`

`social_tools`

Can change things

Publishing helpers, and TikTok Shop product and showcase tools for creators.

Action	What it does	Main parameters
`hashtag`	Suggests hashtags for a keyword.	`keyword`, `language`
`music_search`	Finds trending music.	`keyword`, `country_code`, `date_range`, `genre`
`music_recent`	Music used recently.	`keyword`, `platform_account_id`
`location_search`	Finds a location to tag.	`platform_account_id`, `search_query`
`shop_products`	Products in your TikTok Shop showcase or shop.	`account_id`, `data_source`, `title_keyword`
`affiliate_products`	Affiliate products you can add to your showcase.	`account_id`, `title_keywords`, `category_id`, `commission_rate_range`, `sort_field`
`shop_music_search`	Finds music for TikTok Shop videos.	`platform_account_id`, `keyword`
`showcase_add`	Adds products to your showcase.	`account_id`, `add_type`, `product_ids` or `product_link`
`showcase_remove`	Removes products from your showcase.	`account_id`, `product_ids`
`showcase_top`	Pins products to the top of your showcase.	`account_id`, `product_ids`

`social_seller`

Reads data

Your own TikTok Shop seller data. It needs seller authorization, which is separate from connecting a creator account.

Action	What it does	Main parameters
`daily_report`	A shop's daily report.	`platform_account_id`, `date`
`shops_overview`	Totals across your shops. Data lags 1 to 2 days.	`start_date`, `end_date`, `currency`
`products`	Your product catalog.	`keyword`, `platform_account_id`, `sort_by`, `page`
`product_detail`	Price and stock for each SKU.	`platform_account_id`, `product_id`

Account

`account_info`

Reads data

Shows how much of your 7-day allowance is left, as a percentage, and when it resets, plus your trenz.ai credits balance: the monthly credits used and remaining, and booster credits. It takes no parameters and does not count toward your 7-day allowance. The percentage matches Agent usage remaining on trenz.ai; see Usage limits and credits.