What can you do with this server?

Summary: This is the Fourthwall MCP server (also a CLI) that gives AI agents 86 shop tasks — 49 read operations and 37 effects that each require explicit confirmation — spanning products, orders, collections, webhooks, giveaways, media uploads, and bounded private metadata exports. * Read shop data: list/get products, orders (by id or friendly id), collections and collection products, promotions, webhooks and webhook events, members and membership tiers, mailing list entries, donations, giveaway packages and draws, gift purchases, thank-yous/contributions, reports, DNS status, shop and contact info, and Pro subscription status. * Manage products: create design or digital products (hidden by default), update lifecycle state (PUBLIC/HIDDEN), toggle availability, archive, and read inventory. * Manage media and digital files: request presigned upload URLs, upload exact local bytes, save images to the media library, attach/remove product images, and confirm or remove digital files. * Manage collections: create, update name/description, set the full product list, and toggle availability. * Manage webhooks and streaming: create, get, update, delete webhooks; list/get webhook events; set streaming status to started or ended. * Manage promotions: create and update promotions (limits, requirements, status, applies-to rules). * Manage giveaways, gifting, and fulfillment: create giveaways and giveaway links, finish giveaways/draws, configure and disable giveaway checkout, read/update gifting config, create gifting checkouts, and create order fulfillments with tracking info. * Browse product templates: list, search, and group product templates, including paged variants and category browsing (public endpoints). * Local workflow helpers: list private shop profiles, inspect the native operation contract, preview and submit reviewed 1–20 effect batches with a hash check, export bounded private metadata to a new file, and upload bytes from a private receipt. * Safety guard: every effect needs confirm:true (MCP) or --confirm (CLI); read-only mode exposes only the 49 reads and refuses the rest.

Which integrations are available for this server?

Allows uploading local files to Google Storage through confirmed presigned URL PUT requests, preserving size and content type for Fourthwall upload workflows. Provides tools to manage Fourthwall streaming status for Twitch, including setting streaming to started or ended and retrieving current streaming status.

How do I use Fourthwall MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Fourthwall MCP Server list my recent Fourthwall orders" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Fourthwall MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Summary: This is the Fourthwall MCP server (also a CLI) that gives AI agents 86 shop tasks — 49 read operations and 37 effects that each require explicit confirmation — spanning products, orders, collections, webhooks, giveaways, media uploads, and bounded private metadata exports.

Read shop data: list/get products, orders (by id or friendly id), collections and collection products, promotions, webhooks and webhook events, members and membership tiers, mailing list entries, donations, giveaway packages and draws, gift purchases, thank-yous/contributions, reports, DNS status, shop and contact info, and Pro subscription status.
Manage products: create design or digital products (hidden by default), update lifecycle state (PUBLIC/HIDDEN), toggle availability, archive, and read inventory.
Manage media and digital files: request presigned upload URLs, upload exact local bytes, save images to the media library, attach/remove product images, and confirm or remove digital files.
Manage collections: create, update name/description, set the full product list, and toggle availability.
Manage webhooks and streaming: create, get, update, delete webhooks; list/get webhook events; set streaming status to started or ended.
Manage promotions: create and update promotions (limits, requirements, status, applies-to rules).
Manage giveaways, gifting, and fulfillment: create giveaways and giveaway links, finish giveaways/draws, configure and disable giveaway checkout, read/update gifting config, create gifting checkouts, and create order fulfillments with tracking info.
Browse product templates: list, search, and group product templates, including paged variants and category browsing (public endpoints).
Local workflow helpers: list private shop profiles, inspect the native operation contract, preview and submit reviewed 1–20 effect batches with a hash check, export bounded private metadata to a new file, and upload bytes from a private receipt.
Safety guard: every effect needs confirm:true (MCP) or --confirm (CLI); read-only mode exposes only the 49 reads and refuses the rest.

Fourthwall MCP Server & CLI

npm License YouTube LinkedIn

Fourthwall MCP server and CLI for Codex and AI agents. 86 shared tasks for shop operations, isolated private profiles, reviewed batches, bounded metadata exports and private uploads.

One install, the same tools and guard on both surfaces. Fourthwall's official hosted OAuth MCP already provides broader coverage. This companion adds specific local workflows; read the comparison before choosing.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

fourthwall-cli tools
fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-operation-schema --operation toggle_product_availability --agent
fourthwall-cli <command> --help

Use it directly or let your shell agent call it. Configure the intended private shop first. Every effect requires --confirm; output flags never grant approval.

MCP server, for your AI app

codex mcp add fourthwall -- npx -y @thenavidm/fourthwall-mcp-cli@latest

An MCP client launches the local stdio server and discovers the same tasks. Forward private credential settings through your client runtime. The full client/OS setup is in INSTALL.md.

Which one

Where you work	Surface
Codex or another agent with shell access	CLI, local MCP, or both
A supported local MCP app	Local MCP; desktop extension where supported
A script or CI task	CLI with private secrets supplied by the runtime
A URL-only hosted MCP client	Fourthwall's official hosted MCP is an alternative

Related MCP server: Shopify Store MCP Server

Features

Capability	CLI command	MCP tool
Get a webhook	`fourthwall-cli get-webhook`	`get_webhook`
Update a webhook	`fourthwall-cli update-webhook`	`update_webhook`
Delete a webhook	`fourthwall-cli delete-webhook`	`delete_webhook`
Set streaming status to started	`fourthwall-cli start-streaming`	`start_streaming`
Set streaming status to ended	`fourthwall-cli end-streaming`	`end_streaming`
Get or create a public token	`fourthwall-cli get-public-token`	`get_public_token`
Get a promotion by id	`fourthwall-cli get-promotion`	`get_promotion`
Update a promotion	`fourthwall-cli update-promotion`	`update_promotion`
Update product (offer) lifecycle state	`fourthwall-cli update-product-state`	`update_product_state`
Update product (offer) availability by id	`fourthwall-cli toggle-product-availability`	`toggle_product_availability`
Mark digital download as downloaded	`fourthwall-cli mark-download-complete`	`mark_download_complete`
Finish giveaway	`fourthwall-cli finish-giveaway`	`finish_giveaway`
Create or update giveaway	`fourthwall-cli create-giveaway-checkout`	`create_giveaway_checkout`
Disable giveaway config	`fourthwall-cli disable-giveaway-checkout`	`disable_giveaway_checkout`
Finish draw	`fourthwall-cli finish-giveaway-draw`	`finish_giveaway_draw`
Get gifting config	`fourthwall-cli get-gifting-config`	`get_gifting_config`
Update gifting config	`fourthwall-cli update-gifting-config`	`update_gifting_config`
Update a collection	`fourthwall-cli update-collection`	`update_collection`
Get products in a collection	`fourthwall-cli get-collection-products`	`get_collection_products`
Set collection products	`fourthwall-cli update-collection-products`	`update_collection_products`
Update collection availability	`fourthwall-cli update-collection-availability`	`update_collection_availability`
Get webhooks	`fourthwall-cli list-webhooks`	`list_webhooks`
Create a webhook	`fourthwall-cli create-webhook`	`create_webhook`
Get all promotions	`fourthwall-cli list-promotions`	`list_promotions`
Create a promotion	`fourthwall-cli create-promotion`	`create_promotion`
Get all products (offers)	`fourthwall-cli list-products`	`list_products`
Create a product	`fourthwall-cli create-product`	`create_product`
Attach images to a product	`fourthwall-cli attach-product-images`	`attach_product_images`
Remove images from a product	`fourthwall-cli remove-product-images`	`remove_product_images`
Confirm and link an uploaded digital file	`fourthwall-cli confirm-digital-file-upload`	`confirm_digital_file_upload`
Remove a digital file from a product	`fourthwall-cli remove-digital-file`	`remove_digital_file`
Request a presigned upload URL for a digital file	`fourthwall-cli request-digital-file-upload-url`	`request_digital_file_upload_url`
Request a pre-signed upload URL	`fourthwall-cli request-media-upload-url`	`request_media_upload_url`
List media library images	`fourthwall-cli list-media-images`	`list_media_images`
Save an uploaded image to the media library	`fourthwall-cli save-media-image`	`save_media_image`
Create a new giveaway	`fourthwall-cli create-giveaway`	`create_giveaway`
Create giveaway links	`fourthwall-cli create-giveaway-links`	`create_giveaway_links`
Create a gifting checkout	`fourthwall-cli create-gifting-checkout`	`create_gifting_checkout`
Create a fulfillment for an order	`fourthwall-cli create-fulfillment`	`create_fulfillment`
Validate DNS records	`fourthwall-cli validate-dns`	`validate_dns`
Get all collections	`fourthwall-cli list-collections`	`list_collections`
Create a new collection	`fourthwall-cli create-collection`	`create_collection`
Get webhook events	`fourthwall-cli list-webhook-events`	`list_webhook_events`
Get a webhook event	`fourthwall-cli get-webhook-event`	`get_webhook_event`
Get Thank You by id	`fourthwall-cli get-thank-you`	`get_thank_you`
Get contributions awaiting thank you	`fourthwall-cli list-contributions`	`list_contributions`
Get streaming status	`fourthwall-cli get-streaming-status`	`get_streaming_status`
Get current shop	`fourthwall-cli get-shop`	`get_shop`
Get current shop contact info	`fourthwall-cli get-shop-contact`	`get_shop_contact`
Get sample credit balance	`fourthwall-cli get-sample-balance`	`get_sample_balance`
List available reports	`fourthwall-cli list-reports`	`list_reports`
Get a report	`fourthwall-cli get-report`	`get_report`
Get product (offer) by id	`fourthwall-cli get-product`	`get_product`
Archive a product (offer)	`fourthwall-cli archive-product`	`archive_product`
Get product (offer) inventory by id	`fourthwall-cli get-product-inventory`	`get_product_inventory`
List product templates	`fourthwall-cli list-product-templates`	`list_product_templates`
Get product template details	`fourthwall-cli get-product-template`	`get_product_template`
Search product templates	`fourthwall-cli search-product-templates`	`search_product_templates`
Search product templates by page	`fourthwall-cli search-product-templates-paged`	`search_product_templates_paged`
Search product templates grouped by product family	`fourthwall-cli search-product-templates-grouped`	`search_product_templates_grouped`
Search product templates grouped by product family by page	`fourthwall-cli search-product-templates-grouped-paged`	`search_product_templates_grouped_paged`
List product templates by page	`fourthwall-cli list-product-templates-paged`	`list_product_templates_paged`
Browse product templates by category	`fourthwall-cli list-product-templates-by-category`	`list_product_templates_by_category`
Browse product templates by category by page	`fourthwall-cli list-product-templates-by-category-paged`	`list_product_templates_by_category_paged`
Get Pro subscription status	`fourthwall-cli get-pro-subscription`	`get_pro_subscription`
Get all orders	`fourthwall-cli list-orders`	`list_orders`
Get order by id	`fourthwall-cli get-order`	`get_order`
Get order by friendly id	`fourthwall-cli get-order-by-friendly-id`	`get_order_by_friendly_id`
List membership tiers	`fourthwall-cli list-membership-tiers`	`list_membership_tiers`
List members	`fourthwall-cli list-members`	`list_members`
Get member	`fourthwall-cli get-member`	`get_member`
Get all mailing list entries	`fourthwall-cli list-mailing-list`	`list_mailing_list`
Get all giveaway packages	`fourthwall-cli list-giveaway-packages`	`list_giveaway_packages`
Get giveaway links	`fourthwall-cli get-giveaway-package`	`get_giveaway_package`
Get draw	`fourthwall-cli get-giveaway-draw`	`get_giveaway_draw`
Get gift purchase by id	`fourthwall-cli get-gift-purchase`	`get_gift_purchase`
Get all donations	`fourthwall-cli list-donations`	`list_donations`
Get donation by id	`fourthwall-cli get-donation`	`get_donation`
Get DNS configuration status	`fourthwall-cli get-dns-status`	`get_dns_status`
Get collection by ID or slug	`fourthwall-cli get-collection`	`get_collection`
List private shop profiles	`fourthwall-cli list-accounts`	`list_accounts`
Inspect native contract	`fourthwall-cli get-operation-schema`	`get_operation_schema`
Review ordered shop effects	`fourthwall-cli preview-shop-batch`	`preview_shop_batch`
Execute reviewed shop effects	`fourthwall-cli submit-shop-batch`	`submit_shop_batch`
Export bounded private metadata	`fourthwall-cli export-resources`	`export_resources`
Upload exact bytes from a private receipt	`fourthwall-cli upload-file`	`upload_file`

1. What you can ask it

Ask for a bounded shop task, then review any change before execution:

List the first 25 products in the intended shop and report their state and availability separately.
Read this order and check the native fulfillment contract before preparing a tracking update.
Review these exact product availability changes, then execute only the batch I approve.
Export up to ten pages of order metadata into a new private file and report continuation.
Prepare a hidden digital product from this reviewed native payload. Do not publish it implicitly.
Upload this local image from a private receipt, then show the separate registration step.

These prompts name implemented operations. The terminal animation illustrates a reviewed workflow, rather than an authenticated shop recording.

2. Set up your account

A Fourthwall SUPER ADMIN can create shop API credentials in Settings > For Developers. Follow Fourthwall authentication. Shop Basic credentials grant full shop access; never describe them as a read-only key.

Choose exactly one private source: FOURTHWALL_USERNAME and FOURTHWALL_PASSWORD, an existing FOURTHWALL_ACCESS_TOKEN, or FOURTHWALL_CREDENTIALS_FILE. OAuth permission comes from the provider. This package does not implement consent, exchange or refresh.

The credential file is a JSON object containing either username/password or access_token. It must be an absolute regular non-symlink file, at most 64 KiB, outside repositories. On POSIX the process user must own it and permissions must be owner-only, normally 0600; restrict Windows ACLs separately. Never paste credentials into chat, command transcripts, issues, payloads or project configuration.

fourthwall-cli login
fourthwall-cli list-accounts --agent
fourthwall-cli doctor
fourthwall-cli doctor --network

Login prints instructions. Doctor checks local profiles and policy; the deliberate network option reads the current shop and validates its id. One successful read does not prove every permission, every task or resource ownership. File credentials are cached for the process: restart clients after rotating or revoking them.

Settings

Variable	Default	Meaning
`FOURTHWALL_USERNAME`, `FOURTHWALL_PASSWORD`	None	Shop API Basic credentials
`FOURTHWALL_ACCESS_TOKEN`	None	An existing scoped access token, in place of a username and password
`FOURTHWALL_CREDENTIALS_FILE`	None	Absolute owner-only JSON file holding a username and password or an access token
`FOURTHWALL_ACCOUNTS`	None	Named isolated profiles, each with one credential source
`FOURTHWALL_DEFAULT_ACCOUNT`	First profile	The profile a call uses when it names none
`FOURTHWALL_READ_ONLY`	0	`1` hides and refuses every effect
`FOURTHWALL_ALLOW_DESTRUCTIVE`	1	`0` refuses every effect, even confirmed
`FOURTHWALL_CONFIRM`	`human`	`model` lets confirm:true alone approve over MCP, for an agent with no person to ask
`FOURTHWALL_AUDIT_LOG`	None	File that records every attempted effect, without payloads or credentials
`FOURTHWALL_REQUEST_TIMEOUT_MS`	30000	Each request's deadline; no retries
`FOURTHWALL_MIN_REQUEST_INTERVAL_MS`	1000	Pacing between requests; Fourthwall's tighter limits are paced too
`FOURTHWALL_SURFACE`	`full`	`search` lists three tools that find, describe and run the rest
`FOURTHWALL_TOOL_TIMEOUT_MS`	None	Give up on any tool after this long
`FOURTHWALL_HTTP_PORT`, `FOURTHWALL_HTTP_HOST`, `FOURTHWALL_HTTP_TOKEN`	8787, 127.0.0.1, none	For `--http`; any host but 127.0.0.1 needs the bearer token
`FOURTHWALL_HTTP_ALLOWED_ORIGINS`	None	Comma-separated browser origins allowed to call `--http`; a page from any other site is refused
`FOURTHWALL_DEBUG`	0	`1` prints debug lines on stderr

3. Install

Install Node 22+ in the runtime that launches the server. Use the complete INSTALL.md for Codex, Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and all three desktop OSes.

npm install -g @thenavidm/fourthwall-mcp-cli@latest
fourthwall-cli --version
fourthwall-cli tools
fourthwall-cli schema list-products

After configuring credentials privately, register the local server in Codex:

codex mcp add fourthwall -- npx -y @thenavidm/fourthwall-mcp-cli@latest
codex mcp list

The MCP executable speaks stdio; it is not a hosted URL. The desktop extension is fourthwall-3.0.0.mcpb. Manual installation and updates use the host's supported extension screen. Choose one auth source, leave unused inputs empty and reconnect. GUI installation and authenticated provider tasks require their own validation.

4. Output and exit codes

Both binaries use the same schemas, handlers, validation and confirmation guard. --json prints JSON, --compact prints a single line, and --agent gives compact JSON with no prompts and never confirms a write. fourthwall-cli which <words> finds the command for a task. --select projects requested output fields. Errors go to stderr. --yes suppresses interactive presentation; it never replaces --confirm.

Exit	Meaning
0	Successful command
1	Unexpected error
2	Usage, invalid arguments, a refused effect, an unknown command or a hidden write
3	Not found
4	Provider authentication/permission failure
5	Other API/network failure
7	Provider quota/rate limit
10	Missing/invalid local configuration

fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-shop --account intended-shop --json
fourthwall-cli schema create-promotion

Tool path/query snake_case arguments become dash flags. Native body fields retain their exact camelCase flags, such as --fileName and --contentType; inspect --help instead of guessing a spelling. Objects and arrays use JSON. Use a private --payload-file for larger native bodies. Do not mix payload, payload-file and flat body fields.

5. Which surface and what each costs

Use CLI for scripts, shell agents and selected tasks. Use MCP where your app discovers tools and calls them directly. Both surfaces reach the same 86 tasks and enforce the same approval policy.

Surface	Context and task considerations
CLI	Command help and results enter context on demand; agent shell access is needed
MCP	Tool schemas may be loaded or deferred depending on the client; result content still costs context
Read-only MCP	Exposes 49 reads and excludes 37 effects locally
Official hosted MCP	Broad OAuth tooling with its own schemas, previews and confirmation flow

Measured on 2026-10-05 against 2.0.1, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

Cost	2.0.1	3.0.0
Claude Code, every tool loaded, every message	43,696	39,922
Claude Code's default, tool search, every message	1,610	1,608
`SKILL.md`, read once	518	662
Codex over the CLI, one task, median of five	130,541	108,648
Codex over MCP, the same task, median of five	77,214	77,915

The task was "find the command that creates a promotion, and the flags it requires". Every tool loaded costs less because parts that several tools repeated are written once. Over the CLI, every 3.0.0 run asked which, whose answer carries the command's help, where three 2.0.1 runs tried schema without a command and then read the whole command list; the schema both versions read next is half the size on 3.0.0. Over MCP, Codex now prints create_promotion's payload with every promotion type and its fields, where it printed 2.0.1's as unknown, about 700 tokens more. SKILL.md costs 144 more because it says how approval works over MCP and how which finds a command, and lists every exit code.

Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.

6. Tools

49 reads and 37 confirmed effects. All 86 tasks follow below; nested native JSON fields come from the selected reviewed schema.

get_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a webhook

CLI: fourthwall-cli get-webhook. Policy: read.

Native: GET /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`webhook_configuration_id`	string (minLength=1, maxLength=256)	Required	Native webhookConfigurationId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

update_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Update a webhook

CLI: fourthwall-cli update-webhook. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`webhook_configuration_id`	string (minLength=1, maxLength=256)	Required	Native webhookConfigurationId
`url`	string	Optional	Native field
`allowedTypes`	array	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field	Type or constraint	Requirement	Meaning
url	string	Required	Native field
allowedTypes	array	Required	Native field

delete_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Delete a webhook

CLI: fourthwall-cli delete-webhook. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`webhook_configuration_id`	string (minLength=1, maxLength=256)	Required	Native webhookConfigurationId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

start_streaming

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to started for specified services

CLI: fourthwall-cli start-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/start. Current source.

Argument	Type or constraint	Requirement	Meaning
`services`	array	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
services	array	Required	Native field
services.[].variant 1	value	Choose one	Native oneOf
services.[].variant1.type	string	Required	Native field
services.[].variant1.broadcasterId	string	Optional	Native field
services.[].variant1.broadcasterLogin	string	Optional	Native field
services.[].variant1.thumbnailUrl	string	Optional	Native field

end_streaming

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to ended for specified services

CLI: fourthwall-cli end-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/end. Current source.

Argument	Type or constraint	Requirement	Meaning
`services`	array	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
services	array	Required	Native field

get_public_token

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns an existing public token for the shop, or creates a new one if none exists

CLI: fourthwall-cli get-public-token. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/public-token. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`output_file`	string (minLength=1)	Required	Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

get_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a promotion by id

CLI: fourthwall-cli get-promotion. Policy: read.

Native: GET /open-api/v1.0/promotions/{promotionId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`promotion_id`	string (minLength=1, maxLength=256)	Required	Native promotionId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

update_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates an existing promotion's configuration. Only provided fields are updated; omitted fields remain unchanged. Status changes (activate/deactivate) are part of the same update call.

CLI: fourthwall-cli update-promotion. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/promotions/{promotionId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`promotion_id`	string (minLength=1, maxLength=256)	Required	Native promotionId
`limits`	object	Optional	Native field
`requirements`	object	Optional	Native field
`appliesTo`	union	Optional	Native field
`status`	LIVE, ENDED	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
limits	object	Optional	Native field
limits.maximumUse	integer (format=int32)	Optional	Native field
limits.oneUsePerCustomer	boolean	Required	Native field
requirements	object	Optional	Native field
requirements.minimumOrderValue	object	Optional	Native field
requirements.minimumOrderValue.value	number (minimum=0)	Required	Native field
requirements.minimumOrderValue.currency	string	Required	Native field
appliesTo	union	Optional	Native field
appliesTo.variant 1	value	Choose one	Native oneOf
appliesTo.variant1.type	string	Optional	Native field
appliesTo.variant 2	value	Choose one	Native oneOf
appliesTo.variant2.productIds	array	Optional	Native field
appliesTo.variant2.oncePerOrder	boolean	Optional	Native field
status	LIVE, ENDED	Optional	Native field

update_product_state

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Transitions the product between PUBLIC and HIDDEN. Use DELETE /products/{productId} to archive — ARCHIVED is not reachable here. The sold-out (available) flag is preserved; flip it via PUT /products/{productId}/availability. Idempotent: no-op if the product is already in the requested state.

CLI: fourthwall-cli update-product-state. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/state. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`state`	PUBLIC, HIDDEN	Optional	Target lifecycle state. `PUBLIC` makes the product visible on the storefront; `HIDDEN` keeps it unlisted. The sold-out (`available`) flag is preserved across the transition — use `PUT /products/{productId}/availability` to flip it.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
state	PUBLIC, HIDDEN	Required	Target lifecycle state. `PUBLIC` makes the product visible on the storefront; `HIDDEN` keeps it unlisted. The sold-out (`available`) flag is preserved across the transition — use `PUT /products/{productId}/availability` to flip it.

toggle_product_availability

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates a product (offer) availability

CLI: fourthwall-cli toggle-product-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/availability. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`available`	boolean	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
available	boolean	Required	Native field

mark_download_complete

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Marks digital download as downloaded. If no downloads exist for a digital order and defaultFileUrl is provided in the request body, creates a download with that URL and marks it as downloaded.

CLI: fourthwall-cli mark-download-complete. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/order/{orderId}/downloaded. Current source.

Argument	Type or constraint	Requirement	Meaning
`order_id`	string (minLength=1, maxLength=256)	Required	Native orderId
`defaultFileUrl`	string	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
defaultFileUrl	string	Optional	Native field

finish_giveaway

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish giveaway and select winners

CLI: fourthwall-cli finish-giveaway. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaways/{id}/finish/twitch. Current source.

Argument	Type or constraint	Requirement	Meaning
`id`	string (minLength=1, maxLength=256)	Required	Native id
`participants`	array	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
participants	array	Required	Native field
participants.[].userId	string	Required	Native field
participants.[].userName	string	Required	Native field

create_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway or updates existing one

CLI: fourthwall-cli create-giveaway-checkout. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaway-checkout. Current source.

Argument	Type or constraint	Requirement	Meaning
`heading`	string	Optional	Native field
`description`	string	Optional	Native field
`iconUrl`	string	Optional	Native field
`buttonText`	string	Optional	Native field
`disabled`	boolean	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
heading	string	Required	Native field
description	string	Required	Native field
iconUrl	string	Required	Native field
buttonText	string	Required	Native field
disabled	boolean	Optional	Native field

disable_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

disables a giveaway config

CLI: fourthwall-cli disable-giveaway-checkout. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/giveaways/giveaway-checkout. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

finish_giveaway_draw

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish draw and select winners

CLI: fourthwall-cli finish-giveaway-draw. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/draw/{id}/finish. Current source.

Argument	Type or constraint	Requirement	Meaning
`id`	string (minLength=1, maxLength=256)	Required	Native id
`participants`	array	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
participants	array	Required	Native field
participants.[].variant 1	value	Choose one	Native oneOf
participants.[].variant1.service	string	Required	Native field
participants.[].variant1.userId	string	Optional	Native field
participants.[].variant1.userName	string	Optional	Native field

get_gifting_config

Returns the calling shop's saved gifting rules. Returns a default-shaped config when none is persisted yet.

CLI: fourthwall-cli get-gifting-config. Policy: read.

Native: GET /open-api/v1.0/gifting/config. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

update_gifting_config

Writes the four creator-controlled gifting rule fields. Validation (duration 20-180s, valid shipping/products) and the one-platform-per-shop mutex are enforced server-side. Upserts: a first-ever PUT materializes the config row.

CLI: fourthwall-cli update-gifting-config. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/config. Current source.

Argument	Type or constraint	Requirement	Meaning
`enabled`	boolean	Optional	Master flag. Off pauses purchasability without losing the rest.
`entryTimeLimitSeconds`	integer (format=int32)	Optional	Entry time limit in seconds. Validated 20-180.
`shipping`	union	Optional	Native field
`products`	union	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
enabled	boolean	Required	Master flag. Off pauses purchasability without losing the rest.
entryTimeLimitSeconds	integer (format=int32)	Required	Entry time limit in seconds. Validated 20-180.
shipping	union	Required	Native field
shipping.variant 1	value	Choose one	Native oneOf
shipping.variant1.type	string	Required	Native field
shipping.variant1.type	ALL_CREATOR	Optional	Native field
shipping.variant 2	value	Choose one	Native oneOf
shipping.variant2.type	string	Required	Native field
shipping.variant2.type	ALL_WINNER	Optional	Native field
shipping.variant 3	value	Choose one	Native oneOf
shipping.variant3.type	string	Required	Native field
shipping.variant3.max	number (format=double)	Optional	Native field
shipping.variant3.type	MAX_CREATOR	Optional	Native field
products	union	Required	Native field
products.variant 1	value	Choose one	Native oneOf
products.variant1.type	string	Required	Native field
products.variant1.type	ALL	Optional	Native field
products.variant 2	value	Choose one	Native oneOf
products.variant2.type	string	Required	Native field
products.variant2.offerIds	array	Optional	Native field
products.variant2.type	EXCLUDED	Optional	Native field
products.variant 3	value	Choose one	Native oneOf
products.variant3.type	string	Required	Native field
products.variant3.offerIds	array	Optional	Native field
products.variant3.type	SELECTED	Optional	Native field

update_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates collection name, description, and/or product list

CLI: fourthwall-cli update-collection. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`collection_id`	string (minLength=1, maxLength=256)	Required	Native collectionId
`name`	string	Optional	Native field
`description`	string	Optional	Native field
`offerIds`	array	Optional	List of product IDs to set in the collection
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
name	string	Optional	Native field
description	string	Optional	Native field
offerIds	array	Optional	List of product IDs to set in the collection

get_collection_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated products in a collection with optional status filtering. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli get-collection-products. Policy: read.

Native: GET /open-api/v1.0/collections/{collectionId}/products. Current source.

Argument	Type or constraint	Requirement	Meaning
`collection_id`	string (minLength=1, maxLength=256)	Required	Native collectionId
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`status`	PUBLIC, AVAILABLE, SOLD_OUT, HIDDEN, ARCHIVED	Optional	Filter by product status
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

update_collection_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets the full list of product IDs in the collection

CLI: fourthwall-cli update-collection-products. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/products. Current source.

Argument	Type or constraint	Requirement	Meaning
`collection_id`	string (minLength=1, maxLength=256)	Required	Native collectionId
`offerIds`	array	Optional	Full list of product IDs to set in the collection
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
offerIds	array	Required	Full list of product IDs to set in the collection

update_collection_availability

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Toggle collection availability (available/unavailable)

CLI: fourthwall-cli update-collection-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/availability. Current source.

Argument	Type or constraint	Requirement	Meaning
`collection_id`	string (minLength=1, maxLength=256)	Required	Native collectionId
`available`	boolean	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
available	boolean	Required	Native field

list_webhooks

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhooks

CLI: fourthwall-cli list-webhooks. Policy: read.

Native: GET /open-api/v1.0/webhooks. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

create_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Create a webhook

CLI: fourthwall-cli create-webhook. Policy: explicit confirmation.

Native: POST /open-api/v1.0/webhooks. Current source.

Argument	Type or constraint	Requirement	Meaning
`url`	string	Optional	Native field
`allowedTypes`	array	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
url	string	Required	Native field
allowedTypes	array	Required	Native field

list_promotions

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all promotions. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-promotions. Policy: read.

Native: GET /open-api/v1.0/promotions. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`codes`	array	Optional	Filter by promotion code(s)
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

create_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a promotion

CLI: fourthwall-cli create-promotion. Policy: explicit confirmation.

Native: POST /open-api/v1.0/promotions. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	union	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
variant 1	value	Choose one	Native oneOf
variant1.type	string	Required	Native field
variant1.codes	array	Optional	Native field
variant1.discount	union	Optional	Native field
variant1.discount.variant 1	value	Choose one	Native oneOf
variant1.discount.variant1.type	string	Required	Native field
variant1.discount.variant1.percentage	number	Optional	Native field
variant1.discount.variant1.type	PERCENTAGE	Optional	Native field
variant1.requirements	object	Optional	Native field
variant1.requirements.newMembersOnly	boolean	Required	Native field
variant1.subscriptionType	union	Optional	Native field
variant1.subscriptionType.variant 1	value	Choose one	Native oneOf
variant1.subscriptionType.variant1.type	string	Required	Native field
variant1.subscriptionType.variant1.type	ALL	Optional	Native field
variant1.subscriptionType.variant 2	value	Choose one	Native oneOf
variant1.subscriptionType.variant2.type	string	Required	Native field
variant1.subscriptionType.variant2.type	ANNUAL	Optional	Native field
variant1.subscriptionType.variant 3	value	Choose one	Native oneOf
variant1.subscriptionType.variant3.type	string	Required	Native field
variant1.subscriptionType.variant3.type	MONTHLY	Optional	Native field
variant1.tiers	union	Optional	Native field
variant1.tiers.variant 1	value	Choose one	Native oneOf
variant1.tiers.variant1.type	string	Required	Native field
variant1.tiers.variant1.type	ALL	Optional	Native field
variant1.tiers.variant 2	value	Choose one	Native oneOf
variant1.tiers.variant2.type	string	Required	Native field
variant1.tiers.variant2.ids	array	Optional	Native field
variant1.tiers.variant2.type	SELECTED	Optional	Native field
variant1.type	MEMBERSHIPS_MULTI	Optional	Native field
variant 2	value	Choose one	Native oneOf
variant2.type	string	Required	Native field
variant2.code	string	Optional	Native field
variant2.discount	union	Optional	Native field
variant2.discount.variant 1	value	Choose one	Native oneOf
variant2.discount.variant1.type	string	Required	Native field
variant2.discount.variant1.percentage	number	Optional	Native field
variant2.discount.variant1.type	PERCENTAGE	Optional	Native field
variant2.requirements	object	Optional	Native field
variant2.requirements.newMembersOnly	boolean	Required	Native field
variant2.subscriptionType	union	Optional	Native field
variant2.subscriptionType.variant 1	value	Choose one	Native oneOf
variant2.subscriptionType.variant1.type	string	Required	Native field
variant2.subscriptionType.variant1.type	ALL	Optional	Native field
variant2.subscriptionType.variant 2	value	Choose one	Native oneOf
variant2.subscriptionType.variant2.type	string	Required	Native field
variant2.subscriptionType.variant2.type	ANNUAL	Optional	Native field
variant2.subscriptionType.variant 3	value	Choose one	Native oneOf
variant2.subscriptionType.variant3.type	string	Required	Native field
variant2.subscriptionType.variant3.type	MONTHLY	Optional	Native field
variant2.tiers	union	Optional	Native field
variant2.tiers.variant 1	value	Choose one	Native oneOf
variant2.tiers.variant1.type	string	Required	Native field
variant2.tiers.variant1.type	ALL	Optional	Native field
variant2.tiers.variant 2	value	Choose one	Native oneOf
variant2.tiers.variant2.type	string	Required	Native field
variant2.tiers.variant2.ids	array	Optional	Native field
variant2.tiers.variant2.type	SELECTED	Optional	Native field
variant2.type	MEMBERSHIPS_SINGLE	Optional	Native field
variant 3	value	Choose one	Native oneOf
variant3.type	string	Required	Native field
variant3.codes	array	Optional	Native field
variant3.discount	union	Optional	Native field
variant3.discount.variant 1	value	Choose one	Native oneOf
variant3.discount.variant1.type	string	Required	Native field
variant3.discount.variant1.money	object	Optional	Native field
variant3.discount.variant1.money.value	number (minimum=0)	Required	Native field
variant3.discount.variant1.money.currency	string	Required	Native field
variant3.discount.variant1.freeShipping	boolean	Optional	Native field
variant3.discount.variant1.type	FLAT_RATE	Optional	Native field
variant3.discount.variant 2	value	Choose one	Native oneOf
variant3.discount.variant2.type	string	Required	Native field
variant3.discount.variant2.type	FREE_SHIPPING	Optional	Native field
variant3.discount.variant 3	value	Choose one	Native oneOf
variant3.discount.variant3.type	string	Required	Native field
variant3.discount.variant3.percentage	number	Optional	Native field
variant3.discount.variant3.shipping	Excluded, Included, FreeLowestOnly, Free	Optional	Native field
variant3.discount.variant3.type	PERCENTAGE	Optional	Native field
variant3.requirements	object	Optional	Native field
variant3.requirements.minimumOrderValue	object	Optional	Native field
variant3.requirements.minimumOrderValue.value	number (minimum=0)	Required	Native field
variant3.requirements.minimumOrderValue.currency	string	Required	Native field
variant3.appliesToProducts	object	Optional	Native field
variant3.appliesToProducts.productIds	array	Required	Native field
variant3.appliesToProducts.oncePerOrder	boolean	Optional	Native field
variant3.limits	object	Optional	Native field
variant3.limits.maximumUse	integer (format=int32)	Optional	Native field
variant3.limits.oneUsePerCustomer	boolean	Required	Native field
variant3.type	SHOP_MULTI	Optional	Native field
variant 4	value	Choose one	Native oneOf
variant4.type	string	Required	Native field
variant4.code	string	Optional	Native field
variant4.discount	union	Optional	Native field
variant4.discount.variant 1	value	Choose one	Native oneOf
variant4.discount.variant1.type	string	Required	Native field
variant4.discount.variant1.money	object	Optional	Native field
variant4.discount.variant1.money.value	number (minimum=0)	Required	Native field
variant4.discount.variant1.money.currency	string	Required	Native field
variant4.discount.variant1.freeShipping	boolean	Optional	Native field
variant4.discount.variant1.type	FLAT_RATE	Optional	Native field
variant4.discount.variant 2	value	Choose one	Native oneOf
variant4.discount.variant2.type	string	Required	Native field
variant4.discount.variant2.type	FREE_SHIPPING	Optional	Native field
variant4.discount.variant 3	value	Choose one	Native oneOf
variant4.discount.variant3.type	string	Required	Native field
variant4.discount.variant3.percentage	number	Optional	Native field
variant4.discount.variant3.shipping	Excluded, Included, FreeLowestOnly, Free	Optional	Native field
variant4.discount.variant3.type	PERCENTAGE	Optional	Native field
variant4.requirements	object	Optional	Native field
variant4.requirements.minimumOrderValue	object	Optional	Native field
variant4.requirements.minimumOrderValue.value	number (minimum=0)	Required	Native field
variant4.requirements.minimumOrderValue.currency	string	Required	Native field
variant4.appliesToProducts	object	Optional	Native field
variant4.appliesToProducts.productIds	array	Required	Native field
variant4.appliesToProducts.oncePerOrder	boolean	Optional	Native field
variant4.limits	object	Optional	Native field
variant4.limits.maximumUse	integer (format=int32)	Optional	Native field
variant4.limits.oneUsePerCustomer	boolean	Required	Native field
variant4.type	SHOP_SINGLE	Optional	Native field

list_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all products with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-products. Policy: read.

Native: GET /open-api/v1.0/products. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`search`	string	Optional	Native search
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

create_product

Rate limit: 5 requests / minute per shop. See Rate limiting.

Creates a product from a design or a digital product.

CLI: fourthwall-cli create-product. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
type	string	Required	Native field
variant 1	value	Choose one	Native oneOf
variant1.type	string	Required	Native field
variant1.productTemplateId	string	Optional	Id of the product template to render the design onto, from `GET /open-api/v1.0/product-templates`.
variant1.regions	array	Optional	Design regions to place on the product. Each region references a registered media image by id (register it via `POST /open-api/v1.0/media/images` and pass the returned id as `imageId`).
variant1.regions.[].region	string	Required	Name of the product region to place the image on, e.g. `front` or `back`.
variant1.regions.[].imageId	string	Required	Id of a registered media-library image to render on the region. Register the image first via `POST /open-api/v1.0/media/images` and pass the returned id here.
variant1.regions.[].placementId	string	Optional	Placement to target when `placementStrategy` is `PLACEMENT_ID`. Required for that strategy and ignored by the others.
variant1.regions.[].placementStrategy	AUTO, FILL_ALL, FULL_REGION, PLACEMENT_ID	Optional	How the image is placed on the region. Defaults to `AUTO` when omitted, and takes precedence over `placementId`/`fillAllPlacements`. - `AUTO` — let the renderer decide using the product's automation defaults (its preferred placement, or fill-all for products like mugs/stickers). - `FILL_ALL` — apply the image to every placement in the region. - `FULL_REGION` — render the image across the full region, skipping the preferred placement. - `PLACEMENT_ID` — target the single placement named by `placementId` (required for this strategy).
variant1.colors	array	Optional	Colors to render. Defaults to all available product colors when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied colors are available.
variant1.sizes	array	Optional	Sizes to include. Defaults to all available product sizes when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied sizes are available. When both colors and sizes are supplied, the request is also rejected with 400 if no requested color/size combination is an available variant.
variant1.name	string	Optional	Product name
variant1.description	string	Optional	Product description
variant1.profitMargin	number	Optional	Profit margin in USD applied on top of the base cost.
variant1.publishOnCreate	boolean	Optional	Publish the product immediately on creation. Defaults to false (product stays hidden).
variant1.type	design	Optional	Native field
variant 2	value	Choose one	Native oneOf
variant2.type	string	Required	Native field
variant2.name	string	Optional	Product name
variant2.description	string	Optional	Product description
variant2.price	number	Optional	Price set by the creator, in USD.
variant2.publishOnCreate	boolean	Optional	Publish the product immediately on creation. Defaults to false (product stays hidden).
variant2.type	digital	Optional	Native field

attach_product_images

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Attaches images to a product. Images should be uploaded first via the media upload endpoint.

CLI: fourthwall-cli attach-product-images. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products/{productId}/images. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`images`	array	Optional	List of images to attach
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
images	array	Required	List of images to attach
images.[].url	string	Required	Image URL
images.[].width	integer (format=int32)	Required	Image width in pixels
images.[].height	integer (format=int32)	Required	Image height in pixels

remove_product_images

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes specified images from a product by their URLs.

CLI: fourthwall-cli remove-product-images. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/products/{productId}/images. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`imageUrls`	array	Optional	List of image URLs to remove
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
imageUrls	array	Required	List of image URLs to remove

confirm_digital_file_upload

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

After uploading a file to the presigned URL, call this endpoint to link the file to the product. The file must exist in storage before calling this endpoint.

CLI: fourthwall-cli confirm-digital-file-upload. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products/{productId}/digital-files. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`fileUrl`	string	Optional	The file URL returned from the upload-url endpoint
`fileName`	string	Optional	Display name for the file
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
fileUrl	string	Required	The file URL returned from the upload-url endpoint
fileName	string	Required	Display name for the file

remove_digital_file

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes a digital file from the product by its file URL.

CLI: fourthwall-cli remove-digital-file. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/products/{productId}/digital-files. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`fileUrl`	string	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
fileUrl	string	Required	Native field

request_digital_file_upload_url

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a presigned URL to upload a digital file to. After receiving the response, PUT the file bytes directly to the uploadUrl, then call the confirm endpoint to link the file to the product.

CLI: fourthwall-cli request-digital-file-upload-url. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products/{productId}/digital-files/upload-url. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`fileName`	string	Optional	Name of the file
`contentType`	string	Optional	MIME type of the file
`size`	integer (format=int64)	Optional	Size of the file in bytes. Must match the `x-goog-content-length-range` header sent when uploading the bytes to `uploadUrl`.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`output_file`	string (minLength=1)	Required	Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

Native JSON field	Type or constraint	Requirement	Meaning
fileName	string	Required	Name of the file
contentType	string	Required	MIME type of the file
size	integer (format=int64)	Required	Size of the file in bytes. Must match the `x-goog-content-length-range` header sent when uploading the bytes to `uploadUrl`.

request_media_upload_url

Rate limit: 20 requests / minute per shop. See Rate limiting.

Returns a pre-signed upload URL for uploading a new image. After receiving the response, PUT the image bytes directly to the uploadUrl.

CLI: fourthwall-cli request-media-upload-url. Policy: explicit confirmation.

Native: POST /open-api/v1.0/media/upload-url. Current source.

Argument	Type or constraint	Requirement	Meaning
`fileName`	string	Optional	Name of the file
`contentType`	string	Optional	MIME type of the file
`size`	integer (format=int64)	Optional	Size of the file in bytes. Must match the `x-goog-content-length-range` header sent when uploading the bytes to `uploadUrl`.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`output_file`	string (minLength=1)	Required	Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

Native JSON field	Type or constraint	Requirement	Meaning
fileName	string	Required	Name of the file
contentType	string	Required	MIME type of the file
size	integer (format=int64)	Required	Size of the file in bytes. Must match the `x-goog-content-length-range` header sent when uploading the bytes to `uploadUrl`.

list_media_images

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Retrieves all images from the shop's media library

CLI: fourthwall-cli list-media-images. Policy: read.

Native: GET /open-api/v1.0/media/images. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

save_media_image

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Persists an uploaded image in the media library after the client has PUT it to the signed URL

CLI: fourthwall-cli save-media-image. Policy: explicit confirmation.

Native: POST /open-api/v1.0/media/images. Current source.

Argument	Type or constraint	Requirement	Meaning
`fileUrl`	string	Optional	Native field
`width`	integer (format=int32)	Optional	Native field
`height`	integer (format=int32)	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
fileUrl	string	Required	Native field
width	integer (format=int32)	Required	Native field
height	integer (format=int32)	Required	Native field

create_giveaway

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway

CLI: fourthwall-cli create-giveaway. Policy: explicit confirmation.

Native: POST /open-api/v1.0/giveaways/giveaways. Current source.

Argument	Type or constraint	Requirement	Meaning
`offerId`	string (format=uuid)	Optional	Native field
`quantity`	integer (format=int32)	Optional	Native field
`username`	string	Optional	Native field
`message`	string	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
offerId	string (format=uuid)	Required	Native field
quantity	integer (format=int32)	Required	Native field
username	string	Optional	Native field
message	string	Optional	Native field

create_giveaway_links

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new package with specified number of giveaway links

CLI: fourthwall-cli create-giveaway-links. Policy: explicit confirmation.

Native: POST /open-api/v1.0/giveaway-links. Current source.

Argument	Type or constraint	Requirement	Meaning
`productId`	string (format=uuid)	Optional	Native field
`number`	integer (format=int32)	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
productId	string (format=uuid)	Required	Native field
number	integer (format=int32)	Required	Native field

create_gifting_checkout

Creates a paid checkout for gifting a product to live chat

CLI: fourthwall-cli create-gifting-checkout. Policy: explicit confirmation.

Native: POST /open-api/v1.0/gifting/checkout. Current source.

Argument	Type or constraint	Requirement	Meaning
`offerId`	string	Optional	The product offer to gift to live chat.
`quantity`	integer (minimum=1, maximum=10000, format=int32)	Optional	How many gifts to purchase.
`currency`	USD, EUR, CAD, GBP, AUD, NZD, SEK, NOK, DKK, PLN, INR, JPY, MYR, SGD, MXN, BRL, CHF	Optional	Display currency for the checkout. Defaults to the shop's currency.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
offerId	string	Required	The product offer to gift to live chat.
quantity	integer (minimum=1, maximum=10000, format=int32)	Required	How many gifts to purchase.
currency	USD, EUR, CAD, GBP, AUD, NZD, SEK, NOK, DKK, PLN, INR, JPY, MYR, SGD, MXN, BRL, CHF	Optional	Display currency for the checkout. Defaults to the shop's currency.

create_fulfillment

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a fulfillment with a shipment tracker for provided order items. When trackers change their state, order.status will change to IN_PRODUCTION, PARTIALLY_IN_PRODUCTION, PARTIALLY_SHIPPED, SHIPPED depending on the shipping tracker info. Order updated webhooks will be triggered.

CLI: fourthwall-cli create-fulfillment. Policy: explicit confirmation.

Native: POST /open-api/v1.0/fulfillments. Current source.

Argument	Type or constraint	Requirement	Meaning
`orderId`	string (format=uuid)	Optional	Native field
`items`	array (minItems=1)	Optional	Native field
`shippingLabel`	object	Optional	Native field
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
orderId	string (format=uuid)	Required	Native field
items	array (minItems=1)	Required	Native field
items.[].variantId	string (format=uuid)	Required	Native field
items.[].quantity	integer (minimum=1, format=int32)	Required	Native field
shippingLabel	object	Required	Native field
shippingLabel.trackingNumber	string (minLength=1)	Required	Native field
shippingLabel.trackingCompany	string (minLength=1)	Required	Native field

validate_dns

Rate limit: 20 requests / minute per shop. See Rate limiting.

Triggers a live DNS validation by checking all configured records against actual DNS servers and updates their verification status

CLI: fourthwall-cli validate-dns. Policy: explicit confirmation.

Native: POST /open-api/v1.0/dns/validate. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

list_collections

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all collections with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-collections. Policy: read.

Native: GET /open-api/v1.0/collections. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`search`	string	Optional	Native search
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

create_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new collection with name, description, and optional product list

CLI: fourthwall-cli create-collection. Policy: explicit confirmation.

Native: POST /open-api/v1.0/collections. Current source.

Argument	Type or constraint	Requirement	Meaning
`name`	string	Optional	Native field
`description`	string	Optional	Native field
`offerIds`	array	Optional	List of product IDs to include in the collection
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`payload`	object	Optional	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	string (minLength=1)	Optional	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native JSON field	Type or constraint	Requirement	Meaning
name	string	Required	Native field
description	string	Required	Native field
offerIds	array	Required	List of product IDs to include in the collection

list_webhook_events

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhook events with pagination and optional filtering by one or more webhook types (repeat or comma-separate the type param). The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-webhook-events. Policy: read.

Native: GET /open-api/v1.0/webhook-events. Current source.

Argument	Type or constraint	Requirement	Meaning
`type`	array	Optional	Native type
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=50)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_webhook_event

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a single webhook event by ID

CLI: fourthwall-cli get-webhook-event. Policy: read.

Native: GET /open-api/v1.0/webhook-events/{webhookEventId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`webhook_event_id`	string (minLength=1, maxLength=256)	Required	Native webhookEventId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_thank_you

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get Thank You details

CLI: fourthwall-cli get-thank-you. Policy: read.

Native: GET /open-api/v1.0/thank-yous/{thankYouId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`thank_you_id`	string (minLength=1, maxLength=256)	Required	Native thankYouId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_contributions

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated list of orders, donations, and other contributions that can be thanked. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-contributions. Policy: read.

Native: GET /open-api/v1.0/thank-you-contributions. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=50)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`state`	array	Optional	Native state
`search`	string	Optional	Native search
`min_value`	number (format=double)	Optional	Native minValue
`contains_msg`	boolean	Optional	Native containsMsg
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_streaming_status

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns streaming status for all services

CLI: fourthwall-cli get-streaming-status. Policy: read.

Native: GET /open-api/v1.0/streaming. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_shop

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop

CLI: fourthwall-cli get-shop. Policy: read.

Native: GET /open-api/v1.0/shops/current. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_shop_contact

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop contact info

CLI: fourthwall-cli get-shop-contact. Policy: read.

Native: GET /open-api/v1.0/shops/current/contact-info. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_sample_balance

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current sample credit balance for the shop

CLI: fourthwall-cli get-sample-balance. Policy: read.

Native: GET /open-api/v1.0/samples/balance. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_reports

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the list of available report IDs with metadata including name, columns, and supported precisions

CLI: fourthwall-cli list-reports. Policy: read.

Native: GET /open-api/v1.0/reports. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_report

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Fetches a specific analytics report for a date range

CLI: fourthwall-cli get-report. Policy: read.

Native: GET /open-api/v1.0/reports/{reportId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`report_id`	string (minLength=1, maxLength=256)	Required	Native reportId
`from`	string (format=date-time)	Required	Native from
`to`	string (format=date-time)	Required	Native to
`aggregation_timezone`	string	Required	Timezone in ISO-8601 format (e.g., Europe/Warsaw for Warsaw)
`aggregation_precision`	hour, day, week, month, quarter, year	Required	Native aggregationPrecision
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_product

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product by id

CLI: fourthwall-cli get-product. Policy: read.

Native: GET /open-api/v1.0/products/{productId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

archive_product

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Soft-archives the product — sets it to Archived. Terminal at this surface: once archived, the product cannot be returned to PUBLIC/HIDDEN through the open-api (restoration stays admin-only). Idempotent: re-DELETE on an already-archived product also returns 204.

CLI: fourthwall-cli archive-product. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/products/{productId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

get_product_inventory

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product (offer) inventory by id

CLI: fourthwall-cli get-product-inventory. Policy: read.

Native: GET /open-api/v1.0/products/{productId}/inventory. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Native productId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates

List available product templates. Returns 25 results. To paginate, use the /page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli list-product-templates. Policy: read.

Native: GET /open-api/v1.0/product-templates. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_product_template

        Get detailed information about a specific product template.

        This endpoint is public and does not require authentication.
        Returns full product details including variants, customizable areas,
        size guide, and images.

CLI: fourthwall-cli get-product-template. Policy: read.

Native: GET /open-api/v1.0/product-templates/{productId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`product_id`	string (minLength=1, maxLength=256)	Required	Product template ID
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates

Search product templates by name, brand, description, sizes, categories, colors, or production method. Returns 25 results. To paginate, use the /search/{query}/page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli search-product-templates. Policy: read.

Native: GET /open-api/v1.0/product-templates/search/{query}. Current source.

Argument	Type or constraint	Requirement	Meaning
`query`	string (minLength=1, maxLength=256)	Required	Search query (e.g., 'hoodie', 'black%20t-shirt')
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates_paged

Search product templates with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli search-product-templates-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/search/{query}/page/{page}. Current source.

Argument	Type or constraint	Requirement	Meaning
`query`	string (minLength=1, maxLength=256)	Required	Search query (e.g., 'hoodie', 'black%20t-shirt')
`page`	integer (minimum=1, format=int32)	Required	Page number (1-indexed)
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates_grouped

Search product templates and group results by product family (libraryId). Products sharing the same physical item but with different production methods (e.g. DTG, Embroidery, DTFX) are collapsed into a single result with a variants list. Returns 25 grouped results. To paginate, use the /search-grouped/{query}/page/{N} variant (1-indexed). Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli search-product-templates-grouped. Policy: read.

Native: GET /open-api/v1.0/product-templates/search-grouped/{query}. Current source.

Argument	Type or constraint	Requirement	Meaning
`query`	string (minLength=1, maxLength=256)	Required	Search query (e.g., 'hoodie', 'black%20t-shirt')
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates_grouped_paged

Search product templates grouped by product family with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli search-product-templates-grouped-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/search-grouped/{query}/page/{page}. Current source.

Argument	Type or constraint	Requirement	Meaning
`query`	string (minLength=1, maxLength=256)	Required	Search query (e.g., 'hoodie', 'black%20t-shirt')
`page`	integer (minimum=1, format=int32)	Required	Page number (1-indexed)
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates_paged

List available product templates with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli list-product-templates-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/page/{page}. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=1, format=int32)	Required	Page number (1-indexed)
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates_by_category

Browse product templates filtered by category. Category matches by prefix (e.g., 'Apparel' matches 'Apparel/T-Shirts'). Returns 25 results. To paginate, use the /category/{category}/page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli list-product-templates-by-category. Policy: read.

Native: GET /open-api/v1.0/product-templates/category/{category}. Current source.

Argument	Type or constraint	Requirement	Meaning
`category`	Apparel, Accessories, Home & Living	Required	Category path. Top-level: Apparel, Accessories, Home & Living. Subcategory paths like 'Apparel/T-Shirts' are also valid.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates_by_category_paged

Browse product templates by category with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli list-product-templates-by-category-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/category/{category}/page/{page}. Current source.

Argument	Type or constraint	Requirement	Meaning
`category`	Apparel, Accessories, Home & Living	Required	Category path. Top-level: Apparel, Accessories, Home & Living. Subcategory paths like 'Apparel/T-Shirts' are also valid.
`page`	integer (minimum=1, format=int32)	Required	Page number (1-indexed)
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_pro_subscription

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current Fourthwall Pro platform subscription status, plan, and usage against plan limits

CLI: fourthwall-cli get-pro-subscription. Policy: read.

Native: GET /open-api/v1.0/pro-subscription. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_orders

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all orders with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-orders. Policy: read.

Native: GET /open-api/v1.0/order. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`email`	string	Optional	Native email
`created_at_gt`	string (format=date-time)	Optional	Native createdAt[gt]
`created_at_lt`	string (format=date-time)	Optional	Native createdAt[lt]
`updated_at_gt`	string (format=date-time)	Optional	Native updatedAt[gt]
`updated_at_lt`	string (format=date-time)	Optional	Native updatedAt[lt]
`status`	array	Optional	Native status
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_order

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by id

CLI: fourthwall-cli get-order. Policy: read.

Native: GET /open-api/v1.0/order/{orderId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`order_id`	string (minLength=1, maxLength=256)	Required	Native orderId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_order_by_friendly_id

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by friendly id

CLI: fourthwall-cli get-order-by-friendly-id. Policy: read.

Native: GET /open-api/v1.0/order/by-friendly-id/{friendlyId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`friendly_id`	string (minLength=1, maxLength=256)	Required	Native friendlyId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_membership_tiers

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all tiers for the current shop

CLI: fourthwall-cli list-membership-tiers. Policy: read.

Native: GET /open-api/v1.0/memberships/tiers. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_members

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all members for the current shop. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-members. Policy: read.

Native: GET /open-api/v1.0/memberships/members. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_member

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Gets a member by id

CLI: fourthwall-cli get-member. Policy: read.

Native: GET /open-api/v1.0/memberships/members/{id}. Current source.

Argument	Type or constraint	Requirement	Meaning
`id`	string (minLength=1, maxLength=256)	Required	Native id
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_mailing_list

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all mailing list entries. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-mailing-list. Policy: read.

Native: GET /open-api/v1.0/mailing-list-entries. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_giveaway_packages

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all packages with giveaway links

CLI: fourthwall-cli list-giveaway-packages. Policy: read.

Native: GET /open-api/v1.0/giveaway-links/packages. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_giveaway_package

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all giveaway links for packageId

CLI: fourthwall-cli get-giveaway-package. Policy: read.

Native: GET /open-api/v1.0/giveaway-links/packages/{packageId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`package_id`	string (minLength=1, maxLength=256)	Required	Native packageId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_giveaway_draw

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get draw details

CLI: fourthwall-cli get-giveaway-draw. Policy: read.

Native: GET /open-api/v1.0/gifting/draw/{id}. Current source.

Argument	Type or constraint	Requirement	Meaning
`id`	string (minLength=1, maxLength=256)	Required	Native id
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_gift_purchase

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns gift purchase details by id

CLI: fourthwall-cli get-gift-purchase. Policy: read.

Native: GET /open-api/v1.0/gift-purchase/{giftPurchaseId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`gift_purchase_id`	string (minLength=1, maxLength=256)	Required	Native giftPurchaseId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_donations

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all donations with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-donations. Policy: read.

Native: GET /open-api/v1.0/donations. Current source.

Argument	Type or constraint	Requirement	Meaning
`page`	integer (minimum=0, format=int32, default=0)	Optional	Native page
`size`	integer (minimum=1, maximum=100, format=int32, default=20)	Optional	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_donation

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns donation by id

CLI: fourthwall-cli get-donation. Policy: read.

Native: GET /open-api/v1.0/donations/{donationId}. Current source.

Argument	Type or constraint	Requirement	Meaning
`donation_id`	string (minLength=1, maxLength=256)	Required	Native donationId
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_dns_status

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the cached DNS configuration and record status for the shop's custom domain

CLI: fourthwall-cli get-dns-status. Policy: read.

Native: GET /open-api/v1.0/dns. Current source.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

get_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a collection by its ID or slug

CLI: fourthwall-cli get-collection. Policy: read.

Native: GET /open-api/v1.0/collections/{collectionIdOrSlug}. Current source.

Argument	Type or constraint	Requirement	Meaning
`collection_id_or_slug`	string (minLength=1, maxLength=256)	Required	Native collectionIdOrSlug
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

list_accounts

Local labels/default/auth source availability only. No credential values, paths, provider identity or network.

CLI: fourthwall-cli list-accounts. Policy: read.

Argument

Type or constraint

Requirement

Meaning

get_operation_schema

Local reviewed native method/path/query/body/scopes/rate limit and pinned schema provenance. No provider access or authority proof.

CLI: fourthwall-cli get-operation-schema. Policy: read.

Argument	Type or constraint	Requirement	Meaning
`operation`	get_webhook, update_webhook, delete_webhook, start_streaming, end_streaming, get_public_token, get_promotion, update_promotion, update_product_state, toggle_product_availability, mark_download_complete, finish_giveaway, create_giveaway_checkout, disable_giveaway_checkout, finish_giveaway_draw, get_gifting_config, update_gifting_config, update_collection, get_collection_products, update_collection_products, update_collection_availability, list_webhooks, create_webhook, list_promotions, create_promotion, list_products, create_product, attach_product_images, remove_product_images, confirm_digital_file_upload, remove_digital_file, request_digital_file_upload_url, request_media_upload_url, list_media_images, save_media_image, create_giveaway, create_giveaway_links, create_gifting_checkout, create_fulfillment, validate_dns, list_collections, create_collection, list_webhook_events, get_webhook_event, get_thank_you, list_contributions, get_streaming_status, get_shop, get_shop_contact, get_sample_balance, list_reports, get_report, get_product, archive_product, get_product_inventory, list_product_templates, get_product_template, search_product_templates, search_product_templates_paged, search_product_templates_grouped, search_product_templates_grouped_paged, list_product_templates_paged, list_product_templates_by_category, list_product_templates_by_category_paged, get_pro_subscription, list_orders, get_order, get_order_by_friendly_id, list_membership_tiers, list_members, get_member, list_mailing_list, list_giveaway_packages, get_giveaway_package, get_giveaway_draw, get_gift_purchase, list_donations, get_donation, get_dns_status, get_collection	Required	Native field

preview_shop_batch

Validate every exact request and hash order/profile label/schema locally. No native request, credential loading, ownership check or provider preview.

CLI: fourthwall-cli preview-shop-batch. Policy: read.

Argument	Type or constraint	Requirement	Meaning
`tasks`	array (minItems=1, maxItems=20)	Required	One to twenty exact ordered native effects. No signed receipts or mutable payload files. Cannot override account/confirm/output settings.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.

submit_shop_batch

Confirmed ordered effects; all validated/hash checked before first request. Stop on first failure with known and unattempted receipts; no retry, rollback or implicit continuation.

CLI: fourthwall-cli submit-shop-batch. Policy: explicit confirmation.

Argument	Type or constraint	Requirement	Meaning
`tasks`	array (minItems=1, maxItems=20)	Required	One to twenty exact ordered native effects. No signed receipts or mutable payload files. Cannot override account/confirm/output settings.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`review_sha256`	string	Required	Native field

export_resources

Confirmed native page/size/results export into a new exclusive0600 file with page/item/5MiB budgets and explicit page/offset continuation. No links followed, binary downloads or atomic-backup guarantee.

CLI: fourthwall-cli export-resources. Policy: explicit confirmation.

Argument	Type or constraint	Requirement	Meaning
`operation`	get_collection_products, list_promotions, list_products, list_collections, list_webhook_events, list_contributions, list_orders, list_members, list_mailing_list, list_donations	Required	Native field
`arguments`	object	Optional	Current list query/path arguments; cannot override profile/policy/output.
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`start_offset`	integer (minimum=0, maximum=99)	Optional	Native field
`max_pages`	integer (minimum=1, maximum=100)	Optional	Native field
`max_items`	integer (minimum=1, maximum=10000)	Optional	Native field
`output_file`	string (minLength=1)	Required	Native field

upload_file

Explicitly confirmed Google Storage PUT using a selected private upload receipt and a bounded local regular file. Exact size/Content-Type and x-goog-content-length-range are preserved. No Fourthwall credentials or redirects, no automatic registration/publishing.

CLI: fourthwall-cli upload-file. Policy: explicit confirmation.

Argument	Type or constraint	Requirement	Meaning
`account`	string	Optional	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`receipt_file`	string (minLength=1)	Required	Native field
`input_file`	string (minLength=1)	Required	Native field

7. Writing safely

Every one of the 37 effects requires confirm:true in MCP or --confirm in the CLI. This includes new checkouts, public-token PUT, uploads and local export file writes. Read-only hides and directly refuses effects. FOURTHWALL_ALLOW_DESTRUCTIVE=0 refuses them even when confirmed. Local guard approval is separate from provider authorization and customer consent.

Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm:true counts. FOURTHWALL_CONFIRM=model makes confirm:true enough everywhere, for an agent with no person to ask.

Read the intended record and inspect get_operation_schema before writing. Validate IDs, quantities, callback events and the exact profile. Product creation defaults to hidden. Availability is not lifecycle state: available:false and state:HIDDEN are separate native changes.

No effect retries automatically. A timeout, malformed receipt or partial batch can mean an unknown outcome. Inspect native state before deliberately repeating. The default pacing is 1,000 ms per request; tighter documented operation buckets are respected locally. Other processes share provider quotas.

8. Products media and fulfillment

The pinned contract uses /open-api/v1.0 and current native typed bodies. Product creation supports selected design/digital variants, not every custom production workflow. Digital price is a nonnegative USD amount; publishOnCreate defaults false.

fourthwall-cli create-product --payload-file /absolute/private/digital-product.json --account intended-shop --confirm --agent
fourthwall-cli toggle-product-availability --product-id REVIEWED_PRODUCT_ID --available false --confirm --agent
fourthwall-cli update-product-state --product-id REVIEWED_PRODUCT_ID --state HIDDEN --confirm --agent

The digital tutorial describes admin publishing while the current state endpoint documents PUBLIC/HIDDEN. Check actual authorization and storefront visibility before claiming a live publication outcome. These examples are placeholders, not successful shop receipts.

Media workflow: request_media_upload_url saves a signed receipt to a NEW private file; upload_file sends exact local bytes; save_media_image registers the uploaded reference separately. Digital-file workflow uses request_digital_file_upload_url, upload_file and confirm_digital_file_upload. Use private payload files for fileUrl; never paste signed receipts into agent context.

fourthwall-cli request-media-upload-url --fileName reviewed.png --contentType image/png --size 4096 --output-file /absolute/private/upload-receipt.json --account intended-shop --confirm --agent
fourthwall-cli upload-file --receipt-file /absolute/private/upload-receipt.json --input-file /absolute/private/reviewed.png --account intended-shop --confirm --agent
fourthwall-cli save-media-image --payload-file /absolute/private/register-image.json --account intended-shop --confirm --agent

Replace 4096 with the exact file byte count. The helper's local cap is 64 MiB, not a Fourthwall plan entitlement. HTTPS Google Storage signed hosts only, no redirects, exact Content-Type and x-goog-content-length-range; no Fourthwall Authorization header reaches storage. Upload acknowledgement is not registration, storefront publication or access proof. Receipts bind a profile label and metadata, not cryptographic ownership.

Fulfillment requires native orderId, nonempty items with variantId/quantity, and shippingLabel with trackingCompany/trackingNumber. Giveaway links require productId and number, not the old quantity wrapper. Promotions retain four native variants and their nested discount shapes. Streaming services are native typed objects, not strings. Inspect schema before submitting any of these.

9. Several accounts and reviewed batches

FOURTHWALL_ACCOUNTS is a private JSON array of unique name plus one username/password, access_token or credentials_file source. Named profiles never inherit globals. FOURTHWALL_DEFAULT_ACCOUNT selects an exact default; --account selects another label. Discovery reports labels and source availability only, never secret values or paths.

Preview validates 1–20 ordered native effects locally before any provider call. Signed-output operations and mutable payload files are excluded. Every nested argument is validated; account/confirm/output overrides are forbidden. Preview returns reviewSha256 and providerValidated:false.

fourthwall-cli preview-shop-batch --tasks '{"tool":"toggle_product_availability","arguments":{"product_id":"REVIEWED_PRODUCT_ID","available":false}}' --account intended-shop --agent
fourthwall-cli submit-shop-batch --tasks '{"tool":"toggle_product_availability","arguments":{"product_id":"REVIEWED_PRODUCT_ID","available":false}}' --review-sha256 REVIEWED_64_CHARACTER_HASH --account intended-shop --confirm --agent

The repeatable JSON flag becomes the tasks array. Use the exact hash from your local preview. It binds prepared requests, task order, profile label and selected schema, not credentials, provider state, expiry or single-use execution. Re-review after credential/state changes. Execution stops on the first failure and reports known results and unattempted indices. No transaction or rollback is promised.

10. Pagination and private exports

Query pagination uses native zero-based page/size, with size capped locally at 100. Product-template path pagination is one-based. The old cursor/limit wrappers are obsolete. Native date filter names and repeated status values are preserved by the request encoder; inspect the actual list schema.

export_resources supports the ten selected lists whose current schema exposes results/page/size/totalPages. It validates counters, limits pages/items/bytes, and returns continuation with a page and start_offset when needed. Default budgets are ten pages and 1,000 items; maxima are 100 pages, 10,000 items and 5 MiB.

fourthwall-cli export-resources --operation list_orders --arguments '{"page":0,"size":100}' --max-pages 10 --max-items 1000 --output-file /absolute/private/orders.json --account intended-shop --confirm --agent

A new file is reserved exclusively before fetching; existing files and symlinks are not overwritten. POSIX output mode is 0600; Windows ACLs require separate restriction. Errors remove the partial new file. Exports redact known credentials/signed URLs, but other customer metadata remains private. This is bounded filtered metadata, not an atomic backup, binary download or stable snapshot while data changes.

11. How it works

Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition, and both call the same handlers. Ajv validates discovered input schemas and current native body variants. A shared guard applies confirmation and read-only policy before effects. Native method/path allowlists prevent arbitrary provider requests; query arrays and date names retain their native representation.

Six local helpers add private profile discovery, contract inspection, reviewed batches, bounded exports and exact byte uploads. No vendor or community runtime is copied. Official schema provenance and the 39-name migration mapping are checked by scripts.

npm ci
npm run typecheck
npm run build
npm test
npm run check:counts
npm run check:discovery
npm run sync:api -- --check
npm run build:mcpb

CI runs macOS, Windows and Linux on Node 22/24 plus desktop packaging. These checks prove local contracts, policy, transports and artifacts; authenticated provider outcomes, desktop GUI installation and matched Codex tokens remain separate. See RELEASE-CHECKLIST.md.

12. Your data

Credentials live in private process settings or owner-private files; there is no hosted service or telemetry. Provider API requests go only to api.fourthwall.com. Storage uploads are separately scoped to the documented Google Storage HTTPS hosts and carry no provider credentials.

Raw signed upload receipts and generated public tokens are intentionally written only to a requested new private output_file. Known credentials, sensitive token/file fields and signed credential URLs are redacted from ordinary output and errors. Customer names, emails, order contents and other legitimate native metadata are not automatically anonymized.

Treat provider content and URLs as untrusted data. Optional best-effort audit logs contain static guard decisions, not payloads or credentials; they are not financial ledgers. Keep exports and receipts private. Uninstalling does not revoke provider credentials or reverse effects. Revoke or rotate in Fourthwall and restart dependent runtimes.

13. Official and community comparison

Fourthwall's official MCP already exists. It provides hosted OAuth, broad shop tooling, confirmations and documented previews, with 123 documented tools at review. This package is a selected local companion, with 80 native operations and six workflows. Neither count proves greater coverage or efficiency.

Requirement	This companion	Existing tooling
Authentication	Private shop Basic pair or existing OAuth bearer/file	Official hosted OAuth with shop selection
Coverage	Selected reviewed Platform API routes	Official broader shop, brand, merch and analytics tools
Terminal	Dedicated task CLI over the exact same MCP handlers	Generic MCP terminal clients also exist
Local approvals	Mandatory per-call approval and direct read-only refusal on both surfaces	Official confirmations and previews already exist
Repeated work	Exact local ordered batch review and failure receipts	No claim of transaction or state locking
Export	Bounded private native metadata export with resume offset	Not an atomic backup or binary download
Upload	Private signed receipts and explicit bounded byte helper	Native upload services remain the authority
Cost	No measured task-token saving yet	Equivalent completed tasks must be measured

The reviewed generic wong2/mcp-cli source at 7d12b464 already supports remote interactive OAuth. Its noninteractive JSON call path in that snapshot uses stdio; HTTP noninteractive equivalence was not verified. A bounded GitHub community search found no additional dedicated Fourthwall MCP repository, which is not proof none exists. See COMPARISON.md for review evidence and exclusions.

14. Versions and migration

Component	Version or evidence
Package and desktop	3.0.0
Slipway	0.1.20
MCP TypeScript SDK, through Slipway	2.3.0
Runtime	Node >=22
Native API	Current Platform v1.0 schema checked 2026-10-04
Selected operations	80 of 95 native operations, 80 distinct method/path routes
Legacy	39 actual tool names preserved; breaking argument refresh
Task/token, provider and GUI outcomes	Separate acceptance work; not inferred from local tests

3.0.0 moves both surfaces onto Slipway and keeps every tool's name and arguments; CHANGELOG.md lists what changed for scripts. In 2.0, old cursor/limit fields became page/size, availability uses available, fulfillment uses items/shippingLabel, giveaway uses productId/number, webhooks require url and allowedTypes, promotions use native oneOf variants, and streaming services use typed objects. Effects now require explicit approval. Token/upload receipts need new private output_file. Product creation stays hidden by default. Use schema/help before migrating scripts.

The current official source SHA-256 is 77de1061d5c9273927fd3cf4cac1375c4bb684bed4cc4c0f22252ea6b0e203fe. Provenance, excluded operations and sanitized snapshot checksum ship in src/tools/provenance.json. CHANGELOG.md records the full refresh; private legacy history remains separate.

15. Risks

Full-access Basic credentials make careful profile and permission selection necessary. Local approval cannot prove ownership, customer consent, fulfillment delivery or storefront state. There are no automatic retries, rollbacks, refunds or cleanup workflows beyond the explicitly documented tools.

Fixed local bounds are 1 MiB request/body file, 5 MiB API response/export and 64 MiB byte upload. Timeout defaults to 30 seconds and local pacing to one second, with tighter native buckets. These are conservative process controls, not global quota guarantees. Sandbox verification uses fixtures and makes no real shop changes.

16. Troubleshooting

Symptom	Check
Missing configuration	Choose one complete private auth source; confirm the launching runtime inherits it
API 401/403	Check revoked credentials, OAuth scopes, shop permissions and intended resource
Unknown profile	Use exact list_accounts labels; named profiles never inherit globals
429	Respect shared provider quotas; do not repeatedly retry a possibly completed effect
Invalid arguments	Run schema/--help; old wrappers and guessed body fields are rejected
Upload byte mismatch	Request a new receipt for the exact file size; preserve required headers
Existing output file	Pick a new private path; outputs never overwrite
Empty or malformed receipt	Inspect native state before deliberately repeating
GUI launcher cannot find npx	Check the client's PATH or use absolute node/package paths
Hidden write absent	Read-only intentionally removes it and refuses direct calls

Report sanitized reproducible details through GitHub issues, or use private security reporting. Never attach credentials, upload URLs or customer exports.

17. FAQ

A local program that lets an MCP app call selected Fourthwall Platform API operations. It exposes 86 shared tasks, including six local workflows, through one implementation also used by the CLI.

The same tasks as terminal commands. Tool names use underscores in MCP and dashes in commands, such as list_products and fourthwall-cli list-products. Shell agents and scripts can use JSON output without configuring an MCP connection.

Yes. Fourthwall offers a hosted OAuth MCP at https://mcp.fourthwall.com with broader shop, brand, merchandising and analytics coverage. Its documentation listed 123 tools when reviewed on October 4, 2026; that is a documentation count, not authenticated discovery.

Choose it for hosted OAuth, broad dashboard coverage and its own native previews and confirmations. Choose this companion when you need a dedicated shared task CLI, exact local request reviews, isolated profile selection or bounded private metadata exports.

No. Generic MCP terminal clients also exist, and the official MCP already confirms changes. The useful additions here are specific local workflows and consistent per-call policy across CLI and MCP. There is no universal superiority or total-coverage claim.

Codex, Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed and Gemini CLI can launch a local stdio server where supported. Other stdio clients can use the same executable. URL-only hosted connectors cannot connect directly to this local package.

The npm package and manifest require Node 22 or newer. The desktop bundle includes production JavaScript dependencies; a compatible host must provide the required runtime. macOS, Windows and Linux are declared; CI and actual GUI installation are separate checks.

A Fourthwall SUPER ADMIN can create shop API credentials in Settings > For Developers. Configure the complete private username/password pair, an existing OAuth access token, or a private credential JSON file. Basic credentials grant full shop access.

No. fourthwall-cli login prints the private setup instructions. It does not create credentials, open browser consent, exchange tokens or refresh an existing OAuth token. Use the official provider flow separately if you need OAuth.

Yes. FOURTHWALL_ACCOUNTS contains independently configured named profiles, and --account selects one exact label. Named profiles never inherit global credentials. Labels and review hashes do not establish shop ownership or lock credential contents.

FOURTHWALL_READ_ONLY=1 exposes only the 49 read operations and directly refuses the 37 hidden effects, even if confirm is supplied. This is a local runtime policy; it does not reduce permissions on Fourthwall credentials or govern another client.

All 37 provider and local effects need confirm:true in MCP or --confirm in the CLI. That includes product changes, checkout creation, token generation, upload URL requests, byte uploads, reviewed batches and exports. --yes and --agent do not grant permission.

Creation defaults publishOnCreate to false, keeping the product hidden. Publishing is a separate deliberate choice. The current state endpoint documents PUBLIC/HIDDEN, while the digital-product tutorial also describes admin publishing; authorization and live visibility must be checked in the intended shop.

No. Preview validates every request locally and hashes exact requests, order, profile label and pinned contract. Submit verifies that hash and stops on the first failure. There is no rollback, state lock, expiry or single-use promise; failed effect outcomes can be unknown.

No. Exports save selected native page/size/results metadata with explicit page, item and byte budgets and continuation. They are not atomic snapshots, binary downloads or a guarantee of completeness while shop data changes.

Request a signed upload receipt into a new private file, then explicitly upload matching local bytes to the documented Google Storage host. Registration or attachment is separate. The upload sends no Fourthwall Authorization header and never automatically publishes a product.

Credentials remain in private environment settings or owner-only regular files outside repositories. Signed upload URLs and public tokens are saved only to requested new private files. Ordinary output redacts known credentials and signed URLs; other shop/customer fields remain private data.

Download fourthwall-3.0.0.mcpb from GitHub Releases and install it through a supported Claude Desktop Extensions screen. Choose one credential source and leave others empty. The release includes production dependencies and no credentials. Archive/protocol checks do not prove GUI installation in every client build.

The software is free under AGPL-3.0. Fourthwall service fees, plans and usage still apply. In Claude Code the CLI costs nothing until it is used, plus about 660 tokens for SKILL.md once, where the server costs about 1,610 tokens a message with tool search and 39,900 with every tool loaded. In Codex, finding the command that creates a promotion and its flags took a median of 108,648 input tokens over the CLI and 77,915 over MCP. Section 5 has how each was measured.

All 39 actual legacy tool names remain, but native arguments and pagination were corrected. The new package adds a CLI, desktop bundle, 80 selected native operations, six local workflows, explicit effect approval and stronger private output handling. Version 2.0.0 is a breaking contract refresh; old private history is preserved separately.

Questions

Use issues with sanitized reproduction steps. Security reports belong in the private advisory form.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

Dependencies

Slipway, which brings the MCP TypeScript SDK, and Ajv with ajv-formats power the shared runtime. TypeScript, Vitest and the desktop packer are build/test tools. Dependency licenses are retained in the bundle; see THIRD_PARTY_NOTICES.md.

License

AGPL-3.0. Preserve the license and applicable source obligations. Fourthwall is a separate provider; this community companion is not its official MCP.

Available Tools

86 tools

archive_productArchive a product (offer)B

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Native productId

TDQS

B3.3/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states "Idempotent: re-DELETE on an already-archived product also returns 204," while the annotations declare idempotentHint=false; repeated identical calls demonstrably have no further effect on the resource, so the two directly conflict. Everything else it discloses (rate limit, terminal state, 204 status) is genuinely useful, but the explicit contradiction of an annotation drives this to a 1 per the rubric.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no filler, but the rate-limit boilerplate is placed ahead of the actual purpose statement, so the operational meaning is not fully front-loaded. Still appropriately sized for a destructive, irreversible operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive terminal action with no output schema and full annotation coverage, the description supplies the key missing facts: irreversibility through the open-api, admin-only restoration, the 204 response, and rate limits. It says nothing about side effects on collections, checkouts, or media tied to the product, which an agent would reasonably want to know.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (account, confirm, product_id each documented in-schema), so the baseline is 3. The description adds no parameter-level meaning beyond the schema — nothing about how product_id is resolved or when confirm must be set.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Soft-archives the product — sets it to `Archived`"), which is far more precise than the title alone. The terminal-state note implicitly separates it from state-mutating siblings like update_product_state, but no sibling is named, so the differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong usage context: the action is terminal at this surface and restoration is admin-only, which tells the agent this is a last-resort, confirm-first operation. It never names an alternative tool or states an explicit when-not to call it, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

attach_product_imagesAttach images to a productA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Attaches images to a product. Images should be uploaded first via the media upload endpoint.

ParametersJSON Schema

Name	Required	Description
`images`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`product_id`	Yes	Native productId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds context the annotations do not carry: an explicit rate limit (100 requests / 10 seconds per shop) and the media-upload prerequisite. It still does not say whether attaching replaces or appends to existing images.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and free of filler; two sentences plus the rate-limit note. The rate limit is front-loaded ahead of the purpose statement, which is slightly off-optimal ordering but still compact and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, nested-object, destructive write with no output schema, the description leaves notable gaps: it does not explain the confirm guard, the payload vs payload_file vs native-flag exclusivity, or the effect on existing product images. It covers enough to call the tool but not enough to call it safely without reading the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents product_id, account, confirm, payload and payload_file. The description only indirectly touches the images parameter via the upload prerequisite and adds no format or semantics for the remaining parameters, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Attaches images to a product'), which is clearly distinct from siblings like remove_product_images, save_media_image and upload_file. It does not explicitly name a sibling or scope the operation, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete prerequisite workflow: images must first be uploaded via the media upload endpoint. That is actionable ordering guidance, though it names no explicit alternative tool or when-not condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

confirm_digital_file_uploadConfirm and link an uploaded digital fileA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

After uploading a file to the presigned URL, call this endpoint to link the file to the product. The file must exist in storage before calling this endpoint.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`fileUrl`	No	The file URL returned from the upload-url endpoint
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`fileName`	No	Display name for the file
`product_id`	Yes	Native productId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds genuinely useful context beyond them with the 100 req/10 sec per shop rate limit and the storage-prerequisite constraint, but it never explains what destruction/re-linking means or what happens on a repeat call despite idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus a rate-limit note; the operational constraint and purpose are front-loaded with zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation with a nested payload, full schema coverage and annotations carrying the safety profile, the description covers the workflow position and rate limit adequately. It is slightly thin on post-call behavior and duplicate/retry semantics, but an output schema is absent and nothing essential to invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter (account, confirm, fileUrl, payload, fileName, product_id, payload_file) is already documented in the schema. The description adds no parameter-level meaning such as required combinations or how confirm relates to payload, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'link the file to the product' via a confirmation endpoint, which is distinct from the sibling request_digital_file_upload_url and upload_file. However, it never explicitly names which sibling this is not, so the differentiation is inferred from the workflow rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear situational guidance: call this 'after uploading a file to the presigned URL' and only when 'the file must exist in storage'. That is a usable precondition, but it offers no exclusion or alternative path (e.g., what to do if the upload failed or the URL expired).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_collectionCreate a new collectionB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new collection with name, description, and optional product list

ParametersJSON Schema

Name	Required	Description
`name`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`offerIds`	No	List of product IDs to include in the collection
`description`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the write/risk profile is covered structurally. The description adds genuinely useful non-annotation context in the rate limit (100 requests / 10 seconds per shop) with a link, but says nothing about the destructive implication, required shop scope, or the safety-gated 'confirm' flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the operational constraint is front-loaded in italics and the capability statement follows. No filler, though the 'optional product list' phrasing is slightly imprecise given the nested payload's required offerIds.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, nested-object mutation with no output schema and zero required top-level parameters, the description is thin: it omits which parameter form to choose (payload vs. flat fields vs. payload_file), the confirm-gating behavior, and any statement of what a successful call returns. The rate limit is the one piece of depth it provides.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 71%, and the schema itself documents account, confirm, payload, payload_file, and offerIds. The description's 'name, description, and optional product list' roughly restates the schema rather than adding format, ordering, or nesting rules — notably it does not clarify that the nested payload form requires offerIds while the top-level form does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource — 'Creates a new collection' — and enumerates the fields it accepts (name, description, product list). An agent can distinguish it from update_collection and update_collection_products, but the description never names those siblings explicitly, so differentiation relies on the reader's inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to create versus update an existing collection, no prerequisites, and no explanation of the unusual 'confirm' parameter or when it should be set. The only contextual note is a rate limit, which is a constraint rather than usage routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_fulfillmentCreate a fulfillment for an orderA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

ParametersJSON Schema

Name	Required	Description
`items`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`orderId`	No
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`shippingLabel`	No

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds real value beyond them: a concrete rate limit (100 requests / 10 seconds per shop) and the side effects on order.status (IN_PRODUCTION, PARTIALLY_SHIPPED, SHIPPED, etc.) plus triggered order-updated webhooks. It still does not say what specifically is destructive or whether the call is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, no filler, and the rate-limit constraint plus the state-transition behavior are stated directly. Front-loading the rate limit ahead of the tool's own purpose is slightly awkward ordering, but the text is efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description covers rate limits and side effects reasonably well. However it omits authentication/permission requirements and gives no parameter-level guidance for a 7-parameter, nested-object payload, leaving notable gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description names no parameters at all — items, orderId, shippingLabel, account, confirm, payload and payload_file are left entirely to the schema. With 7 parameters and only 57% schema description coverage, the description does not compensate for the undocumented remainder.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a fulfillment with a shipment tracker for provided order items'), which is unambiguous and distinguishable from every sibling tool, none of which touch fulfillments. The scope of what is created (fulfillment + tracker for given items) is stated up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions or exclusions. The description only explains downstream effects (order.status transitions), not when an agent should reach for it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_gifting_checkoutCreate a gifting checkoutC

Destructive

Creates a paid checkout for gifting a product to live chat

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`offerId`	No	The product offer to gift to live chat.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`currency`	No
`quantity`	No	How many gifts to purchase.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, openWorldHint=true, idempotentHint=false, readOnlyHint=false, so safety profile is covered. However, the description does not disclose that this is a paid, irreversible, open-world operation, that confirmation is required, or any rate limits/authentication needs. 'Paid checkout' hints at payment, but the destructive and non-idempotent nature is left entirely to annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence that front-loads the verb and scope. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, open-world, non-idempotent payment operation with 7 parameters and nested payload, the description is far too thin. It lacks any behavioral warnings, usage context, or distinction from the nearly identical giveaway checkout siblings. Critical information an agent needs is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 86%, so the schema already documents most parameters (offerId, quantity, currency, account, confirm, payload, payload_file). The description adds nothing about parameter meaning. With high schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Creates a paid checkout for gifting a product to live chat.' Distinguishes from sibling 'create_giveaway_checkout' by specifying 'gifting' and 'live chat', though it doesn't explicitly name the alternative. An agent can tell what it does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this vs. create_giveaway_checkout, disable_giveaway_checkout, or other checkout tools. The description does not state prerequisites or exclusions. The only usage hint comes from the schema's 'confirm' parameter, not the description itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_giveawayCreate a new giveawayC

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`message`	No
`offerId`	No
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`quantity`	No
`username`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

C2.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral fact not in the annotations (the 100 requests / 10 seconds per shop rate limit), but says nothing about the confirm semantics, what the creation returns, or reversibility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The rate-limit note is front-loaded and the text is short with no filler. However, the brevity is under-specification rather than true conciseness: for a destructive, multi-parameter mutation the single sentence does not earn its place as complete guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with a nested request body, 50% parameter coverage, no output schema, and a large family of related siblings, this description is too thin. Annotations cover safety, but the agent still lacks the field requirements and sibling routing it needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50% across 8 parameters with a nested payload object, and the description contributes no parameter meaning at all. With required=[] and a nullable payload/message/offerId/quantity set, the agent gets no guidance on which fields are actually needed to create a giveaway.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Creates a new giveaway'), so an agent knows exactly the operation performed. It does not, however, differentiate this from the many sibling giveaway tools (finish_giveaway, create_giveaway_checkout, create_giveaway_links, get_giveaway_draw), leaving the agent to infer which giveaway-creation path applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance, no prerequisites, and no mention of the sibling alternatives such as create_giveaway_checkout or finish_giveaway. The agent must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_giveaway_checkoutCreate or update giveawayC

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway or updates existing one

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`heading`	No
`iconUrl`	No
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`disabled`	No
`buttonText`	No
`description`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

C2.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description does add a genuine non-annotation detail — the 100 requests / 10 seconds per shop rate limit — but says nothing about permissions, reversibility, or what an upsert overwrites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the rate limit front-loaded, so there is little waste. However, the brevity comes at the cost of under-specification rather than tightness — the single purpose sentence is doing too little work for a 9-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, open-world upsert with 9 parameters, a nested request body, zero required fields and no output schema, the description leaves major gaps: no body-construction guidance, no confirm semantics, and no disambiguation from the create_giveaway sibling. It is not complete enough to call the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 44% across 9 parameters including a nested payload object, and the description adds zero parameter meaning. It does not explain the payload vs payload_file vs individual body flags exclusivity, nor the semantics of 'confirm' beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a verb and resource ('Creates a new giveaway or updates existing one'), but the tool is create_giveaway_checkout while the text says 'giveaway', and the sibling list contains a separate create_giveaway. It never distinguishes the checkout variant from the plain giveaway tool, so the purpose is only partially clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of prerequisites or the confirm gate, and no routing to alternatives such as create_giveaway or disable_giveaway_checkout. The agent must infer usage entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_giveaway_linksCreate giveaway linksB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new package with specified number of giveaway links

ParametersJSON Schema

Name	Required	Description
`number`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`productId`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, non-idempotent, and openWorld, so the safety profile is covered. The description contributes a real extra fact (100 requests / 10 seconds per shop, with a link to rate limiting), but says nothing about what is consumed/destroyed, required permissions, or whether links can be revoked.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, easy to scan. Leading with the rate-limit note before the purpose statement slightly de-emphasizes the actual function, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with 6 optional params, a nested payload object, and no output schema, the description omits auth/permission requirements, what a 'package' and its links are, and what happens to the earlier parameters when payload or payload_file is supplied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the schema already explains account, confirm, payload, and payload_file well. The description only clarifies the meaning of 'number' (count of giveaway links); it adds nothing about productId or the payload-vs-flat-parameter mutual exclusivity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: creates a new package containing a specified number of giveaway links. It is reasonably distinguishable from list_giveaway_packages/get_giveaway_package, though the 'creates a new package' phrasing sits close to the sibling create_giveaway without explaining the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of the competing siblings (create_giveaway, create_giveaway_checkout, create_gifting_checkout). The agent gets a purpose but no routing criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_productCreate a productB

Destructive

Rate limit: 5 requests / minute per shop. See Rate limiting.

Creates a product from a design or a digital product.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description does add one genuinely useful behavioral fact — the 5 requests/minute per-shop rate limit — but says nothing about the confirmation requirement, what the destructive side effects are, or that creation is not idempotent (retries can duplicate products).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks with no filler; the rate-limit constraint is front-loaded in italics where an agent will see it first. Nothing is wasted, though the single purpose sentence is arguably too terse for a tool with this much branching behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a non-idempotent, destructive-flagged create operation with a nested discriminated-union body, a `confirm` gate, and no output schema, yet the description is one sentence plus a rate limit. It omits the confirmation prerequisite, the hidden-by-default creation behavior, and any hint of what a successful call returns, so an agent must reconstruct all of that from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including `account`, `confirm`, `payload`, `payload_file` and the nested region objects is already documented in the schema. The phrase "from a design or a digital product" loosely gestures at the `type` discriminator but adds no syntax, defaults, or constraints beyond what the schema states. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Creates a product") and names the two supported modes — design or digital — which maps cleanly onto the schema's discriminated union. It does not differentiate itself from the surrounding product-mutation siblings (update_product_state, archive_product, toggle_product_availability), but the purpose itself is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a rate limit but no when-to-use guidance: it never says when to prefer the design flow over the digital flow, what prerequisites exist (e.g. the image must already be registered, the template must already exist), or that the `confirm` flag gates the call. An agent must infer all routing from the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_promotionCreate a promotionB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a promotion

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the write/destructive safety profile is covered. The description usefully adds the rate limit (100 requests/10 seconds per shop), but does not explain destructive effects, auth requirements, or other side effects beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler; the rate-limit constraint is front-loaded. The purpose sentence 'Creates a promotion' restates the title and name, so it earns slightly less than full marks for value density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema coverage and existing annotations, the description is minimally adequate. However, it does not help an agent navigate the complex payload variants or frame the create operation beyond a bare statement and rate limit. No output schema exists, but return values are not the main gap here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the structured schema already documents the parameters, making 3 the baseline. The description adds no parameter-level meaning such as payload variant selection or confirm semantics. The complex oneOf payload alternatives are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Creates a promotion'. It does not explicitly differentiate from sibling tools like update_promotion or get_promotion, so it falls short of full sibling differentiation. The rate-limit line is peripheral to purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as update_promotion or get_promotion, and no prerequisites or exclusions are given. Usage is only implied by the tool name. The sole context provided is a rate-limit note.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_webhookCreate a webhookC

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Create a webhook

ParametersJSON Schema

Name	Required	Description
`url`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`allowedTypes`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

C2.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the write/destructive/openWorld profile, but the description adds a genuine behavioral fact the annotations lack: a rate limit of 100 requests / 10 seconds per shop. That is real added value, though it doesn't say what happens on creation, whether duplicate URLs are rejected, or whether the hook fires immediately.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The rate-limit sentence is front-loaded and worth keeping, but the second sentence is pure tautology occupying half the description. Short overall, but not every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, open-world mutation tool with a nested payload object, zero required top-level params, and no output schema, the description is far too thin. It omits authentication expectations, the allowedTypes semantics, and any notion of what a created webhook returns or how it is identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Six parameters (url, account, confirm, payload, allowedTypes, payload_file) with 67% schema coverage, and the description explains none of them. It does not clarify the required payload url/allowedTypes, the confirm-gating semantic, or the mutually exclusive payload vs payload_file paths.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description's only purpose sentence, "Create a webhook," is a literal restatement of the tool name (create_webhook) and title (Create a webhook). It adds no verb/resource detail beyond what structured fields already convey and does nothing to distinguish it from siblings like update_webhook or delete_webhook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives such as update_webhook for modifying existing hooks. The agent is left to infer that this creates a new hook rather than updating one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_webhookDelete a webhookC

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Delete a webhook

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`webhook_configuration_id`	Yes	Native webhookConfigurationId

TDQS

C2.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds a concrete behavioral fact the annotations do not — a 100 requests / 10 seconds per-shop rate limit with a link to the guide — but says nothing about irreversibility, permissions, or what happens when the id is unknown.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short and free of padding, but the only substantive sentence is a boilerplate rate-limit notice; the one-line purpose is a pure duplication of the title, so the second line earns nothing and the total word count is not the issue — the allocation is.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering destructiveness and non-idempotency and the schema fully documented, the description is barely adequate: for a destructive, non-idempotent operation it should at least state that the deletion is permanent and whether the target must exist. The rate-limit note is the only real addition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including the account label caveat, the confirm guard, and the webhook_configuration_id constraints, so the schema carries the parameter burden. The description adds no parameter-level meaning beyond that, which is the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Delete a webhook" names a specific verb and resource, so the basic purpose is unambiguous. However, it is a verbatim restatement of the tool title with nothing added — no scope, no target qualifier, and no differentiation from the sibling lifecycle tools update_webhook, create_webhook, get_webhook, and list_webhooks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives. The presence of siblings like update_webhook (which can presumably disable a webhook) makes this omission meaningful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disable_giveaway_checkoutDisable giveaway configC

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

disables a giveaway config

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds a rate limit (100 requests/10 seconds per shop), which is useful behavioral context, but it does not explain what 'disabling' entails (reversibility, effects on related resources), leaving a gap beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and contains no wasted words. However, it front-loads the rate limit note ahead of the purpose statement, which is a slightly suboptimal ordering for an agent scanning for what the tool does.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Annotations cover the safety profile and the schema fully documents parameters, but the description omits what disabling a giveaway config actually does (e.g., stops checkout, revokes links) and the confirm parameter's role is only in the schema. For a destructive operation with no output schema, this leaves the agent without consequence details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, confirm) are fully documented in the schema. The description adds no parameter information, which is the baseline expectation when the schema is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'disables a giveaway config' restates the title 'Disable giveaway config' almost verbatim, providing no additional clarity about the action or distinguishing it from siblings like finish_giveaway or create_giveaway_checkout. It is a tautology rather than a specific purpose statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus alternatives such as finish_giveaway or update_promotion. The description only states what it does, leaving the agent to infer usage context entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

end_streamingSet streaming status to endedB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to ended for specified services

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`services`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered structurally. The description adds genuinely useful operational context the annotations don't carry — a 100 req/10s per-shop rate limit — but says nothing about what 'ended' does to an in-progress stream or whether the change is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no padding; the rate-limit constraint and the purpose are both front-loaded. Slightly odd ordering (limit before purpose) but nothing is wasted or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, no required fields, a nested payload object, three mutually exclusive body-delivery options, and no output schema, the description is thin — it never explains the services vs payload vs payload_file choice or what a successful call returns. Annotations and the schema carry most of the load, making this adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so the schema already documents account, confirm, payload, and payload_file including their mutual-exclusion rules. The description's phrase 'for specified services' only loosely gestures at the services/payload input, adding no format or precedence detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Sets ... to ended') and resource ('streaming status') with scope ('for specified services'), so an agent understands the operation immediately. It does not name or differentiate itself from the obvious sibling start_streaming or the read-side get_streaming_status, leaving the routing to name inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance, and no mention of the complementary start_streaming / get_streaming_status siblings. The only guardrail ('confirm: set true only when the user asked for exactly this action') lives in the schema, not the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

export_resourcesExport bounded private metadataB

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`arguments`	No	Current list query/path arguments; cannot override profile/policy/output.
`max_items`	No
`max_pages`	No
`operation`	Yes
`output_file`	Yes
`start_offset`	No

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already declaring destructiveHint=true and readOnlyHint=false, the description still adds real behavioral context: file mode 0600, page/item/5MiB budget caps, explicit page/offset continuation, and negative guarantees (no links followed, no binary downloads, no atomic-backup guarantee). This meaningfully exceeds the annotation surface, though it doesn't explain what the destructive aspect actually destroys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence, front-loaded with the export action and file target before the budget and continuation clauses. It wastes no words, though the heavy abbreviated jargon slightly impairs readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with nested objects, 38% schema coverage, and no output schema, the description gives good behavioral context but omits guidance on operation selection and the confirm/account semantics. It is adequate but not sufficient on its own.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 38%, so the description must compensate, and it does partially by explaining page/size budgets and offset-based continuation. However it says nothing about the operation enum values, account, confirm, or the nested arguments object, leaving much of the 8-parameter surface undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (export) and resource (native page/size/results metadata) written into a new file, which is clearly distinguishable from the many sibling list_* tools that return data inline. It is dense with jargon but the core action and output target are identifiable without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to choose this export tool over the sibling list_products/list_orders/etc. tools it wraps, nor any statement of prerequisites beyond the implied 'Confirmed' in the name. The agent must infer that this is the file-producing variant.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

finish_giveawayFinish giveawayB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish giveaway and select winners

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Native id
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`participants`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the danger profile is covered structurally. The description adds a concrete rate limit (100 requests / 10 seconds per shop), which is genuine context beyond annotations, but it does not explain irreversibility or what state changes on finishing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines with no filler. The rate-limit notice is front-loaded ahead of the purpose statement, which is slightly odd ordering but harmless and easily parsed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive, non-idempotent mutation with a nested payload and no output schema, so the description carries moderate burden. It covers rate limits but omits what finishing entails (participant requirements, whether winners are drawn randomly, irreversibility) relative to the complexity and sibling finish_giveaway_draw.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents id, account, confirm, payload, participants, and payload_file. The description adds no parameter meaning at all, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Finish giveaway') plus a scope differentiator ('select winners'), which signals it is a terminal action. Siblings like finish_giveaway_draw and get_giveaway_draw are not named or contrasted, so the agent must infer the distinction, keeping this below a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no exclusions. With close siblings such as finish_giveaway_draw, create_giveaway, and get_giveaway_draw present, the description never tells the agent which condition selects this tool over those.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

finish_giveaway_drawFinish drawB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish draw and select winners

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Native id
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`participants`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this as destructive, non-idempotent, and open-world. The description adds a concrete rate limit, which is useful behavioral context, but it does not expand on what finishing the draw destroys, whether it is irreversible, or what happens to existing draw state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is minimal and has no filler. The rate limit is useful, but placing it before the core purpose makes the structure slightly less front-loaded than ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The action and a rate limit are given, while annotations cover the destructive/non-idempotent profile and the schema documents most parameters. However, the description does not explain the effect on existing draw state or how it relates to sibling giveaway tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the input schema carries most parameter semantics. The description adds no parameter details, but the high coverage justifies the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action: finishing a draw and selecting winners. It implies a specific draw resource and distinguishes the action from broader giveaway operations, though it never explicitly says 'giveaway' or names a sibling tool for contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as finish_giveaway or get_giveaway_draw, nor any prerequisite or postcondition context. The only additional context is a rate limit, which is not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_collectionGet collection by ID or slugB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a collection by its ID or slug

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`collection_id_or_slug`	Yes	Native collectionIdOrSlug

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop) with a link, which is real behavioral context not present in structured fields. It does not mention error behavior (e.g., what happens for an unknown slug), keeping it from 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks with no waste, though the rate-limit notice precedes the purpose statement, so the core purpose is not strictly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should convey the return shape, but it only says it returns 'a collection' without field or error details. Annotations and the 100% schema coverage handle the safety and input side, so this is adequate but with a clear gap on the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, and the description's 'by its ID or slug' merely restates the collection_id_or_slug semantics. Baseline 3 is appropriate when the schema carries the parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Returns') and resource ('a collection') plus the lookup key (ID or slug), which distinguishes it from list_collections and get_collection_products. It does not explicitly name those siblings, so it stops short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no alternatives named. An agent must infer from the name alone that this is the single-resource fetch versus list_collections for enumeration or get_collection_products for contents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_collection_productsGet products in a collectionA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated products in a collection with optional status filtering. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`status`	No	Filter by product status
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`collection_id`	Yes	Native collectionId

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: a concrete rate limit (100 requests / 10 seconds per shop) and the silent capping of oversized pages at 100.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the rate-limit warning, and the core purpose statement is clear and short. The page-size-cap sentence mildly duplicates the size parameter's schema description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only paginated list tool with full schema coverage and annotations carrying the safety profile, and no output schema to explain, the description supplies the needed rate-limit and pagination constraints. Minor gap: no mention of the pagination traversal pattern or default ordering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including page, size, status, account and collection_id is already documented, giving a baseline of 3. The description's mention of status filtering and the page cap simply restates what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Returns), resource (products), and scope (in a collection) plus the optional status filter, which cleanly separates it from list_products and get_collection. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (listing products scoped to a collection) but never names alternatives such as list_products or update_collection_products, nor states when-not to use it. The rate-limit note is context, not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dns_statusGet DNS configuration statusA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the cached DNS configuration and record status for the shop's custom domain

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: a concrete rate limit (100 requests / 10 seconds per shop) and the fact that the returned configuration is cached rather than freshly resolved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no padding. The rate-limit note is placed first rather than the purpose statement, which is slightly less front-loaded than ideal, but the content is tight overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless read-only tool with annotations covering the safety profile, the description says enough to call it correctly. With no output schema, more detail on what 'record status' contains or how stale the cache may be would help, but the essentials are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'account' parameter is documented in the schema as a private shop profile label. The description adds nothing about the parameter, but with full schema coverage the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns the cached DNS configuration and record status for the shop's custom domain.' The word 'cached' usefully separates it from a live validation. It does not, however, name or distinguish itself from the sibling validate_dns, which an agent could plausibly confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to call this versus validate_dns, which is the obvious alternative in the sibling list. No prerequisites or exclusions are given; the agent must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_donationGet donation by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns donation by id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`donation_id`	Yes	Native donationId

TDQS

B3.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: a concrete rate limit of 100 requests / 10 seconds per shop plus a link to the rate-limiting guide, which the agent cannot get from the annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no wasted words, though the structure leads with the italicized rate-limit banner and pushes the actual purpose ("Returns donation by id") to second position. That is a minor front-loading inversion rather than a real flaw.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter getter with 100% schema coverage and rich annotations, the definition is adequate, and the rate-limit disclosure is a useful addition. It does not, however, note the not-found behavior or any returned shape, and there is no output schema to fall back on.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (donation_id and the private account label) are already documented in the schema, including the useful note that the account is a label and not an authorization proof. The description adds nothing about parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Returns donation by id" states a verb and resource, but the name (get_donation) and title (Get donation by id) already say exactly the same thing, so this reads close to a restatement rather than added specification. Unlike a strong definition, it does not distinguish this from the sibling list_donations or explain the single-record scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is given: it never states that this is for fetching one known donation versus listing donations via list_donations, nor any prerequisite such as needing the private account label. The only instruction is a rate-limit notice, which is throttling behavior, not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_gifting_configGet gifting configA

Read-onlyIdempotent

Returns the calling shop's saved gifting rules. Returns a default-shaped config when none is persisted yet.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: a default-shaped config is returned when nothing is persisted, so the caller never receives an empty/error result. It does not describe the shape of that default config or any auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the primary behavior stated first and the fallback behavior second. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of describing the return value, yet it only says 'default-shaped config' without indicating what fields a gifting config contains. For a simple zero-required-parameter getter this is adequate but leaves a real gap for an agent that must reason about the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is documented in the schema with a precise warning that it is a profile label, not an identity or auth proof. The description adds nothing about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns the calling shop's saved gifting rules') and scopes it to the calling shop, which separates it from the account-scoped siblings. It does not explicitly name update_gifting_config as the write counterpart, but the read semantics are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance and no alternative named, despite update_gifting_config being an obvious adjacent sibling. The agent must infer that this is the read side of the gifting config pair.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_gift_purchaseGet gift purchase by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns gift purchase details by id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`gift_purchase_id`	Yes	Native giftPurchaseId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop), which is genuinely useful context, but says nothing about error behavior for missing ids.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and free of filler. The rate-limit note is front-loaded ahead of the one-line purpose, which is slightly odd ordering but does not impede comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should hint at what 'gift purchase details' includes; it does not. For a simple id-based lookup with full annotation coverage and a fully documented schema, this is minimally adequate but leaves the return payload undefined.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema documents both the gift_purchase_id pattern and the account label semantics, so the baseline is 3. The description adds nothing about parameter meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (returns) and resource (gift purchase details) scoped by id. Clear and unambiguous, though it does not distinguish itself from retrieval siblings like get_donation or get_promotion that follow the same pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No indication of when to use this tool versus alternatives, nor any prerequisites (e.g., how to obtain a valid gift_purchase_id). The only guidance is implied by 'by id'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_giveaway_drawGet drawB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get draw details

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Native id
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile carries no burden on the description. The description does add one genuinely useful behavioral trait not present in structured data — a per-shop rate limit of 100 requests / 10 seconds — but says nothing about auth requirements, error/not-found behavior, or response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short fragments with no waste: a rate-limit note with a documentation link, then the purpose. It is efficient, though leading with throttling rather than the tool's purpose slightly buries the front-loaded statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read with a fully covered schema and no output schema, the description is close to sufficient, and annotations cover the safety profile. It is still missing error semantics (unknown id, expired draw) and any hint of what 'details' the returned draw contains, which leaves a small but real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both 'id' (native id, pattern/maxLength constraints) and 'account' (exact private shop profile label) fully documented in the schema. The description adds no meaning beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get draw details'), and the name get_giveaway_draw ties it to the giveaway domain. It does not, however, distinguish itself from the sibling finish_giveaway_draw or otherwise clarify that this is a read-by-id lookup, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus alternatives, no prerequisites, and no mention of what happens when the draw id is unknown. The rate-limit sentence is operational context, not usage guidance, so the agent must infer the calling conditions on its own.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_giveaway_packageGet giveaway linksB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all giveaway links for packageId

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`package_id`	Yes	Native packageId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop), which is genuine extra context, but says nothing about ordering, pagination, or result size for a tool returning 'all' links.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very compact, with no wasted words. The only structural quibble is that the rate-limit note is placed ahead of the tool's actual purpose, so the core function is not front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only getter with full schema coverage and no output schema, the description is minimally adequate. It still leaves open whether the returned link list is paginated or bounded, which matters for a tool that claims to return 'all' links.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including a detailed note on the account parameter and a pattern/maxLength on package_id, so the schema carries the semantics. The description only restates packageId without adding format or scoping detail beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns all giveaway links for packageId'), which is clearly distinct from siblings like list_giveaway_packages or create_giveaway_links. It stops short of explicitly naming those siblings, so it doesn't reach a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance, no prerequisites, and no routing to alternatives such as create_giveaway_links or list_giveaway_packages. The agent must infer usage entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_memberGet memberA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Gets a member by id

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Native id
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the rate limit (100 requests / 10 seconds per shop) and a link to the rate-limiting guide, which is real behavioral context not present in structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines: the rate limit is front-loaded and the purpose follows immediately. No waste and nothing buried, though the rate-limit note is slightly noise for a single-item read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A simple read-only lookup with full schema coverage, no output schema and annotations covering the safety/idempotency profile. The description is adequate for its complexity; the only omission is guidance versus the sibling list_members.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both 'id' (the native id with its pattern/length constraints) and 'account'. The description adds no additional meaning about either parameter, which is the baseline expectation when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Gets a member by id'. That is unambiguous about what the tool returns and how it is keyed. It does not differentiate itself from the sibling list_members, which is the main remaining gap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus list_members or any other member-related sibling, and no stated prerequisites. The phrase 'by id' weakly implies you need a known id, but the agent gets no explicit routing advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_operation_schemaInspect native contractC

Read-onlyIdempotent

Local reviewed native method/path/query/body/scopes/rate limit and pinned schema provenance. No provider access or authority proof.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes

TDQS

C2.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world. The description adds two genuinely useful facts beyond the annotations: it makes no provider/network call (local inspection only) and provides no authority or permission proof. However, it says nothing about output shape, freshness, or failure modes, so it adds only moderate behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short fragments with no waste, but the structure is cryptic rather than front-loaded. It is under-specified for its brevity, not over-long, so conciseness is fine but clarity suffers.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does at least name the fields returned (method/path/query/body/scopes/rate limit/provenance). That is enough to signal a metadata-read tool, but the phrasing is fragmentary and omits what 'pinned schema provenance' and 'authority proof' concretely mean to a caller.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the single parameter is a fully-enumerated operation name list that is fairly self-documenting. The description's field list implies the return contents rather than the parameter's meaning, so it does not fully compensate for the coverage gap. A baseline 3 is appropriate for an enum parameter that documents itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description hints that the tool returns a locally-stored contract for an operation (method/path/query/body/scopes/rate limit and schema provenance), but it is a noun-phrase fragment rather than a clear verb+resource statement. An agent can infer it is a metadata lookup rather than a live API call, but the purpose is not stated plainly. Sibling tools like get_webhook or get_product are concrete actions; this one is not differentiated in plain language.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no mention of alternatives or prerequisites. The trailing disclaimer ('No provider access or authority proof') clarifies limits but does not tell the agent when this tool should be chosen over a sibling that actually performs the operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_orderGet order by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`order_id`	Yes	Native orderId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds a genuinely useful operational fact (100 requests / 10 seconds per shop, with a docs link), but nothing about error behavior, missing-order handling, or return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines with no filler; the rate-limit note is front-loaded and the purpose statement follows. Slightly terse relative to what a getter could communicate, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with no output schema, the description never hints at what an order object contains or what happens on a missing id. With annotations covering safety and the schema covering both parameters, the gap is moderate rather than severe.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both order_id and account are already documented in the schema. The description adds no additional semantics about parameter format or meaning, which is the expected baseline when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns order by id'), which is clear and matches the title. However, it does not distinguish itself from the closely related sibling get_order_by_friendly_id, so an agent must infer that this one takes the native orderId rather than the friendly id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus list_orders, get_order_by_friendly_id, or the webhook/report getters. The only context given is a rate limit, which is a constraint, not usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_order_by_friendly_idGet order by friendly idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by friendly id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`friendly_id`	Yes	Native friendlyId

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description is not required to restate them. It usefully adds a concrete rate limit (100 req / 10s per shop) with a docs link, which is exactly the kind of operational context annotations cannot carry. It still omits error behavior (e.g. not-found handling), keeping it below the top mark.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler and the rate-limit constraint placed first, so the operational limit is front-loaded. It is appropriately sized, though the body sentence adds almost nothing beyond the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup with full annotation coverage and no output schema, the description is largely adequate. But it neither routes the agent away from the near-identical get_order nor indicates what a call returns or whether a missing friendly_id produces an error, leaving small but real gaps for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, including the account label semantics and friendly_id pattern/length. The description only echoes the lookup key and adds no syntax, format, or validity guidance beyond the schema, which is the expected baseline when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns order') plus the lookup key ('by friendly id'), which is enough to distinguish it from the list_orders sibling. It does not, however, explicitly contrast with get_order, the closest sibling that presumably looks up by a different identifier, so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_order, list_orders, or any other order-retrieval sibling. The only usage-adjacent content is the rate limit, which constrains calling frequency but does not tell an agent which tool to pick.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_productGet product (offer) by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product by id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`product_id`	Yes	Native productId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered by structured data. The description adds a genuinely useful behavioral fact not present in annotations: a 100 req/10s per-shop rate limit with a link. It says nothing about error behavior (e.g. unknown id) or account scoping, so it is only moderately additive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines, front-loading the rate-limit caveat before the core statement. Nothing is padded, though the single-sentence return statement is terse enough that it verges on under-specification rather than true conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-resource read tool with full schema coverage, complete annotations, and no output schema, the description supplies what an agent needs beyond structured fields: the rate limit. Error/not-found behavior is the only notable omission, which is minor for a getter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters ('account' with its profile-label semantics and 'product_id' as a native id with a pattern constraint) are already fully documented in the schema. The description adds no parameter meaning beyond that, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns product by id') that clearly distinguishes it from siblings like list_products, create_product, archive_product, and get_product_inventory. It does not, however, explicitly call out those siblings or scope (e.g. whether it returns offers/variants), so it stops short of the 5 tier.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives such as list_products or get_product_inventory, nor any prerequisites (e.g. that product_id must be a native id, or how 'account' scoping affects results). The rate-limit note is operational, not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_product_inventoryGet product (offer) inventory by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product (offer) inventory by id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`product_id`	Yes	Native productId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds a concrete rate limit (100 requests / 10 seconds per shop) that an agent cannot get from annotations, but it says nothing about what 'inventory' contains or whether the result can be stale/empty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is two short sentences with the operational constraint front-loaded and zero filler. It is efficient, though the sparse phrasing borders on under-specification for a lookup tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain what an inventory response looks like (availability, stock state, offer fields), which it does not. Combined with no usage guidance against siblings, the definition is minimally viable but leaves an agent guessing about the result payload.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with only two parameters, so the schema already documents 'account' (shop profile label, not a provider identity) and 'product_id' (native productId). The description adds no format, validation, or scoping detail beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb and resource ('Returns product (offer) inventory by id') and matches the title, so the agent knows this is a by-id inventory read rather than a product-details read. It does not explicitly distinguish itself from the sibling get_product, which likely returns product metadata, leaving that separation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_product, list_products, or update_product_state. The only contextual statement is a rate-limit warning, which is a constraint rather than a usage rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_product_templateGet product template detailsB

Read-onlyIdempotent

Get detailed information about a specific product template.

This endpoint is public and does not require authentication. Returns full product details including variants, customizable areas, size guide, and images.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`product_id`	Yes	Product template ID

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly, idempotent, openWorld and non-destructive. The description adds useful non-annotation context: it is a public endpoint needing no authentication, and it enumerates the returned payload (variants, customizable areas, size guide, images). That returns-shape info is valuable since there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Short and front-loaded: purpose first, then auth note, then return contents. No filler sentences, though the indentation/whitespace is slightly awkward.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-param read with rich annotations, the description is largely complete, and the return-content enumeration compensates for the missing output schema. It remains thin on the multi-item siblings' relationship, but nothing critical to invoking the call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both params are documented in-schema, including the account field's subtle 'private shop profile label, not an authorization proof' semantics. Baseline 3 is appropriate; the description adds nothing beyond the schema for parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get detailed information about a specific product template'), which is clear. However, it does not differentiate from close siblings like get_product, list_product_templates, or search_product_templates, which a reader must infer from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this vs the many sibling list/search tools (list_product_templates, search_product_templates, get_product). The reader has to infer that this is the single-item retrieval endpoint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_promotionGet a promotion by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a promotion by id

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`promotion_id`	Yes	Native promotionId

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds a concrete operational constraint (100 requests / 10 seconds per shop) with a link, which is genuinely useful context not present in structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no waste; the rate-limit constraint is front-loaded. Slightly odd that the primary purpose is subordinated to the rate-limit note, but nothing is bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-resource read with full annotation coverage and full schema coverage, the essentials are present. However, there is no output schema, so the description could say more about what a returned promotion contains or how the response is shaped.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, including the 'account' caveat and promotion_id pattern. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Returns a promotion by id'), which is unambiguous. It does not differentiate from siblings like list_promotions or update_promotion, but the singular 'by id' framing is distinct enough to infer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus list_promotions, update_promotion, or create_promotion. The only usage-adjacent content is a rate-limit note, which is a constraint, not a when-to-use signal.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pro_subscriptionGet Pro subscription statusA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current Fourthwall Pro platform subscription status, plan, and usage against plan limits

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond annotations by disclosing a concrete rate limit (100 requests / 10 seconds per shop) and the shape of what is returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words, but the rate-limit note is front-loaded ahead of the purpose statement, which is slightly awkward ordering. Still compact and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description usefully names the returned content (status, plan, usage against limits). Combined with the rate-limit disclosure and full schema coverage, an agent has enough to call it correctly, though the return format is only loosely described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is documented in the schema itself, so the baseline of 3 applies. The description adds nothing about the account label semantics beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns the current Fourthwall Pro platform subscription status, plan, and usage against plan limits. No sibling tool covers subscription state, so an agent can distinguish it immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the purpose statement (call it to check Pro subscription state); there is no explicit when-to-use, when-not-to-use, or named alternative. For a simple status-read tool this is minimally adequate but leaves the agent to infer context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_public_tokenGet or create a public tokenB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns an existing public token for the shop, or creates a new one if none exists

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`output_file`	Yes	Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds genuinely useful context with the 100 req/10s rate limit, but leaves the destructive flag unexplained — it never says whether minting a token invalidates or rotates an existing one, which is exactly the risk an agent needs to know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler. The only structural nit is that the rate-limit line leads, pushing the actual purpose into second position rather than front-loading it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should carry more of the return story, but it only says a token is returned without describing its form or use. Combined with the unexplained destructive behavior, this is adequate but with visible gaps for a tool that both reads and mutates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm and output_file are already well documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource pair: it returns an existing public token for the shop or creates one when none exists. No sibling tool deals with public tokens, so there is no ambiguity to resolve, though it never explicitly distinguishes itself from the surrounding get_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The get-or-create behavior is described, but there is no guidance on when an agent should call this versus alternatives, no prerequisites, and no explanation of the confirm flag's role (left entirely to the schema). The rate-limit note is contextual, not usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_reportGet a reportA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Fetches a specific analytics report for a date range

ParametersJSON Schema

Name	Required	Description
`to`	Yes	Native to
`from`	Yes	Native from
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`report_id`	Yes	Native reportId
`aggregation_timezone`	Yes	Timezone in ISO-8601 format (e.g., Europe/Warsaw for Warsaw)
`aggregation_precision`	Yes	Native aggregationPrecision

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely new context by disclosing the 100 requests / 10 seconds per shop rate limit and pointing to a rate-limiting guide, which is not derivable from any structured field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The rate-limit caveat is front-loaded, which is defensible since it is an operational precondition, though it slightly delays the core purpose statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters, 5 of them required, and no output schema, the description does little beyond the rate limit. Required-but-non-obvious inputs like aggregation_timezone and aggregation_precision carry only terse 'Native ...' schema text, and the description does not compensate for the absence of return-value documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters and the baseline is 3. The description adds no additional parameter meaning (e.g., how from/to interact with aggregation_timezone, or the valid report_id space) beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetches a specific analytics report') plus the scope ('for a date range'), which distinguishes it from the sibling list_reports. It stops short of saying which analytics domain (sales, traffic, etc.) or what makes a report 'specific' beyond report_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The date-range scoping implies usage, and the presence of list_reports as a sibling lets an agent infer the enumeration-vs-single-fetch split, but the description never states when to use this versus list_reports or what prerequisites exist. Usage is only implied, not asserted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sample_balanceGet sample credit balanceA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current sample credit balance for the shop

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely new behavioral context the annotations cannot convey: a concrete rate limit of 100 requests / 10 seconds per shop, plus a link to the rate-limiting guide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Slightly suboptimal ordering: the rate-limit note is front-loaded ahead of the one sentence that states what the tool actually does, which is the more important selection signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so nothing documents the return value beyond 'current sample credit balance for the shop' — no indication of units, currency, or whether it is a number or an object. For a trivial read-only zero-required-param tool this is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is documented in-schema as an exact private shop profile label. The description says nothing about the parameter, so baseline 3 applies — the schema does all the work and the description adds no syntax or scoping detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns the current sample credit balance for the shop'), which no sibling in the list covers — the surrounding tools deal with webhooks, products, collections, promotions, and giveaways, so there is no ambiguity to resolve. An agent can select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no prerequisites, and names no alternative. The only operational guidance is a rate limit, which is a constraint rather than a usage condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_shopGet current shopB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully adds a non-obvious behavioral trait, the 100 req/10s per-shop rate limit, but says nothing about authentication needs or what the returned shop object contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no padding, and the rate-limit constraint is front-loaded where a caller will see it. It is efficient, though the sparseness borders on underspecification rather than tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter getter with annotations covering safety, the description is minimally sufficient. With no output schema, though, nothing tells the agent what fields the shop object returns, which leaves a real gap for a tool whose whole job is returning an object.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single optional `account` parameter, and the schema text itself explains that it is a label, not an authorization proof. The description adds no parameter detail, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (returns the current shop), which is clearer than a tautology like 'Get shop'. However, it does not distinguish itself from near siblings such as get_shop_contact, get_shop_stats-style tools, or list_accounts, so an agent must still infer scope from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling getters. The only guidance-adjacent content is the rate-limit note, which is operational rather than selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_shop_contactGet current shop contact infoA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop contact info

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop) and a link to rate-limiting documentation, which is useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

At two sentences, the description is tightly sized and front-loads the rate-limit caveat before the core purpose. Both sentences earn their place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only getter with full schema coverage and rich annotations, the description supplies the core purpose and rate-limit behavior. It does not explain when to choose this over sibling get_shop, but the remaining structured fields cover the invocation details adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single optional 'account' parameter, so the schema fully documents its semantics. The description adds no additional meaning or format details for the parameter, making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Returns the current shop contact info.' An agent can tell it retrieves contact information, but it does not distinguish this from the sibling tool get_shop, so sibling differentiation is absent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no when-to-use guidance, no alternatives, and no prerequisites. It only states what is returned, leaving the agent to infer appropriate usage from the name and context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_streaming_statusGet streaming statusB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns streaming status for all services

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety and idempotency profile. The description adds a useful operational detail: the rate limit of 100 requests per 10 seconds per shop. However, it does not disclose auth requirements or response shape beyond the one-line scope statement, so a 3 is appropriate given annotations carry most of the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no wasted words. The rate-limit note is front-loaded before the purpose statement, which is slightly less ideal for immediate purpose discovery but still acceptable and well-structured overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and read-only, with rich annotations and full schema coverage. The description supplies rate-limit and scope context, and while no output schema exists, the one-line return statement is sufficient for a status getter. Nothing critical to invoking the tool correctly appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single optional 'account' parameter is fully documented in the schema. The description adds no additional parameter semantics, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Returns') and resource ('streaming status for all services'). It clearly distinguishes itself from write siblings like start_streaming and end_streaming by being a getter, though it does not explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance or alternatives are provided. The rate-limit note is operational, not usage guidance. An agent must infer from the tool name alone when to choose this over start_streaming or end_streaming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_thank_youGet Thank You by idB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get Thank You details

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`thank_you_id`	Yes	Native thankYouId

TDQS

B3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a concrete, operationally relevant constraint beyond that: 100 requests / 10 seconds per shop, with a link to the rate-limiting guide. It stops short of describing behavior on a missing/invalid id, but the rate limit is real added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but the boilerplate rate-limit banner is placed ahead of the actual purpose sentence, which is poor front-loading and forces the agent to read past irrelevant text to find 'Get Thank You details'. The four-word purpose line is itself too thin to earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining what a 'Thank You' record contains, and it does not. Parameters are fully covered by the schema and the annotations cover safety, but the return content is left entirely unspecified for a get-by-id tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, thank_you_id) are already documented in the schema, including the pattern and maxLength constraints. The description adds nothing about parameter format or meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'Get Thank You details', which restates the title 'Get Thank You by id' almost verbatim and does not clarify what a 'Thank You' resource is (tip, thank-you note, post-purchase page?) or how it differs from siblings like get_donation or get_promotion. It does imply single-resource retrieval by id, which is minimally informative but far from specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, what prerequisites exist (e.g. the account parameter, permissions), or what the alternative is if the id is unknown. The only non-purpose sentence is a rate-limit notice, which is not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webhookGet a webhookC

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a webhook

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`webhook_configuration_id`	Yes	Native webhookConfigurationId

TDQS

C2.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop), which is useful behavioral context beyond annotations, but it omits other behavioral details such as error handling or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and places the rate limit first, which is useful. However, the 'Get a webhook' line is redundant with the title and adds no information, making the description under-specified rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-ID tool with rich annotations and full schema coverage, the structured fields carry most of the invocation burden. Still, with no output schema and no description of return values or error behavior, the definition is only minimally complete and leaves gaps an agent might hit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters are documented in the input schema. The description adds no parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is essentially 'Get a webhook', which restates the tool name/title rather than describing the specific resource or operation. It does not explain what a webhook configuration is or distinguish this tool from siblings like get_webhook_event or list_webhooks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is provided, and no alternatives or prerequisites are named. The rate limit is an operational constraint, not usage guidance for selecting this tool over another.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webhook_eventGet a webhook eventA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a single webhook event by ID

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`webhook_event_id`	Yes	Native webhookEventId

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds a concrete rate limit (100 requests / 10 seconds per shop) and links to the rate-limiting guide, which is a meaningful behavioral constraint beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is very concise, using only two sentences. However, it front-loads the rate-limit note ahead of the tool's primary purpose, which slightly weakens immediate scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-by-ID tool with annotations covering safety and no output schema, the description is nearly complete. It states purpose and rate limit, but omits any explicit usage context relative to siblings, leaving a small gap for an agent choosing between this and list_webhook_events or get_webhook.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account and webhook_event_id) are already documented in the schema. The description adds no extra meaning beyond the phrase 'by ID', which merely restates the required parameter. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Get) and resource (a single webhook event by ID), making the core action unambiguous. It does not explicitly differentiate from close siblings like get_webhook (configuration) or list_webhook_events, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no exclusions, and does not point to alternatives like list_webhook_events for multiple events or get_webhook for the webhook definition itself. Usage is only implied by the phrase 'by ID'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accountsList private shop profilesC

Read-onlyIdempotent

Local labels/default/auth source availability only. No credential values, paths, provider identity or network.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false. The description adds valuable behavioral scope by stating that only local labels/default/auth source availability is exposed and that credential values, paths, provider identity, and network data are excluded.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but it is composed of cryptic fragments rather than a front-loaded statement of purpose. It is concise without being clear about what the tool actually lists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should explain return values, but it only lists exclusions and never says what account/profile data is returned. Combined with the missing usage guidance, an agent lacks enough context to know when and why to call this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to document. The baseline score for a zero-parameter tool is 4, and the description does not need to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description does not state a clear verb and resource. 'Local labels/default/auth source availability only' is a scope constraint, not a definition of what list_accounts returns, and it does not distinguish this tool from the many list/get siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or any sibling tool such as get_shop or list_webhooks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_collectionsGet all collectionsA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all collections with pagination. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`search`	No	Native search
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: a concrete rate limit (100 requests / 10 seconds per shop) and the pagination cap behavior, both beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the rate-limit constraint front-loaded. The page-size sentence is partly redundant with the schema but is short enough not to be wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-required-parameter list tool with no output schema, the description covers pagination semantics and rate limiting, which are the main operational risks. It does not describe the shape of returned collections, but for a simple listing endpoint that is an acceptable omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (page, size, search, account) are already documented in the schema. The description's page-size cap statement duplicates the schema's own 'maximum page size is 100' text, adding no new meaning. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns all collections') with the scope qualifier 'all', which distinguishes it from get_collection. It does not explicitly name siblings, but the verb choice makes the read-list intent unambiguous against create_collection/update_collection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance and never mentions alternatives such as get_collection for a single collection or the paginated/filtered variants. The only contextual note is a rate limit, which is operational rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_contributionsGet contributions awaiting thank youB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated list of orders, donations, and other contributions that can be thanked. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`state`	No	Native state
`search`	No	Native search
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`min_value`	No	Native minValue
`contains_msg`	No	Native containsMsg

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: a concrete rate limit (100 requests / 10 seconds per shop) and a capping behavior on the page size. It does not mention auth requirements or the default filtering behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus an italicized rate-limit note; the operational constraint is front-loaded and the functional statement follows. No redundant filler, though the page-size cap is duplicated verbatim from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, all-optional read tool with no output schema, the description explains the resource and pagination cap but leaves important gaps: what a returned contribution looks like, and whether the default results are limited to WAITING contributions (the title implies 'awaiting thank you' while the state param accepts SENT/CANCELLED/SKIPPED). An agent could call it but might misread the default scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description repeats the page-size cap that the schema already states and adds nothing about the state enum values, the search syntax, or the account label semantics for the remaining parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Returns paginated list of orders, donations, and other contributions that can be thanked'), and the 'that can be thanked' qualifier distinguishes it from plain siblings like list_orders and list_donations by scoping to actionable contributions. It doesn't, however, explicitly name those siblings as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Nothing tells the agent when to choose this tool over list_orders, list_donations, or get_thank_you. The phrase 'can be thanked' hints at intent, but there is no explicit when-to-use, when-not-to-use, or prerequisite guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_donationsGet all donationsB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all donations with pagination. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the read-only, idempotent, open-world profile, so safety is covered. The description adds a concrete rate limit (100 req/10s) and a pagination cap, which is useful operational context. However, it doesn't explain what a 'donation' contains, ordering, or whether results are filterable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with rate-limit context, then the pagination behavior. It's efficient, though the page-size cap is repeated from the schema, which is mildly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated read tool with full annotation coverage and 100% schema description coverage, the definition covers rate limits and page capping but omits ordering, filtering behavior, and what the response contains. No output schema exists, so return-shape guidance would help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all three parameters including the size cap. The description's pagination sentence largely duplicates the schema's 'size' description. Baseline 3 is appropriate since the description adds little beyond the schema here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource ('Returns all donations') and adds scope detail (pagination). It doesn't explicitly differentiate from the sibling 'list_contributions', which is a semantically adjacent resource, but the resource itself is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance. It doesn't say when to prefer this over 'get_donation' (singular) or 'list_contributions'. The only conditional language is about page size capping, not about tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_giveaway_packagesGet all giveaway packagesA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all packages with giveaway links

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the safety profile (readOnlyHint, idempotentHint, non-destructive, openWorld). The description adds genuinely useful behavior beyond that: a concrete rate limit of 100 requests / 10 seconds per shop with a doc link. What it does not add is return shape or pagination behavior, so it is not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero waste; the operational constraint (rate limit) is front-loaded and the purpose follows immediately. Nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries more burden for return values, and it only says 'all packages with giveaway links' without describing result structure or pagination. Combined with annotations covering safety and the schema covering the parameter, it is adequate but leaves a genuine gap on the list result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is fully documented in the schema. The description adds no additional parameter meaning, so this lands at the baseline 3 for a schema that already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Returns all packages with giveaway links.' It is clear what the tool does. However, it does not distinguish itself from the singular sibling get_giveaway_package or explain the plural/singular relationship, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_giveaway_package for a single package. The agent must infer usage entirely from the tool name and context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_mailing_listGet all mailing list entriesA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all mailing list entries. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations don't: a concrete rate limit (100 requests / 10 seconds per shop) and the page-size cap behavior. It doesn't disclose ordering or whether the result set is scoped to a shop, which would complete the picture.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, with the operational constraint (rate limit) front-loaded and the page-size cap immediately after. No filler or restated name/title padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple paginated list tool with full schema coverage and annotations covering safety, this is nearly complete. Rate limiting is disclosed; only return ordering and result scoping are unstated, and there is no output schema so return-shape explanation isn't required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents page, size and account. The description restates the size cap, which is redundant with the schema's own note, and adds nothing about the 'account' label semantics. Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns all mailing list entries.' An agent immediately knows this is a paginated read of mailing list entries. No sibling tool covers mailing lists, so no differentiation is required, but the description doesn't note any scope limits (e.g. per-shop scoping).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of when-not to call it. The rate-limit sentence is operational context, not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_media_imagesList media library imagesA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Retrieves all images from the shop's media library

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a genuine behavioral detail beyond the structured data: the rate limit (100 requests / 10 seconds per shop), with a link to further documentation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The rate-limit line is arguably front-loaded ahead of the actual purpose statement, which slightly delays the core description, but overall it is tight and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one fully documented parameter (account) that is not required, no output schema, and annotations covering the safety profile, the definition supplies enough context to call the tool correctly. Return format and pagination behavior are unaddressed, a minor gap for a list endpoint with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is fully documented in the schema, so baseline is 3. The description adds no parameter-level meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Retrieves') and resource ('all images from the shop's media library'), which is clear. It does not explicitly differentiate itself from sibling media tools like save_media_image or remove_product_images, but the read-only listing purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as list_products, list_collections, or the other media-library tools (save_media_image, request_media_upload_url). Usage must be inferred entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_membersList membersA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all members for the current shop. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real operational context the annotations lack: a 100 req/10s rate limit and the fact that oversized page values are capped rather than rejected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler; the rate-limit constraint and the pagination cap each earn their place. Leading with the rate limit before the purpose slightly delays the core statement, but it is still compact and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple paginated list tool with full schema coverage and rich annotations, and no output schema to explain, the definition covers purpose, limits, and pagination adequately. It could note the relationship to get_member and membership tiers, but nothing blocks correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters (page, size, account) are documented in the schema itself, including the 100 cap and the 'exact private shop profile label' clarification. The description merely restates the size cap, adding no meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists all members for the current shop'), so an agent knows exactly what it returns. It does not distinguish itself from the nearby get_member sibling (single vs. list), so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Bulk-listing intent is implied by 'lists all members' and the paging parameters, but there is no explicit when-to-use guidance or pointer to get_member for a single lookup. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_membership_tiersList membership tiersA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all tiers for the current shop

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop) plus a link to the rate-limiting guide, which is real behavioral context not present in the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and front-loaded, with every sentence earning its place. The rate-limit notice is placed before the purpose statement, which slightly buries the actual function, but no wording is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A simple, read-only, zero-required-parameter list tool with full annotation coverage and no output schema, so the bar is low. The description covers scope and rate limits; only pagination/return-shape hints are absent, which is acceptable given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; the single 'account' parameter is already fully explained in the schema as 'Exact private shop profile label; not a provider identity or authorization proof.' With one optional param and complete schema documentation, the baseline of 3 applies — the description adds nothing about the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists all tiers') and scopes it to 'the current shop'. It is distinguishable from the many list_* siblings (list_members, list_accounts, list_collections), though it does not explicitly contrast itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to call this versus alternatives such as list_members or get_member, and no stated prerequisites. The only usage context is the implicit 'current shop' scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_ordersGet all ordersB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all orders with pagination. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`email`	No	Native email
`status`	No	Native status
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`created_at_gt`	No	Native createdAt[gt]
`created_at_lt`	No	Native createdAt[lt]
`updated_at_gt`	No	Native updatedAt[gt]
`updated_at_lt`	No	Native updatedAt[lt]

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: a concrete rate limit (100 req/10 s per shop) and confirmation that oversized page sizes are capped at 100. It omits any note on result ordering or what happens when filters match nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the operational constraint an agent most needs (rate limit). Minor waste: the page-size cap is duplicated from the schema's size description rather than left to the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool with annotations covering safety and no output schema, the definition covers pagination and rate limits but never describes the shape of a returned order or the default sort/order. Adequate but with a noticeable gap for an agent that must interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all nine parameters are documented in the schema itself. The description only restates the page-size cap already present in the size parameter description, adding no new syntax, format, or filter-combination meaning. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Returns all orders with pagination" states a specific verb (returns/list) and resource (orders), which is clear on its own. It does not, however, distinguish itself from the sibling single-order tools get_order and get_order_by_friendly_id, leaving the agent to infer that this is the bulk-listing variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_order, get_order_by_friendly_id, or any filtered search. The description never mentions that the optional email/status/date filters exist or when to reach for them, so the agent gets no routing help.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_productsGet all products (offers)A

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all products with pagination. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`search`	No	Native search
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful operational context the annotations do not: a concrete rate limit (100 req / 10s) and the capping behavior for oversized page values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler, and the operational constraint is stated up front. Leading with the rate limit rather than the tool's purpose is slightly back-to-front, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only paginated list tool with no output schema and fully documented parameters, the description covers the operation, the rate limit, and the page-size cap. Returned fields and default sort order are unspecified, but these are minor gaps rather than blockers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so page, size, search, and account are all documented in the schema itself. The description repeats the size cap that is already in the size parameter description, adding no new syntax or format meaning beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns all products') plus the pagination behavior. It is clearly distinguishable from get_product (single) and the product-template listers, though it never names those siblings to sharpen the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus get_product, list_product_templates, or the search_* variants. The description only covers rate limits and page-size behavior, leaving selection entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_product_templatesList product templatesA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: a fixed 25-result page size, path-based pagination chosen for HTTP cacheability, and the presence of a total field for computing page counts. It does not describe sort order or whether templates are shop-scoped, which is a minor omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the purpose and then escalating to pagination mechanics. Every sentence carries information; the only slight redundancy is restating the pagination endpoint and its purpose in two adjacent sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single optional parameter, full schema coverage, and no output schema, the description supplies the missing pieces an agent needs: result count, how to page, and where to find the total. It would be complete at 5 if it named the paged sibling tool explicitly or indicated the shape of each template entry.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is documented in the schema as an exact private shop profile label, so the schema already carries the semantics. The description adds nothing about how 'account' scopes the listed templates, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List available product templates') and adds the 25-result batch size, so the agent knows exactly what the call returns. It does not, however, differentiate itself from the many siblings that list the same resource (list_product_templates_paged, list_product_templates_by_category, search_product_templates), which is the main gap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real next-step guidance for pagination ('use the /page/{N} variant', '1-indexed', 'use the total field to calculate total pages'). But it frames pagination as a URL variant rather than naming the actual sibling tool list_product_templates_paged, and it gives no criteria for choosing this list tool over search_product_templates or the by_category variants.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_product_templates_by_categoryBrowse product templates by categoryA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`category`	Yes	Category path. Top-level: Apparel, Accessories, Home & Living. Subcategory paths like 'Apparel/T-Shirts' are also valid.

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover read-only, idempotent, and open-world safety, but the description adds substantial behavioral context: prefix-based category matching, a fixed result count of 25, path-based pagination with 1-indexing, using the total field to calculate pages, and a rationale (HTTP cacheability). This goes well beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then adds operational details in a logical order. It is slightly verbose with five sentences, and the final sentence about cacheability is informative but not essential for invocation; still, each sentence contributes useful context without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with no output schema, the description covers the key operational details: filtering behavior, result count, and pagination instructions including how to compute total pages. It does not describe the response fields or error conditions, but those are less critical given the annotations and schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds meaningful semantics for the category parameter: it explains that matching is by prefix and gives an example ('Apparel' matches 'Apparel/T-Shirts'). The account parameter is not elaborated, but its schema description is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Browse) and resource (product templates) with a clear filter (by category), and it explicitly names the paged variant as the alternative for pagination, distinguishing it from list_product_templates_by_category_paged. Together with the tool name, an agent can identify it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly indicates when to use this tool (browsing templates filtered by category) and provides a specific alternative for pagination. However, it does not mention when to use it versus unfiltered list_product_templates or search_product_templates, so exclusions are absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_product_templates_by_category_pagedBrowse product templates by category by pageA

Read-onlyIdempotent

Browse product templates by category with pagination. This endpoint is public and does not require authentication.

ParametersJSON Schema

Name	Required	Description
`page`	Yes	Page number (1-indexed)
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`category`	Yes	Category path. Top-level: Apparel, Accessories, Home & Living. Subcategory paths like 'Apparel/T-Shirts' are also valid.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: this endpoint is public and requires no authentication, which affects how an agent should call it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core purpose front-loaded and the auth note following. Nothing to trim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description could carry return-shape information, but it only says 'pagination' without page size, total-count, or termination behavior. For a simple read-only paged list with fully documented params, this is adequate but leaves a real gap around what a page actually returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains page (1-indexed), category (top-level and subcategory paths), and account. The description adds nothing about parameter format or semantics; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: browsing product templates filtered by category, with pagination. That distinguishes it from the unpaged list_product_templates_by_category and the non-category list_product_templates_paged, though the description never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only guidance offered is an authentication fact ('public, no authentication'), not a when-to-use rule. With siblings like list_product_templates_by_category, list_product_templates_paged, and search_product_templates_paged available, the description gives no criteria for choosing among them.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_product_templates_pagedList product templates by pageA

Read-onlyIdempotent

List available product templates with pagination. This endpoint is public and does not require authentication.

ParametersJSON Schema

Name	Required	Description	Default
`page`	Yes	Page number (1-indexed)
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnlyHint, idempotentHint and destructiveHint, so the safety profile is settled. The description adds genuinely new behavioral context by stating the endpoint is public and needs no authentication, which is not derivable from the annotations and matters for callers deciding whether to attach credentials.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, no filler, and the pagination scope is stated before the auth note. Every sentence carries information an agent can act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description is the only place pagination mechanics could be explained, and it omits page size and whether total counts are returned. Combined with the absent sibling differentiation, the definition is adequate for a simple list call but leaves real gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so 'page' (1-indexed) and 'account' are already fully documented in the schema. The description adds nothing about page size, 1-indexing, or the exact-match semantics of 'account', so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List available product templates') plus a pagination scope, so the agent knows what comes back. However, it never distinguishes itself from the many near-identical siblings (list_product_templates, search_product_templates_paged, list_product_templates_by_category_paged), which is exactly where confusion is most likely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no mention of alternatives, despite the tool sitting in a cluster of six-plus template-listing variants. The only usable signal is the implicit paged/not-paged distinction carried by the name, which the description should have made explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_promotionsGet all promotionsA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all promotions. The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`codes`	No	Filter by promotion code(s)
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds genuinely useful non-annotation context: an explicit rate limit (100 requests / 10 seconds per shop) plus the pagination capping behavior, both of which affect how an agent should pace and size its calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the rate limit, which is the highest-value operational fact. Slightly penalized because the page-size sentence duplicates the schema's own 'size' description rather than earning new space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool with a fully described schema and no output schema, the definition supplies the operationally important extras (rate limit, capped page size) an agent needs to call it correctly. Filtering semantics for codes/account are delegated entirely to the schema, which is acceptable given full coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters including page, size, codes, and account are already documented in the schema. The description's page-size statement is a verbatim repeat of the 'size' parameter description, adding no new semantics. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Returns all promotions'), so an agent knows this is a listing endpoint. However, it does no sibling differentiation despite living among get_promotion, create_promotion, and update_promotion, so the distinction between listing and fetching a single promotion is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no alternatives named. The agent must guess that this is the browse/scan endpoint versus get_promotion for a known ID, and nothing explains whether filtering is preferred over paging through everything.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_reportsList available reportsA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the list of available report IDs with metadata including name, columns, and supported precisions

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/destructive=false, so safety is covered. The description adds a concrete operational constraint the annotations do not: a rate limit of 100 requests / 10 seconds per shop, which is genuinely useful context for an agent planning calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with the rate-limit warning front-loaded and the return-value summary following. The markdown link and italic wrapping are slightly noisy but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, read-only listing tool with annotations covering safety and no output schema, the description supplies the needed operational context (rate limit) plus a summary of returned fields. Nothing essential to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is a single optional 'account' parameter whose semantics are already documented in the schema. The description adds no additional meaning about that parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Returns the list of available report IDs') and enumerates the returned metadata (name, columns, supported precisions). It distinguishes itself from get_report by implication of 'list', but never names that sibling explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus get_report or any other sibling, and no prerequisites or exclusions. The agent must infer that this enumerates reports while get_report fetches one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_webhook_eventsGet webhook eventsA

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhook events with pagination and optional filtering by one or more webhook types (repeat or comma-separate the type param). The maximum page size is 100 - larger values are capped at 100.

ParametersJSON Schema

Name	Required	Description
`page`	No	Native page
`size`	No	Number of elements per page. The maximum page size is 100 - larger values are capped at 100.
`type`	No	Native type
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful operational context the annotations do not: a 100 requests/10 seconds per-shop rate limit and the 100-item page-size cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact paragraphs with no filler; every sentence carries information. The rate-limit notice is front-loaded ahead of the purpose statement, which is slightly awkward ordering but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers pagination, filtering syntax, and rate limits, which is most of what an agent needs to invoke it. With no output schema, the description never describes the shape of a returned webhook event, leaving a gap for a list/read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema by explaining that the `type` filter accepts repeated or comma-separated values and reiterating the page-size cap. The `account` parameter's label semantics are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (get webhook events) and scopes it with pagination and optional type filtering, which distinguishes it from the singular get_webhook_event. It stops short of naming that sibling explicitly, so the differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the pagination and filtering hints, and the rate-limit note signals a high-volume read. However, there is no explicit when-to-use guidance versus list_webhooks or get_webhook_event, nor any prerequisite or exclusion conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_webhooksGet webhooksB

Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhooks

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a concrete operational constraint the annotations do not carry: 100 requests / 10 seconds per shop, plus a link to the rate-limiting guide. That is genuine added behavioral context, though pagination or result-size behavior is still unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short, but the ordering is poor: a rate-limit warning leads while the actual purpose ("Get webhooks") trails and merely echoes the title. Every word is technically in bounds, yet the front-loaded content is the least important part.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list endpoint with no output schema, the description should at minimum signal what is returned (collection of webhook records) and whether results are paginated. It covers the rate-limit dimension well but leaves the core list semantics implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is well documented in the schema itself as an exact private shop profile label. The description adds nothing about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name and the phrase "Get webhooks" identify the resource, but the description is essentially a restatement of the title rather than a statement of what the tool returns. It never clarifies whether this is a paginated listing of all shop webhooks versus a single lookup, even though the sibling get_webhook makes that distinction critical.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all. With siblings get_webhook, create_webhook, update_webhook and delete_webhook present, the description should say this is the enumeration counterpart to get_webhook, but it offers nothing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark_download_completeMark digital download as downloadedA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Marks digital download as downloaded. If no downloads exist for a digital order and defaultFileUrl is provided in the request body, creates a download with that URL and marks it as downloaded.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`order_id`	Yes	Native orderId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`defaultFileUrl`	No

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=true. The description adds genuinely useful context beyond them: an explicit rate limit (100 req/10s per shop) and the fact that the call can silently create a download record when none exists. It does not say what state is destroyed or whether the action is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the rate limit called out up front as a separate note. The purpose and the conditional behavior are packed efficiently, though the leading rate-limit block before the tool's actual function is a slightly awkward front-load.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description covers the key behavioral facts (rate limit, conditional creation) and relies on a rich schema for the rest. It stops short of stating permissions or the effect on existing download records, but is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the schema carries most parameter documentation (account, confirm, payload, payload_file, order_id). The description adds meaning the schema lacks by tying defaultFileUrl to the conditional creation path, which the schema only lists as a bare string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Marks digital download as downloaded') and adds the non-obvious conditional side effect (creating a download from defaultFileUrl when none exists). It is clear enough to distinguish from siblings like confirm_digital_file_upload and remove_digital_file, though it never names those alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains a conditional behavior but gives no when-to-use guidance, no prerequisites, and no routing to related digital-file tools. An agent is left to infer when this tool is appropriate versus request_digital_file_upload_url, confirm_digital_file_upload, or remove_digital_file.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_shop_batchReview ordered shop effectsB

Read-onlyIdempotent

Validate every exact request and hash order/profile label/schema locally. No native request, credential loading, ownership check or provider preview.

ParametersJSON Schema

Name	Required	Description	Default
`tasks`	Yes	One to twenty exact ordered native effects. No signed receipts or mutable payload files. Cannot override account/confirm/output settings.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by enumerating what it does NOT do: no native request, no credential loading, no ownership check, no provider preview — telling the agent which classes of failure this validation will miss.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no filler, front-loading the validation action before the exclusions. It is terse to the point of being cryptic, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a preview/validation tool there is no output schema, and the description never says what the validation produces (errors, hashes, a pass/fail report). Combined with the implicit relationship to submit_shop_batch, the description is adequate but leaves the agent guessing about the result and the follow-up step.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters (tasks and account). The description's reference to 'order/profile label/schema' loosely maps to the ordered tasks array and the account profile label but adds no syntax or format detail. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title and description convey a local validation/dry-run of an ordered batch of shop effects, but the core purpose is expressed in dense jargon ('hash order/profile label/schema locally') rather than a plain verb+resource statement. It does not name submit_shop_batch as the executing counterpart, so the agent must infer the preview-vs-submit relationship from the tool name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no mention of the obvious alternative (submit_shop_batch) despite it being a sibling. The 'No native request...' clause hints at a pre-submission check, but the agent must infer that this should be called before submitting.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remove_digital_fileRemove a digital file from a productB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes a digital file from the product by its file URL.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`fileUrl`	No
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`product_id`	Yes	Native productId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a concrete rate limit (100 requests / 10 seconds per shop), which is genuine behavioral context not present in annotations. It does not, however, state whether removal is permanent or reversible, which is the key unknown for a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the constraint (rate limit) is front-loaded ahead of the action. Slightly odd ordering for a purpose statement, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent tool with six parameters including a nested request body and no output schema, the description covers purpose and rate limiting but omits permanence/reversibility and the choice among fileUrl, payload, and payload_file. The rich schema carries much of the burden, keeping this at a minimum-viable level rather than inadequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents most parameters (including the account and confirm semantics). The description contributes the fact that the file is identified by URL, which maps to fileUrl, but it does not clarify the interaction between fileUrl, payload, and payload_file, which is the real ambiguity in this schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Removes a digital file from the product') and adds the lookup key ('by its file URL'), which distinguishes it from upload-oriented siblings like confirm_digital_file_upload and request_digital_file_upload_url. It does not explicitly name which sibling to prefer, but the action and identifier are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only guidance is a rate limit, not a when-to-use statement. There is no indication of prerequisites, no mention of when to use this versus the other digital-file or media-removal tools (e.g., remove_product_images), and no exclusions. An agent must infer usage entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remove_product_imagesRemove images from a productB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes specified images from a product by their URLs.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`imageUrls`	No	List of image URLs to remove
`product_id`	Yes	Native productId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds a concrete operational constraint the annotations do not carry: a 100 requests / 10 seconds per shop rate limit. It stops short of saying whether removals are reversible or partial failures are possible, which keeps it out of 5 territory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short elements with no filler. The rate-limit notice is placed first, which is arguably a less important lead than the destructive action itself, but the action sentence is tight and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter destructive tool with a nested payload object and no output schema, the description covers the core action and the rate limit but is silent on the interaction between payload, payload_file and the top-level imageUrls, and says nothing about the confirm safeguard. The schema carries that burden, so the description is adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters, including the confirm, payload, payload_file and imageUrls variants, are already documented. The description only restates that removal is by URL, adding no syntax, format or conflict-resolution detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Removes) and resource (images from a product) plus the identifying mechanism (by their URLs). An agent can immediately tell this is a mutation on product media. It does not name the sibling attach_product_images, so it stops short of full differentiation, but the name and description are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus attach_product_images or list_media_images, and no mention of prerequisites such as the confirm flag or the need for an existing product. The rate-limit line implies usage context but does not route the agent between alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

request_digital_file_upload_urlRequest a presigned upload URL for a digital fileA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a presigned URL to upload a digital file to. After receiving the response, PUT the file bytes directly to the uploadUrl, then call the confirm endpoint to link the file to the product.

ParametersJSON Schema

Name	Required	Description
`size`	No	Size of the file in bytes. Must match the `x-goog-content-length-range` header sent when uploading the bytes to `uploadUrl`.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`fileName`	No	Name of the file
`product_id`	Yes	Native productId
`contentType`	No	MIME type of the file
`output_file`	Yes	Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false. The description adds a concrete, non-annotated behavioral trait – the 100 requests / 10 seconds per shop rate limit with a docs link – plus the multi-step lifecycle (URL → PUT → confirm) that the annotations do not convey. It does not explain what makes the call 'destructive', which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences plus a rate-limit notice; every sentence carries actionable information and there is no filler. The rate-limit warning is front-loaded ahead of the core purpose, which is slightly suboptimal ordering but does not hurt usability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly carries the burden of explaining the return value (a presigned uploadUrl) and the follow-up steps. Combined with the fully documented 9-parameter schema, an agent has everything needed to call it and complete the flow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 9 parameters (including the nested payload object) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns a presigned URL for uploading a digital file. The 'digital file' scoping and the reference to the confirm endpoint make it naturally distinguishable from siblings like request_media_upload_url, upload_file, and confirm_digital_file_upload.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear workflow context: PUT the file bytes to the returned uploadUrl, then call the confirm endpoint to link the file to the product. However, it never explicitly contrasts this tool with the alternative upload paths (upload_file, request_media_upload_url) or states when-not to use it, so no exclusion guidance is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

request_media_upload_urlRequest a pre-signed upload URLB

Destructive

Rate limit: 20 requests / minute per shop. See Rate limiting.

Returns a pre-signed upload URL for uploading a new image. After receiving the response, PUT the image bytes directly to the uploadUrl.

ParametersJSON Schema

Name	Required	Description
`size`	No	Size of the file in bytes. Must match the `x-goog-content-length-range` header sent when uploading the bytes to `uploadUrl`.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`fileName`	No	Name of the file
`contentType`	No	MIME type of the file
`output_file`	Yes	Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The rate limit (20 requests/minute per shop) is real behavioral context not present in the annotations, and the follow-up PUT step clarifies the two-phase flow. But annotations mark this destructiveHint=true, and the description never explains what is destroyed or reserved, nor does it disclose auth/permission prerequisites, so the mutation profile stays opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Short and largely waste-free, with the PUT-the-bytes instruction being the highest-value sentence. Minor structural flaw: the rate-limit callout leads the description ahead of the actual purpose, delaying the front-loaded answer to 'what does this do?'

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, a nested payload object, no output schema, and openWorld access, the description is thin. Because there is no output schema, it should describe the response (the uploadUrl field and the x-goog-content-length-range header the schema's size parameter references), but that required-upload-header detail is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents size, fileName, contentType, account, confirm, payload, and output_file. The description adds no parameter-level meaning beyond what the structured fields provide, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: returns a pre-signed upload URL for uploading a new image. This is clear and actionable, but it never distinguishes itself from close siblings such as request_digital_file_upload_url, upload_file, or save_media_image, leaving the agent to infer that 'image' versus 'digital file' is the dividing line.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives useful downstream workflow guidance — PUT the image bytes directly to the uploadUrl — plus the rate limit. However, it offers no when-to-use/when-not guidance relative to sibling upload tools, so the agent must infer selection from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_media_imageSave an uploaded image to the media libraryB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Persists an uploaded image in the media library after the client has PUT it to the signed URL

ParametersJSON Schema

Name	Required	Description
`width`	No
`height`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`fileUrl`	No
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare it as a non-readonly, destructive, non-idempotent, open-world write. The description adds genuinely new context beyond that: a concrete rate limit (100 requests / 10 seconds per shop) and the prerequisite that the client must have already PUT the file to the signed URL. It still doesn't say what happens on failure or duplicate submission, but the additions are substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very brief and free of padding, with two purposeful sentences. Mild deduction: the boilerplate rate-limit line is front-loaded ahead of the actual purpose statement, so the tool's function is not the first thing the agent reads.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with a nested payload, no output schema, and no required fields, the description covers the workflow entry point and rate limit but omits the payload shape, the meaning of 'confirm', and any return behavior. It is adequate but leaves real gaps that the schema only partially fills.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 57%, and the description explains no parameters at all — width, height, fileUrl, and the payload/payload_file mutual exclusion are left entirely to the schema. With zero required parameters and a nested payload object, the description should clarify what actually needs to be supplied, but contributes nothing here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Persists an uploaded image in the media library.' The reference to 'after the client has PUT it to the signed URL' places the tool at a precise point in the upload workflow, which implicitly separates it from siblings like request_media_upload_url, though that sibling is never named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage timing is implied by the phrase 'after the client has PUT it to the signed URL', which tells the agent this is the final step following a signed-URL upload. However, no alternative tool is named and no explicit when-not-to-use condition is given, so the agent must infer the sequencing from the upload pipeline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_product_templatesSearch product templatesA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query (e.g., 'hoodie', 'black%20t-shirt')
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: a fixed 25-result page size, path-based pagination rationale (HTTP cacheability), and where to find the total count. It does not, however, describe the result shape beyond the count.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with what it searches, then the result count, then pagination mechanics. Every sentence carries information; the pagination sentence is dense but earns its place since the tool has no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of return-value disclosure and does so for the two most agent-relevant facts (25 results, a total field). Searchable-field coverage is complete. What's missing is any mention of the grouped/list alternatives, but for calling the tool correctly the definition is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description exceeds that by expanding what the required 'query' actually matches against (name, brand, description, sizes, categories, colors, production method), which the schema's generic example ('hoodie') does not convey. The optional 'account' parameter is not elaborated in the description, but the schema documents it well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search product templates) and enumerates the searchable fields (name, brand, description, sizes, categories, colors, production method), which is far more specific than the title. However, it distinguishes itself from the sibling search_product_templates_paged only by describing an HTTP path variant ('/search/{query}/page/{N}') rather than naming the sibling tool, which is ambiguous in an MCP context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear guidance for the pagination case (use the paged variant, 1-indexed, use total to compute pages), but says nothing about when to prefer this over list_product_templates, search_product_templates_grouped, or the category-scoped variants. Usage is implied by the verb 'search' rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_product_templates_groupedSearch product templates grouped by product familyA

Read-onlyIdempotent

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query (e.g., 'hoodie', 'black%20t-shirt')
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are collapsed across production methods into a variants list, the page size is fixed at 25, and pagination is path-based for cacheability. It stops short of describing error handling or the account parameter's auth implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and grouping semantics in the first two sentences, then pagination. The trailing 'Pagination is path-based for HTTP cacheability' is a mild rationale rather than an instruction, but it is brief and does not bloat the definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully sketches the return shape (grouped results plus a variants list) and the 25-item page limit, which is what an agent needs to handle results. Deductions for not covering the account parameter's effect or failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented there (query with example, account with an explicit 'not an authorization proof' clarification), so the schema carries the semantic load. The description adds nothing about query formatting or the account parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search), resource (product templates), and the defining behavior (group by product family / libraryId), which distinguishes it from search_product_templates and search_product_templates_paged. The collapsing rule (same physical item, different production methods) makes the tool's identity unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to the /search-grouped/{query}/page/{N} variant for pagination and explains the fixed 25-result page, which is actionable when-vs-what guidance. It does not, however, state when to prefer this grouped search over the flat search_product_templates or list_product_templates siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_product_templates_grouped_pagedSearch product templates grouped by product family by pageB

Read-onlyIdempotent

Search product templates grouped by product family with pagination. This endpoint is public and does not require authentication.

ParametersJSON Schema

Name	Required	Description
`page`	Yes	Page number (1-indexed)
`query`	Yes	Search query (e.g., 'hoodie', 'black%20t-shirt')
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that the endpoint is public and requires no authentication, useful behavioral context, but does not cover pagination limits, response shape, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, second sentence adds auth context. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with rich annotations and full schema coverage, the description gives purpose and auth requirement. It leaves sibling selection and pagination/return semantics implicit, but enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and documents all three params (query, page, account) with constraints. The description only restates grouping/pagination and adds no parameter details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search product templates) with scope (grouped by product family, pagination). It does not explicitly name alternatives among many sibling search/list tools, but the combination of grouping and pagination is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance; does not mention sibling tools like search_product_templates_grouped or search_product_templates_paged. The public/no-auth note is a prerequisite but not selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_product_templates_pagedSearch product templates by pageB

Read-onlyIdempotent

Search product templates with pagination. This endpoint is public and does not require authentication.

ParametersJSON Schema

Name	Required	Description
`page`	Yes	Page number (1-indexed)
`query`	Yes	Search query (e.g., 'hoodie', 'black%20t-shirt')
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: no authentication is required. It says nothing about pagination mechanics, result caps, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core operation and the distinguishing pagination trait, then the access constraint. No filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description says nothing about what a page returns, page size, total counts, or how an agent knows it has reached the last page. For a paged search tool, that leaves a real gap, though the parameter schema and annotations cover the rest.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents page (1-indexed), query format, and the account label. The description adds no parameter-level meaning beyond the word 'pagination', so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search product templates') plus the distinguishing modifier 'with pagination', which separates it from siblings like search_product_templates and search_product_templates_grouped. It stops short of explicitly contrasting the paged vs. non-paged variants, but an agent can still identify the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance and never references the numerous sibling search/list variants (search_product_templates, search_product_templates_grouped, list_product_templates_paged). It states only that the endpoint is public, which is context, not selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_streamingSet streaming status to startedB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to started for specified services

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`services`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a concrete, non-annotation behavioral constraint: a 100 requests / 10 seconds per shop rate limit with a link to the rate-limiting guide. It still omits consequences of the action (e.g., what state change occurs for viewers), keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler; the rate-limit note earns its place. Structure is slightly off since the caveat is front-loaded ahead of the actual purpose, pushing the verb to the second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, zero-required, nested-object mutation with no output schema, the description covers purpose plus throttling but omits the lifecycle context an agent needs — that this begins an actual live broadcast, how it pairs with end_streaming, and how the payload/payload_file/body-flag alternatives relate. Annotations carry safety, so the gaps are moderate rather than severe.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so the schema already documents account, confirm, payload, payload_file, and the nested services shape. The description adds nothing about parameters — it does not explain the Twitch service object structure, the confirm flag semantics, or the mutually exclusive payload/body-flag modes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Sets streaming status to started for specified services.' An agent can distinguish this from end_streaming and get_streaming_status by the verb alone, but the description never names those siblings or clarifies the relationship in text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all — no mention of prerequisites, of when to prefer this over end_streaming/get_streaming_status, or of when starting a stream is inappropriate. 'For specified services' is scope, not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_shop_batchExecute reviewed shop effectsB

Destructive

Confirmed ordered effects; all validated/hash checked before first request. Stop on first failure with known and unattempted receipts; no retry, rollback or implicit continuation.

ParametersJSON Schema

Name	Required	Description
`tasks`	Yes	One to twenty exact ordered native effects. No signed receipts or mutable payload files. Cannot override account/confirm/output settings.
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`review_sha256`	Yes

TDQS

B3.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false, and openWorld=true, yet the description adds substantial behavior beyond them: validation and hash-checking before the first request, stop-on-first-failure semantics, known-vs-unattempted receipt reporting, and explicit no-retry/no-rollback/no-implicit-continuation guarantees. This is exactly the failure-mode context an agent needs before firing a destructive batch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with zero filler, and the safety-relevant failure behavior is front-loaded. It is efficient, though the subjectless fragments ('Confirmed ordered effects') are slightly cryptic for a standalone read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does address it via the 'known and unattempted receipts' outcome, plus failure and no-rollback semantics. It is nearly complete for a destructive batch tool; only the review_sha256 generation flow is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so the schema already documents tasks, account, and confirm; the description adds no field-level meaning beyond restating the validation/hash-check behavior. The undocumented review_sha256 (pattern only, no description) and its provenance are not explained, so the description does not compensate for the remaining coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title ('Execute reviewed shop effects') plus 'Confirmed ordered effects' conveys that this applies a pre-reviewed batch of shop mutations, but the description itself is a telegraphic fragment that never states the verb/resource outright. It also fails to differentiate from the obvious sibling preview_shop_batch, leaving the agent to infer the batch-execution role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no routing to the natural alternative, preview_shop_batch. The phrase 'Confirmed ordered effects' and the review_sha256 requirement hint that a prior review/confirmation step exists, but the description never tells the agent when this tool should be chosen over the preview step or a single-effect sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

toggle_product_availabilityUpdate product (offer) availability by idB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates a product (offer) availability

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`available`	No
`product_id`	Yes	Native productId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds genuinely useful context beyond that: a concrete rate limit of 100 requests / 10 seconds per shop. But it never explains what 'availability' means here (product vs offer), nor the side effects of taking an item unavailable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines with no filler; the rate limit constraint is front-loaded and the purpose follows. Nothing is wasted, though the sparseness arguably reflects under-specification rather than disciplined concision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with 6 parameters, a nested request body, and no output schema, the description is thin. It covers the rate limit but omits what happens on success/failure, whether 'confirm' is required, and how the payload and top-level fields interact. Annotations carry the safety profile, which keeps this at a minimum-viable 3.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, above the 80% threshold, so the schema already documents most parameters and the baseline is 3. The description adds no parameter meaning at all, and notably does not clarify the ambiguity between the top-level 'available' boolean and the nested 'payload.available', or the role of 'confirm'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Updates a product (offer) availability.' That is clear enough for an agent to know it mutates availability state. However, it does nothing to distinguish this tool from close siblings like update_product_state, archive_product, or update_collection_availability, so sibling differentiation is absent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no named alternative. The only contextual note is a rate limit, which is operational rather than a usage rule. An agent gets no help deciding between this and update_product_state or archive_product.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_collectionUpdate a collectionB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates collection name, description, and/or product list

ParametersJSON Schema

Name	Required	Description
`name`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`offerIds`	No	List of product IDs to set in the collection
`description`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`collection_id`	Yes	Native collectionId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description contributes the concrete rate limit (100 req/10s per shop), which is genuinely new context, but it does not disclose that supplying offerIds replaces the collection's product set or that the operation is non-idempotent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no waste, though the rate-limit line is placed ahead of the purpose statement, which slightly buries the front-loaded 'what it does'. Still efficient and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, 8-parameter mutation with no output schema, the description covers the basic mutation surface and rate limit but omits replace-vs-merge semantics for the product list and the meaning of confirm. Adequate but with clear gaps an agent would want filled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema handles most parameter documentation (payload, payload_file, confirm, collection_id). The description only restates the updatable fields and ignores the payload/payload_file mutual exclusion and the confirm flag, adding little beyond structured data — the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource plus the three mutable fields (name, description, product list), so the agent knows exactly what changes. It does not explicitly distinguish itself from near-name siblings like update_collection_products or update_collection_availability, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus its siblings (update_collection_products, update_collection_availability, create_collection) and no prerequisites or exclusions. Only a rate-limit note is given, which is operational context rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_collection_availabilityUpdate collection availabilityB

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Toggle collection availability (available/unavailable)

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`available`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`collection_id`	Yes	Native collectionId

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false, and openWorld=true, so the safety profile is largely covered. The description adds a genuinely useful behavioral fact the annotations do not carry: a rate limit of 100 requests / 10 seconds per shop. It does not, however, clarify the tension between 'toggle' and the explicit 'available' boolean, or what state the collection ends up in.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and free of filler, with no wasted sentences. The ordering is slightly off — the rate-limit meta-note is front-loaded ahead of the actual purpose — but the content is tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation tool with no output schema, the description covers the rate-limit constraint and nothing more. It omits when to use it versus related update/toggle siblings and leaves ambiguous whether the call toggles or sets the availability value, which matters given a dedicated 'available' parameter exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema largely documents its own parameters (payload, payload_file, confirm, account, collection_id). The description only gestures at 'available/unavailable', which loosely maps to the available parameter but adds no format or semantics beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Toggle collection availability (available/unavailable)'. An agent can distinguish it from most siblings. However, it does not name or differentiate itself from close siblings such as toggle_product_availability or update_collection, so it stops short of full sibling disambiguation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use or when-not-to-use guidance, and no alternative tool is named. The only extra content is a rate-limit note, which is a constraint rather than usage guidance. The agent must infer usage purely from the name and schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_collection_productsSet collection productsA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets the full list of product IDs in the collection

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`offerIds`	No	Full list of product IDs to set in the collection
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`collection_id`	Yes	Native collectionId

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds two genuinely new facts beyond the annotations: the 100 req/10s rate limit and the 'full list' replacement semantics (products not listed are dropped), which is meaningful for a destructive mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler, and the core action sentence is clear. Leading with the rate-limit callout before the purpose is slightly awkward ordering, but the content is tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with full annotation coverage and a fully documented schema, the description supplies the rate limit and replacement semantics an agent needs. It is missing only confirmation/auth implications, but nothing critical to correct invocation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including offerIds, payload, confirm and account is already documented in the schema. The description's 'full list of product IDs' merely echoes the offerIds schema text, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Sets') and resource ('the full list of product IDs in the collection'), and the word 'full' signals replacement rather than append. It does not name or contrast with the obvious sibling get_collection_products or update_collection, so the agent must infer which one to use, keeping it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this tool versus alternatives such as get_collection_products or update_collection, and no exclusions or prerequisites. The only supplementary context is a rate limit, which is a constraint rather than usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_gifting_configUpdate gifting configA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`enabled`	No	Master flag. Off pauses purchasability without losing the rest.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`products`	No
`shipping`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`entryTimeLimitSeconds`	No	Entry time limit in seconds. Validated 20-180.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, and the description reinforces this with real behavioral detail beyond the annotations: server-side validation (duration 20-180s), the one-platform-per-shop mutex, and upsert materialization of a missing row. One mild tension remains unaddressed: the description's 'Upserts / PUT' framing reads as idempotent while idempotentHint=false, and no failure behavior is described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded, followed by the enforcement and upsert caveats. No filler, every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-param, zero-required mutation with nested oneOf schemas and no output schema, the description covers the essentials an agent needs (write semantics, server-side validation, mutex constraint, upsert behavior). It could still say what happens on validation failure or what permissions the 'account' label requires.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema already documents the key fields. The description adds the useful grouping that the payload carries exactly four creator-controlled fields and restates the 20-180s validation, but it does not clarify the payload vs. payload_file vs. top-level flag exclusivity (left to the schema) or the nested products/shipping oneOf variants.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Writes the four creator-controlled gifting rule fields'), which clearly separates it from the read-only sibling get_gifting_config. It is clear but never names an alternative tool or explicitly scopes what 'the four fields' are beyond the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no stated when-to-use, when-not-to-use, or named alternative. The only contextual cue is the upsert note ('a first-ever PUT materializes the config row'), which hints at create-or-replace semantics but does not guide tool selection against siblings like update_promotion or create_gifting_checkout.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_product_stateUpdate product (offer) lifecycle stateA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

ParametersJSON Schema

Name	Required	Description
`state`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`product_id`	Yes	Native productId
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

TDQS

A3.5/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly claims 'Idempotent: no-op if the product is already in the requested state,' while the annotations declare idempotentHint=false — a direct, material conflict an agent could rely on to skip a repeat call or re-check state. It also frames the operation as a benign, reversible visibility flip while destructiveHint=true, though that tension is less clear-cut than the idempotency one.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, no filler, with the scope and exclusions laid out compactly. Leading with the rate limit rather than the operation itself is a mild front-loading miss, but everything stated earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers rate limits, the two alternate endpoints for adjacent concerns, state reachability, and flag preservation — a lot of what an agent needs for a 6-parameter mutation with no output schema. It is undermined somewhat by the false idempotency claim, and it leaves account/confirm/payload to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents state, account, confirm, and the payload variants, including the same PUBLIC/HIDDEN explanation. The description repeats the state semantics and availability-preservation note rather than adding new parameter-level meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — transitioning the product between PUBLIC and HIDDEN — and explicitly sets the boundary against two adjacent operations (archiving, availability toggling). An agent can tell this apart from archive_product and toggle_product_availability without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real when-to-use guidance by naming the alternatives: archive via DELETE /products/{productId} and sold-out flag via PUT /products/{productId}/availability, plus the non-reachable ARCHIVED state. Slightly short of 5 because it routes by raw HTTP path rather than by the sibling tool names (archive_product, toggle_product_availability) the agent actually sees.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_promotionUpdate a promotionA

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates an existing promotion's configuration. Only provided fields are updated; omitted fields remain unchanged. Status changes (activate/deactivate) are part of the same update call.

ParametersJSON Schema

Name	Required	Description
`limits`	No
`status`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`appliesTo`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`promotion_id`	Yes	Native promotionId
`requirements`	No

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds real behavior beyond the annotations: a concrete rate limit (100 req/10s per shop), partial-update semantics (omitted fields remain unchanged), and that status transitions ride along with the same call. It does not disclose irreversibility of status changes to ENDED or the mutual exclusivity of payload/payload_file/individual fields, which the schema partly covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the operational constraint and then the update semantics. No filler, though the rate-limit pointer occupies prime opening space that could have been shortened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter mutation tool with nested objects, no output schema, and a payload/payload_file/individual-field exclusivity rule, the description is thin. Annotations cover the safety profile and the description covers partial updates and rate limits, but the caller still has no guidance on which input mode to pick or on confirm/account usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 56%, so the schema documents several key params (account, confirm, payload, payload_file, promotion_id) but leaves limits, status, appliesTo, and requirements bare. The description's 'only provided fields are updated' implies optionality but adds no meaning about the dual-mode payload-vs-individual-fields interface, which is the schema's most confusing aspect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Updates an existing promotion's configuration') and the scope of a partial update. It is distinguishable from create_promotion and get_promotion by the verb, but it never names those siblings or explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line 'Status changes (activate/deactivate) are part of the same update call' implicitly tells the agent not to look for a separate activation tool, which is useful routing. However there is no explicit when-to-use/when-not guidance versus create_promotion, and no mention of prerequisites such as confirm or account.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_webhookUpdate a webhookC

Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Update a webhook

ParametersJSON Schema

Name	Required	Description
`url`	No
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete current native JSON body; cannot mix with native body flags or payload_file.
`allowedTypes`	No
`payload_file`	No	Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.
`webhook_configuration_id`	Yes	Native webhookConfigurationId

TDQS

C2.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The rate limit disclosure (100 requests / 10 seconds per shop) is genuine added value beyond the annotations. However, the description says nothing about the destructive nature of the update, whether omitted fields are preserved or cleared, or what confirmation semantics (the `confirm` parameter) mean in practice.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no padding, and the rate limit is front-loaded. But the second sentence is pure tautology against the title, so half the content earns no place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A destructive, non-idempotent mutation with 7 parameters, a nested payload object, and no output schema needs far more than a rate limit note. The description omits what is destroyed, how partial updates behave, and the exclusivity rules among the body parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 71%, so most parameters carry their own descriptions and the baseline is 3. The description adds nothing about the payload vs payload_file vs allowedTypes mutual-exclusion rules or the meaning of webhook_configuration_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says only "Update a webhook," which restates the tool name and title verbatim. It does not indicate what about a webhook can be updated (URL, event types) or distinguish this tool from create_webhook, delete_webhook, or get_webhook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus the sibling create_webhook, delete_webhook, or get_webhook. There is no mention of prerequisites, confirmation requirements, or conditions under which updating is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upload_fileUpload exact bytes from a private receiptA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`input_file`	Yes
`receipt_file`	Yes

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered; the description still adds real value by scoping the operation (Google Storage PUT, exact size/Content-Type and x-goog-content-length-range preserved, no credentials or redirects, no automatic registration/publishing). It omits what happens to an existing object at the target path, which matters given destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences that lead with the core action and then the constraints; little waste. The jargon ("private upload receipt", "bounded local regular file") is compact but slightly costly to parse on a first read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent write with no output schema and half the params undocumented, the definition covers safety boundaries but not the full invocation loop: receipt provenance, overwrite semantics, and failure behavior are all absent. Adequate to recognize the tool, thin for calling it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%: account and confirm are documented, while input_file and receipt_file carry no schema description. The description partially compensates by clarifying that the receipt is a selected private receipt and the input is a bounded local regular file, but it never says where a receipt comes from or what "bounded" means numerically, leaving the two required params under-specified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: an explicit PUT of exact bytes to Google Storage using a receipt plus a local file. The mechanics are clear, but it never names the siblings that produce the receipt (e.g. request_digital_file_upload_url, request_media_upload_url) or distinguishes itself from confirm_digital_file_upload, so an agent must infer the relationship.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Explicitly confirmed" and "a selected private upload receipt" imply a prerequisite receipt and a user-confirmation gate, but the description never says to call an upload-URL tool first or when this is preferable to confirm_digital_file_upload. Usage is implied rather than stated, and no exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_dnsValidate DNS recordsA

Destructive

Rate limit: 20 requests / minute per shop. See Rate limiting.

Triggers a live DNS validation by checking all configured records against actual DNS servers and updates their verification status

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Set true only when the user asked for exactly this action.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=true), and the description usefully reinforces this by stating it contacts actual external DNS servers and updates verification status. It also adds a concrete operational constraint the annotations lack: a 20 requests/minute per shop rate limit. It could go further on failure semantics, but against existing annotations this is solid added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no waste. The rate-limit disclaimer is front-loaded ahead of the functional sentence, which is slightly unfortunate for an agent skimming for purpose, but the overall footprint is tight and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description plus annotations cover what the agent needs: what it does, that it touches live external servers, that it mutates state, and a rate limit. For a two-param tool with full schema coverage and complete annotations, nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'account' and 'confirm' are already well documented in the schema, and the description adds nothing about them. That makes the baseline 3 appropriate — the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('triggers a live DNS validation') and resource ('all configured records'), plus the side effect ('updates their verification status'). This clearly reads as a mutation, distinguishing it in spirit from the read-only get_dns_status sibling, but it never names that sibling the way a 5 would.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied — the agent can infer this is the tool for re-checking records live, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. get_dns_status for reading the current state). The rate-limit note constrains cadence but is not routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

37 tool updatesv3.0.0Oct 7, 2026

Changedarchive_product1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedattach_product_images10 fields changed

addedInput schema / $defs

Added value: +{
+  "images": {
+    "description": "List of images to attach",
+    "items": {
+      "properties": {
+        "height": {
+          "description": "Image height in pixels",
+          "format": "int32",
+          "type": "integer"
+        },
+        "url": {
+          "description": "Image URL",
+          "type": "string"
+        },
+        "width": {
+          "description": "Image width in pixels",
+          "format": "int32",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "height",
+        "url",
+        "width"
+      ],
+      "title": "Image Input",
+      "type": "object"
+    },
+    "type": "array"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / images / $ref
```
Added value: +"#/$defs/images"
```
removedInput schema / properties / images / description
```
Removed value: -"List of images to attach"
```

removedInput schema / properties / images / items

Removed value: -{
-  "properties": {
-    "height": {
-      "description": "Image height in pixels",
-      "format": "int32",
-      "type": "integer"
-    },
-    "url": {
-      "description": "Image URL",
-      "type": "string"
-    },
-    "width": {
-      "description": "Image width in pixels",
-      "format": "int32",
-      "type": "integer"
-    }
-  },
-  "required": [
-    "height",
-    "url",
-    "width"
-  ],
-  "title": "Image Input",
-  "type": "object"
-}

removedInput schema / properties / images / type
```
Removed value: -"array"
```
addedInput schema / properties / payload / properties / images / $ref
```
Added value: +"#/$defs/images"
```
removedInput schema / properties / payload / properties / images / description
```
Removed value: -"List of images to attach"
```

removedInput schema / properties / payload / properties / images / items

Removed value: -{
-  "properties": {
-    "height": {
-      "description": "Image height in pixels",
-      "format": "int32",
-      "type": "integer"
-    },
-    "url": {
-      "description": "Image URL",
-      "type": "string"
-    },
-    "width": {
-      "description": "Image width in pixels",
-      "format": "int32",
-      "type": "integer"
-    }
-  },
-  "required": [
-    "height",
-    "url",
-    "width"
-  ],
-  "title": "Image Input",
-  "type": "object"
-}

removedInput schema / properties / payload / properties / images / type
```
Removed value: -"array"
```

Changedconfirm_digital_file_upload1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_collection1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_fulfillment20 fields changed

addedInput schema / $defs

Added value: +{
+  "Shipping_Label": {
+    "properties": {
+      "trackingCompany": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "trackingNumber": {
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "trackingCompany",
+      "trackingNumber"
+    ],
+    "title": "Shipping Label",
+    "type": "object"
+  },
+  "items": {
+    "items": {
+      "properties": {
+        "quantity": {
+          "format": "int32",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "variantId": {
+          "format": "uuid",
+          "type": "string"
+        }
+      },
+      "required": [
+        "quantity",
+        "variantId"
+      ],
+      "title": "Fulfillment Item",
+      "type": "object"
+    },
+    "minItems": 1,
+    "type": "array"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / items / $ref
```
Added value: +"#/$defs/items"
```

removedInput schema / properties / items / items

Removed value: -{
-  "properties": {
-    "quantity": {
-      "format": "int32",
-      "minimum": 1,
-      "type": "integer"
-    },
-    "variantId": {
-      "format": "uuid",
-      "type": "string"
-    }
-  },
-  "required": [
-    "quantity",
-    "variantId"
-  ],
-  "title": "Fulfillment Item",
-  "type": "object"
-}

removedInput schema / properties / items / minItems
```
Removed value: -1
```
removedInput schema / properties / items / type
```
Removed value: -"array"
```
addedInput schema / properties / payload / properties / items / $ref
```
Added value: +"#/$defs/items"
```

removedInput schema / properties / payload / properties / items / items

Removed value: -{
-  "properties": {
-    "quantity": {
-      "format": "int32",
-      "minimum": 1,
-      "type": "integer"
-    },
-    "variantId": {
-      "format": "uuid",
-      "type": "string"
-    }
-  },
-  "required": [
-    "quantity",
-    "variantId"
-  ],
-  "title": "Fulfillment Item",
-  "type": "object"
-}

removedInput schema / properties / payload / properties / items / minItems
```
Removed value: -1
```
removedInput schema / properties / payload / properties / items / type
```
Removed value: -"array"
```
addedInput schema / properties / payload / properties / shippingLabel / $ref
```
Added value: +"#/$defs/Shipping_Label"
```

removedInput schema / properties / payload / properties / shippingLabel / properties

Removed value: -{
-  "trackingCompany": {
-    "minLength": 1,
-    "type": "string"
-  },
-  "trackingNumber": {
-    "minLength": 1,
-    "type": "string"
-  }
-}

removedInput schema / properties / payload / properties / shippingLabel / required
```
Removed value: -[
-  "trackingCompany",
-  "trackingNumber"
-]
```
removedInput schema / properties / payload / properties / shippingLabel / title
```
Removed value: -"Shipping Label"
```
removedInput schema / properties / payload / properties / shippingLabel / type
```
Removed value: -"object"
```
addedInput schema / properties / shippingLabel / $ref
```
Added value: +"#/$defs/Shipping_Label"
```

removedInput schema / properties / shippingLabel / properties

Removed value: -{
-  "trackingCompany": {
-    "minLength": 1,
-    "type": "string"
-  },
-  "trackingNumber": {
-    "minLength": 1,
-    "type": "string"
-  }
-}

removedInput schema / properties / shippingLabel / required

Removed value: -[
-  "trackingCompany",
-  "trackingNumber"
-]

removedInput schema / properties / shippingLabel / title
```
Removed value: -"Shipping Label"
```
removedInput schema / properties / shippingLabel / type
```
Removed value: -"object"
```

Changedcreate_gifting_checkout10 fields changed

addedInput schema / $defs

Added value: +{
+  "currency": {
+    "description": "Display currency for the checkout. Defaults to the shop's currency.",
+    "enum": [
+      "USD",
+      "EUR",
+      "CAD",
+      "GBP",
+      "AUD",
+      "NZD",
+      "SEK",
+      "NOK",
+      "DKK",
+      "PLN",
+      "INR",
+      "JPY",
+      "MYR",
+      "SGD",
+      "MXN",
+      "BRL",
+      "CHF"
+    ],
+    "type": "string"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / currency / $ref
```
Added value: +"#/$defs/currency"
```

removedInput schema / properties / currency / description

Removed value: -"Display currency for the checkout. Defaults to the shop's currency."

removedInput schema / properties / currency / enum

Removed value: -[
-  "USD",
-  "EUR",
-  "CAD",
-  "GBP",
-  "AUD",
-  "NZD",
-  "SEK",
-  "NOK",
-  "DKK",
-  "PLN",
-  "INR",
-  "JPY",
-  "MYR",
-  "SGD",
-  "MXN",
-  "BRL",
-  "CHF"
-]

removedInput schema / properties / currency / type
```
Removed value: -"string"
```
addedInput schema / properties / payload / properties / currency / $ref
```
Added value: +"#/$defs/currency"
```

removedInput schema / properties / payload / properties / currency / description

Removed value: -"Display currency for the checkout. Defaults to the shop's currency."

removedInput schema / properties / payload / properties / currency / enum

Removed value: -[
-  "USD",
-  "EUR",
-  "CAD",
-  "GBP",
-  "AUD",
-  "NZD",
-  "SEK",
-  "NOK",
-  "DKK",
-  "PLN",
-  "INR",
-  "JPY",
-  "MYR",
-  "SGD",
-  "MXN",
-  "BRL",
-  "CHF"
-]

removedInput schema / properties / payload / properties / currency / type
```
Removed value: -"string"
```

Changedcreate_giveaway1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_giveaway_checkout1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_giveaway_links1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_product3 fields changed

addedInput schema / $defs

Added value: +{
+  "Create_Product_Request": {
+    "description": "Request to create a product. The shape is discriminated by the `type` field.",
+    "properties": {
+      "type": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "type"
+    ],
+    "title": "Create Product Request",
+    "type": "object"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

changedInput schema / properties / payload / oneOf

Previous value: -[
-  {
-    "allOf": [
-      {
-        "description": "Request to create a product. The shape is discriminated by the `type` field.",
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Create Product Request",
-        "type": "object"
-      },
-      {
-        "properties": {
-          "colors": {
-            "description": "Colors to render. Defaults to all available product colors when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied colors are available.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "description": {
-            "description": "Product description",
-            "type": "string"
-          },
-          "name": {
-            "description": "Product name",
-            "type": "string"
-          },
-          "productTemplateId": {
-            "description": "Id of the product template to render the design onto, from `GET /open-api/v1.0/product-templates`.",
-            "type": "string"
-          },
-          "profitMargin": {
-            "description": "Profit margin in USD applied on top of the base cost.",
-            "type": "number"
-          },
-          "publishOnCreate": {
-            "description": "Publish the product immediately on creation. Defaults to false (product stays hidden).",
-            "type": "boolean"
-          },
-          "regions": {
-            "description": "Design regions to place on the product. Each region references a registered media image by id (register it via `POST /open-api/v1.0/media/images` and pass the returned id as `imageId`).",
-            "items": {
-              "description": "A product region paired with the registered media image to render on it.",
-              "properties": {
-                "imageId": {
-                  "description": "Id of a registered media-library image to render on the region. Register the image first via `POST /open-api/v1.0/media/images` and pass the returned id here.",
-                  "type": "string"
-                },
-                "placementId": {
-                  "description": "Placement to target when `placementStrategy` is `PLACEMENT_ID`. Required for that strategy and ignored by the others.",
-                  "type": "string"
-                },
-                "placementStrategy": {
-                  "description": "How the image is placed on the region. Defaults to `AUTO` when omitted, and takes precedence over `placementId`/`fillAllPlacements`.\n- `AUTO` — let the renderer decide using the product's automation defaults (its preferred placement, or fill-all for products like mugs/stickers).\n- `FILL_ALL` — apply the image to every placement in the region.\n- `FULL_REGION` — render the image across the full region, skipping the preferred placement.\n- `PLACEMENT_ID` — target the single placement named by `placementId` (required for this strategy).",
-                  "enum": [
-                    "AUTO",
-                    "FILL_ALL",
-                    "FULL_REGION",
-                    "PLACEMENT_ID"
-                  ],
-                  "type": "string"
-                },
-                "region": {
-                  "description": "Name of the product region to place the image on, e.g. `front` or `back`.",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "imageId",
-                "region"
-              ],
-              "title": "Product Design Region",
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "sizes": {
-            "description": "Sizes to include. Defaults to all available product sizes when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied sizes are available. When both colors and sizes are supplied, the request is also rejected with 400 if no requested color/size combination is an available variant.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "design"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "description": "Create a product by running the design pipeline: renders each region's registered image into mockups and creates a purchasable product. The product is created hidden unless `publishOnCreate` is true.",
-    "required": [
-      "name",
-      "productTemplateId",
-      "regions",
-      "type"
-    ],
-    "title": "Create Design Product Request"
-  },
-  {
-    "allOf": [
-      {
-        "description": "Request to create a product. The shape is discriminated by the `type` field.",
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Create Product Request",
-        "type": "object"
-      },
-      {
-        "properties": {
-          "description": {
-            "description": "Product description",
-            "type": "string"
-          },
-          "name": {
-            "description": "Product name",
-            "type": "string"
-          },
-          "price": {
-            "description": "Price set by the creator, in USD.",
-            "type": "number"
-          },
-          "publishOnCreate": {
-            "description": "Publish the product immediately on creation. Defaults to false (product stays hidden).",
-            "type": "boolean"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "digital"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "description": "Create a digital product with a creator-set price in USD and digital fulfillment. Attach files and images via the /products/{productId}/digital-files and /products/{productId}/images endpoints.",
-    "required": [
-      "description",
-      "name",
-      "price",
-      "type"
-    ],
-    "title": "Create Digital Product Request"
-  }
-]New value: +[
+  {
+    "allOf": [
+      {
+        "$ref": "#/$defs/Create_Product_Request"
+      },
+      {
+        "properties": {
+          "colors": {
+            "description": "Colors to render. Defaults to all available product colors when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied colors are available.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "description": {
+            "description": "Product description",
+            "type": "string"
+          },
+          "name": {
+            "description": "Product name",
+            "type": "string"
+          },
+          "productTemplateId": {
+            "description": "Id of the product template to render the design onto, from `GET /open-api/v1.0/product-templates`.",
+            "type": "string"
+          },
+          "profitMargin": {
+            "description": "Profit margin in USD applied on top of the base cost.",
+            "type": "number"
+          },
+          "publishOnCreate": {
+            "description": "Publish the product immediately on creation. Defaults to false (product stays hidden).",
+            "type": "boolean"
+          },
+          "regions": {
+            "description": "Design regions to place on the product. Each region references a registered media image by id (register it via `POST /open-api/v1.0/media/images` and pass the returned id as `imageId`).",
+            "items": {
+              "description": "A product region paired with the registered media image to render on it.",
+              "properties": {
+                "imageId": {
+                  "description": "Id of a registered media-library image to render on the region. Register the image first via `POST /open-api/v1.0/media/images` and pass the returned id here.",
+                  "type": "string"
+                },
+                "placementId": {
+                  "description": "Placement to target when `placementStrategy` is `PLACEMENT_ID`. Required for that strategy and ignored by the others.",
+                  "type": "string"
+                },
+                "placementStrategy": {
+                  "description": "How the image is placed on the region. Defaults to `AUTO` when omitted, and takes precedence over `placementId`/`fillAllPlacements`.\n- `AUTO` — let the renderer decide using the product's automation defaults (its preferred placement, or fill-all for products like mugs/stickers).\n- `FILL_ALL` — apply the image to every placement in the region.\n- `FULL_REGION` — render the image across the full region, skipping the preferred placement.\n- `PLACEMENT_ID` — target the single placement named by `placementId` (required for this strategy).",
+                  "enum": [
+                    "AUTO",
+                    "FILL_ALL",
+                    "FULL_REGION",
+                    "PLACEMENT_ID"
+                  ],
+                  "type": "string"
+                },
+                "region": {
+                  "description": "Name of the product region to place the image on, e.g. `front` or `back`.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "imageId",
+                "region"
+              ],
+              "title": "Product Design Region",
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "sizes": {
+            "description": "Sizes to include. Defaults to all available product sizes when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied sizes are available. When both colors and sizes are supplied, the request is also rejected with 400 if no requested color/size combination is an available variant.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "properties": {
+          "type": {
+            "const": "design"
+          }
+        },
+        "type": "object"
+      }
+    ],
+    "description": "Create a product by running the design pipeline: renders each region's registered image into mockups and creates a purchasable product. The product is created hidden unless `publishOnCreate` is true.",
+    "required": [
+      "name",
+      "productTemplateId",
+      "regions",
+      "type"
+    ],
+    "title": "Create Design Product Request"
+  },
+  {
+    "allOf": [
+      {
+        "$ref": "#/$defs/Create_Product_Request"
+      },
+      {
+        "properties": {
+          "description": {
+            "description": "Product description",
+            "type": "string"
+          },
+          "name": {
+            "description": "Product name",
+            "type": "string"
+          },
+          "price": {
+            "description": "Price set by the creator, in USD.",
+            "type": "number"
+          },
+          "publishOnCreate": {
+            "description": "Publish the product immediately on creation. Defaults to false (product stays hidden).",
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "properties": {
+          "type": {
+            "const": "digital"
+          }
+        },
+        "type": "object"
+      }
+    ],
+    "description": "Create a digital product with a creator-set price in USD and digital fulfillment. Attach files and images via the /products/{productId}/digital-files and /products/{productId}/images endpoints.",
+    "required": [
+      "description",
+      "name",
+      "price",
+      "type"
+    ],
+    "title": "Create Digital Product Request"
+  }
+]

Changedcreate_promotion3 fields changed

addedInput schema / $defs

Added value: +{
+  "Open_Api_Promotion_Selected_Products": {
+    "properties": {
+      "oncePerOrder": {
+        "type": "boolean"
+      },
+      "productIds": {
+        "items": {
+          "format": "uuid",
+          "type": "string"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "productIds"
+    ],
+    "title": "Open Api Promotion Selected Products",
+    "type": "object"
+  },
+  "Shop": {
+    "properties": {
+      "minimumOrderValue": {
+        "properties": {
+          "currency": {
+            "type": "string"
+          },
+          "value": {
+            "minimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "currency",
+          "value"
+        ],
+        "title": "Money",
+        "type": "object"
+      }
+    },
+    "title": "Shop",
+    "type": "object"
+  },
+  "discount": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Shop"
+          },
+          {
+            "properties": {
+              "freeShipping": {
+                "type": "boolean"
+              },
+              "money": {
+                "properties": {
+                  "currency": {
+                    "type": "string"
+                  },
+                  "value": {
+                    "minimum": 0,
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "currency",
+                  "value"
+                ],
+                "title": "Money",
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "FLAT_RATE",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "freeShipping",
+          "money"
+        ],
+        "title": "Fixed Amount"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Shop"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "FREE_SHIPPING",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "Free Shipping"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Shop"
+          },
+          {
+            "properties": {
+              "percentage": {
+                "type": "number"
+              },
+              "shipping": {
+                "enum": [
+                  "Excluded",
+                  "Included",
+                  "FreeLowestOnly",
+                  "Free"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "PERCENTAGE",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "percentage",
+          "shipping"
+        ],
+        "title": "Percentage"
+      }
+    ]
+  },
+  "discount_2": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Memberships"
+          },
+          {
+            "properties": {
+              "percentage": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "PERCENTAGE",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "percentage"
+        ],
+        "title": "Percentage"
+      }
+    ]
+  },
+  "subscriptionType": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Open Api Promotion Membership Subscription Type Applies To"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "ALL",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "All Members"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Open Api Promotion Membership Subscription Type Applies To"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "ANNUAL",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "Annual Members Only"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Open Api Promotion Membership Subscription Type Applies To"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "MONTHLY",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "Monthly Members Only"
+      }
+    ]
+  },
+  "tiers": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Open Api Promotion Membership Tiers Applies To"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "ALL",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "All Tiers"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Open Api Promotion Membership Tiers Applies To"
+          },
+          {
+            "properties": {
+              "ids": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "SELECTED",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "ids"
+        ],
+        "title": "Selected Tiers"
+      }
+    ]
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

changedInput schema / properties / payload / oneOf

Previous value: -[
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Open Api Create Promotion Request"
-      },
-      {
-        "properties": {
-          "codes": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "discount": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Memberships"
-                  },
-                  {
-                    "properties": {
-                      "percentage": {
-                        "type": "number"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "PERCENTAGE",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "percentage"
-                ],
-                "title": "Percentage"
-              }
-            ]
-          },
-          "requirements": {
-            "properties": {
-              "newMembersOnly": {
-                "type": "boolean"
-              }
-            },
-            "required": [
-              "newMembersOnly"
-            ],
-            "title": "Memberships",
-            "type": "object"
-          },
-          "subscriptionType": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Subscription Type Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "ALL",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "All Members"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Subscription Type Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "ANNUAL",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "Annual Members Only"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Subscription Type Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "MONTHLY",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "Monthly Members Only"
-              }
-            ]
-          },
-          "tiers": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Tiers Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "ALL",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "All Tiers"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Tiers Applies To"
-                  },
-                  {
-                    "properties": {
-                      "ids": {
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "SELECTED",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "ids"
-                ],
-                "title": "Selected Tiers"
-              }
-            ]
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "MEMBERSHIPS_MULTI",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "codes",
-      "discount"
-    ],
-    "title": "MEMBERSHIPS_MULTI"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Open Api Create Promotion Request"
-      },
-      {
-        "properties": {
-          "code": {
-            "type": "string"
-          },
-          "discount": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Memberships"
-                  },
-                  {
-                    "properties": {
-                      "percentage": {
-                        "type": "number"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "PERCENTAGE",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "percentage"
-                ],
-                "title": "Percentage"
-              }
-            ]
-          },
-          "requirements": {
-            "properties": {
-              "newMembersOnly": {
-                "type": "boolean"
-              }
-            },
-            "required": [
-              "newMembersOnly"
-            ],
-            "title": "Memberships",
-            "type": "object"
-          },
-          "subscriptionType": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Subscription Type Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "ALL",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "All Members"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Subscription Type Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "ANNUAL",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "Annual Members Only"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Subscription Type Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "MONTHLY",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "Monthly Members Only"
-              }
-            ]
-          },
-          "tiers": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Tiers Applies To"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "ALL",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "All Tiers"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Open Api Promotion Membership Tiers Applies To"
-                  },
-                  {
-                    "properties": {
-                      "ids": {
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "SELECTED",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "ids"
-                ],
-                "title": "Selected Tiers"
-              }
-            ]
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "MEMBERSHIPS_SINGLE",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "code",
-      "discount"
-    ],
-    "title": "MEMBERSHIPS_SINGLE"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Open Api Create Promotion Request"
-      },
-      {
-        "properties": {
-          "appliesToProducts": {
-            "properties": {
-              "oncePerOrder": {
-                "type": "boolean"
-              },
-              "productIds": {
-                "items": {
-                  "format": "uuid",
-                  "type": "string"
-                },
-                "type": "array"
-              }
-            },
-            "required": [
-              "productIds"
-            ],
-            "title": "Open Api Promotion Selected Products",
-            "type": "object"
-          },
-          "codes": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "discount": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Shop"
-                  },
-                  {
-                    "properties": {
-                      "freeShipping": {
-                        "type": "boolean"
-                      },
-                      "money": {
-                        "properties": {
-                          "currency": {
-                            "type": "string"
-                          },
-                          "value": {
-                            "minimum": 0,
-                            "type": "number"
-                          }
-                        },
-                        "required": [
-                          "currency",
-                          "value"
-                        ],
-                        "title": "Money",
-                        "type": "object"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "FLAT_RATE",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "freeShipping",
-                  "money"
-                ],
-                "title": "Fixed Amount"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Shop"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "FREE_SHIPPING",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "Free Shipping"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Shop"
-                  },
-                  {
-                    "properties": {
-                      "percentage": {
-                        "type": "number"
-                      },
-                      "shipping": {
-                        "enum": [
-                          "Excluded",
-                          "Included",
-                          "FreeLowestOnly",
-                          "Free"
-                        ],
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "PERCENTAGE",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "percentage",
-                  "shipping"
-                ],
-                "title": "Percentage"
-              }
-            ]
-          },
-          "limits": {
-            "properties": {
-              "maximumUse": {
-                "format": "int32",
-                "type": "integer"
-              },
-              "oneUsePerCustomer": {
-                "type": "boolean"
-              }
-            },
-            "required": [
-              "oneUsePerCustomer"
-            ],
-            "title": "Open Api Promotion Limits",
-            "type": "object"
-          },
-          "requirements": {
-            "properties": {
-              "minimumOrderValue": {
-                "properties": {
-                  "currency": {
-                    "type": "string"
-                  },
-                  "value": {
-                    "minimum": 0,
-                    "type": "number"
-                  }
-                },
-                "required": [
-                  "currency",
-                  "value"
-                ],
-                "title": "Money",
-                "type": "object"
-              }
-            },
-            "title": "Shop",
-            "type": "object"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "SHOP_MULTI",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "codes",
-      "discount"
-    ],
-    "title": "SHOP_MULTI"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Open Api Create Promotion Request"
-      },
-      {
-        "properties": {
-          "appliesToProducts": {
-            "properties": {
-              "oncePerOrder": {
-                "type": "boolean"
-              },
-              "productIds": {
-                "items": {
-                  "format": "uuid",
-                  "type": "string"
-                },
-                "type": "array"
-              }
-            },
-            "required": [
-              "productIds"
-            ],
-            "title": "Open Api Promotion Selected Products",
-            "type": "object"
-          },
-          "code": {
-            "type": "string"
-          },
-          "discount": {
-            "oneOf": [
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Shop"
-                  },
-                  {
-                    "properties": {
-                      "freeShipping": {
-                        "type": "boolean"
-                      },
-                      "money": {
-                        "properties": {
-                          "currency": {
-                            "type": "string"
-                          },
-                          "value": {
-                            "minimum": 0,
-                            "type": "number"
-                          }
-                        },
-                        "required": [
-                          "currency",
-                          "value"
-                        ],
-                        "title": "Money",
-                        "type": "object"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "FLAT_RATE",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "freeShipping",
-                  "money"
-                ],
-                "title": "Fixed Amount"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Shop"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "FREE_SHIPPING",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "title": "Free Shipping"
-              },
-              {
-                "allOf": [
-                  {
-                    "properties": {
-                      "type": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "type"
-                    ],
-                    "title": "Shop"
-                  },
-                  {
-                    "properties": {
-                      "percentage": {
-                        "type": "number"
-                      },
-                      "shipping": {
-                        "enum": [
-                          "Excluded",
-                          "Included",
-                          "FreeLowestOnly",
-                          "Free"
-                        ],
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "properties": {
-                      "type": {
-                        "const": "PERCENTAGE",
-                        "type": "string"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ],
-                "required": [
-                  "percentage",
-                  "shipping"
-                ],
-                "title": "Percentage"
-              }
-            ]
-          },
-          "limits": {
-            "properties": {
-              "maximumUse": {
-                "format": "int32",
-                "type": "integer"
-              },
-              "oneUsePerCustomer": {
-                "type": "boolean"
-              }
-            },
-            "required": [
-              "oneUsePerCustomer"
-            ],
-            "title": "Open Api Promotion Limits",
-            "type": "object"
-          },
-          "requirements": {
-            "properties": {
-              "minimumOrderValue": {
-                "properties": {
-                  "currency": {
-                    "type": "string"
-                  },
-                  "value": {
-                    "minimum": 0,
-                    "type": "number"
-                  }
-                },
-                "required": [
-                  "currency",
-                  "value"
-                ],
-                "title": "Money",
-                "type": "object"
-              }
-            },
-            "title": "Shop",
-            "type": "object"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "SHOP_SINGLE",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "code",
-      "discount"
-    ],
-    "title": "SHOP_SINGLE"
-  }
-]New value: +[
+  {
+    "allOf": [
+      {
+        "properties": {
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "title": "Open Api Create Promotion Request"
+      },
+      {
+        "properties": {
+          "codes": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "discount": {
+            "$ref": "#/$defs/discount_2"
+          },
+          "requirements": {
+            "properties": {
+              "newMembersOnly": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "newMembersOnly"
+            ],
+            "title": "Memberships",
+            "type": "object"
+          },
+          "subscriptionType": {
+            "$ref": "#/$defs/subscriptionType"
+          },
+          "tiers": {
+            "$ref": "#/$defs/tiers"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "properties": {
+          "type": {
+            "const": "MEMBERSHIPS_MULTI",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    ],
+    "required": [
+      "codes",
+      "discount"
+    ],
+    "title": "MEMBERSHIPS_MULTI"
+  },
+  {
+    "allOf": [
+      {
+        "properties": {
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "title": "Open Api Create Promotion Request"
+      },
+      {
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "discount": {
+            "$ref": "#/$defs/discount_2"
+          },
+          "requirements": {
+            "properties": {
+              "newMembersOnly": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "newMembersOnly"
+            ],
+            "title": "Memberships",
+            "type": "object"
+          },
+          "subscriptionType": {
+            "$ref": "#/$defs/subscriptionType"
+          },
+          "tiers": {
+            "$ref": "#/$defs/tiers"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "properties": {
+          "type": {
+            "const": "MEMBERSHIPS_SINGLE",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    ],
+    "required": [
+      "code",
+      "discount"
+    ],
+    "title": "MEMBERSHIPS_SINGLE"
+  },
+  {
+    "allOf": [
+      {
+        "properties": {
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "title": "Open Api Create Promotion Request"
+      },
+      {
+        "properties": {
+          "appliesToProducts": {
+            "$ref": "#/$defs/Open_Api_Promotion_Selected_Products"
+          },
+          "codes": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "discount": {
+            "$ref": "#/$defs/discount"
+          },
+          "limits": {
+            "properties": {
+              "maximumUse": {
+                "format": "int32",
+                "type": "integer"
+              },
+              "oneUsePerCustomer": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "oneUsePerCustomer"
+            ],
+            "title": "Open Api Promotion Limits",
+            "type": "object"
+          },
+          "requirements": {
+            "$ref": "#/$defs/Shop"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "properties": {
+          "type": {
+            "const": "SHOP_MULTI",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    ],
+    "required": [
+      "codes",
+      "discount"
+    ],
+    "title": "SHOP_MULTI"
+  },
+  {
+    "allOf": [
+      {
+        "properties": {
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "title": "Open Api Create Promotion Request"
+      },
+      {
+        "properties": {
+          "appliesToProducts": {
+            "$ref": "#/$defs/Open_Api_Promotion_Selected_Products"
+          },
+          "code": {
+            "type": "string"
+          },
+          "discount": {
+            "$ref": "#/$defs/discount"
+          },
+          "limits": {
+            "properties": {
+              "maximumUse": {
+                "format": "int32",
+                "type": "integer"
+              },
+              "oneUsePerCustomer": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "oneUsePerCustomer"
+            ],
+            "title": "Open Api Promotion Limits",
+            "type": "object"
+          },
+          "requirements": {
+            "$ref": "#/$defs/Shop"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "properties": {
+          "type": {
+            "const": "SHOP_SINGLE",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    ],
+    "required": [
+      "code",
+      "discount"
+    ],
+    "title": "SHOP_SINGLE"
+  }
+]

Changedcreate_webhook8 fields changed

addedInput schema / $defs

Added value: +{
+  "allowedTypes": {
+    "items": {
+      "enum": [
+        "ORDER_PLACED",
+        "ORDER_UPDATED",
+        "GIFT_PURCHASE",
+        "PRODUCT_CREATED",
+        "PRODUCT_UPDATED",
+        "DONATION",
+        "SUBSCRIPTION_PURCHASED",
+        "SUBSCRIPTION_EXPIRED",
+        "SUBSCRIPTION_CHANGED",
+        "NEWSLETTER_SUBSCRIBED",
+        "THANK_YOU_SENT",
+        "GIFT_DRAW_STARTED",
+        "GIFT_DRAW_ENDED",
+        "PROMOTION_CREATED",
+        "PROMOTION_UPDATED",
+        "PROMOTION_STATUS_CHANGED",
+        "PLATFORM_APP_DISCONNECTED",
+        "MEMBERSHIP_POST_UPSERTED",
+        "MEMBERSHIP_SERIES_UPSERTED",
+        "MEMBERSHIP_SERIES_DELETED",
+        "MEMBERSHIP_TAG_CREATED",
+        "MEMBERSHIP_TAG_UPDATED",
+        "MEMBERSHIP_TAG_DELETED",
+        "MEMBERSHIP_TIER_UPSERTED",
+        "MEMBERSHIP_TIER_DELETED",
+        "COLLECTION_UPDATED",
+        "CART_ABANDONED_1H",
+        "CART_ABANDONED_24H",
+        "CART_ABANDONED_72H"
+      ],
+      "type": "string"
+    },
+    "type": "array"
+  }
+}

addedInput schema / properties / allowedTypes / $ref
```
Added value: +"#/$defs/allowedTypes"
```

removedInput schema / properties / allowedTypes / items

Removed value: -{
-  "enum": [
-    "ORDER_PLACED",
-    "ORDER_UPDATED",
-    "GIFT_PURCHASE",
-    "PRODUCT_CREATED",
-    "PRODUCT_UPDATED",
-    "DONATION",
-    "SUBSCRIPTION_PURCHASED",
-    "SUBSCRIPTION_EXPIRED",
-    "SUBSCRIPTION_CHANGED",
-    "NEWSLETTER_SUBSCRIBED",
-    "THANK_YOU_SENT",
-    "GIFT_DRAW_STARTED",
-    "GIFT_DRAW_ENDED",
-    "PROMOTION_CREATED",
-    "PROMOTION_UPDATED",
-    "PROMOTION_STATUS_CHANGED",
-    "PLATFORM_APP_DISCONNECTED",
-    "MEMBERSHIP_POST_UPSERTED",
-    "MEMBERSHIP_SERIES_UPSERTED",
-    "MEMBERSHIP_SERIES_DELETED",
-    "MEMBERSHIP_TAG_CREATED",
-    "MEMBERSHIP_TAG_UPDATED",
-    "MEMBERSHIP_TAG_DELETED",
-    "MEMBERSHIP_TIER_UPSERTED",
-    "MEMBERSHIP_TIER_DELETED",
-    "COLLECTION_UPDATED",
-    "CART_ABANDONED_1H",
-    "CART_ABANDONED_24H",
-    "CART_ABANDONED_72H"
-  ],
-  "type": "string"
-}

removedInput schema / properties / allowedTypes / type
```
Removed value: -"array"
```

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / allowedTypes / $ref
```
Added value: +"#/$defs/allowedTypes"
```

removedInput schema / properties / payload / properties / allowedTypes / items

Removed value: -{
-  "enum": [
-    "ORDER_PLACED",
-    "ORDER_UPDATED",
-    "GIFT_PURCHASE",
-    "PRODUCT_CREATED",
-    "PRODUCT_UPDATED",
-    "DONATION",
-    "SUBSCRIPTION_PURCHASED",
-    "SUBSCRIPTION_EXPIRED",
-    "SUBSCRIPTION_CHANGED",
-    "NEWSLETTER_SUBSCRIBED",
-    "THANK_YOU_SENT",
-    "GIFT_DRAW_STARTED",
-    "GIFT_DRAW_ENDED",
-    "PROMOTION_CREATED",
-    "PROMOTION_UPDATED",
-    "PROMOTION_STATUS_CHANGED",
-    "PLATFORM_APP_DISCONNECTED",
-    "MEMBERSHIP_POST_UPSERTED",
-    "MEMBERSHIP_SERIES_UPSERTED",
-    "MEMBERSHIP_SERIES_DELETED",
-    "MEMBERSHIP_TAG_CREATED",
-    "MEMBERSHIP_TAG_UPDATED",
-    "MEMBERSHIP_TAG_DELETED",
-    "MEMBERSHIP_TIER_UPSERTED",
-    "MEMBERSHIP_TIER_DELETED",
-    "COLLECTION_UPDATED",
-    "CART_ABANDONED_1H",
-    "CART_ABANDONED_24H",
-    "CART_ABANDONED_72H"
-  ],
-  "type": "string"
-}

removedInput schema / properties / payload / properties / allowedTypes / type
```
Removed value: -"array"
```

Changeddelete_webhook1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changeddisable_giveaway_checkout1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedend_streaming1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedexport_resources1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedfinish_giveaway1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedfinish_giveaway_draw8 fields changed

addedInput schema / $defs

Added value: +{
+  "participants": {
+    "items": {
+      "oneOf": [
+        {
+          "allOf": [
+            {
+              "properties": {
+                "service": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "service"
+              ],
+              "title": "Participant"
+            },
+            {
+              "properties": {
+                "userId": {
+                  "type": "string"
+                },
+                "userName": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            }
+          ],
+          "required": [
+            "userId",
+            "userName"
+          ],
+          "title": "Twitch"
+        }
+      ]
+    },
+    "type": "array"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / participants / $ref
```
Added value: +"#/$defs/participants"
```

removedInput schema / properties / participants / items

Removed value: -{
-  "oneOf": [
-    {
-      "allOf": [
-        {
-          "properties": {
-            "service": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "service"
-          ],
-          "title": "Participant"
-        },
-        {
-          "properties": {
-            "userId": {
-              "type": "string"
-            },
-            "userName": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        }
-      ],
-      "required": [
-        "userId",
-        "userName"
-      ],
-      "title": "Twitch"
-    }
-  ]
-}

removedInput schema / properties / participants / type
```
Removed value: -"array"
```
addedInput schema / properties / payload / properties / participants / $ref
```
Added value: +"#/$defs/participants"
```

removedInput schema / properties / payload / properties / participants / items

Removed value: -{
-  "oneOf": [
-    {
-      "allOf": [
-        {
-          "properties": {
-            "service": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "service"
-          ],
-          "title": "Participant"
-        },
-        {
-          "properties": {
-            "userId": {
-              "type": "string"
-            },
-            "userName": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        }
-      ],
-      "required": [
-        "userId",
-        "userName"
-      ],
-      "title": "Twitch"
-    }
-  ]
-}

removedInput schema / properties / payload / properties / participants / type
```
Removed value: -"array"
```

Changedget_public_token1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedmark_download_complete1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedremove_digital_file1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedremove_product_images1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedrequest_digital_file_upload_url1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedrequest_media_upload_url1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedsave_media_image1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedstart_streaming8 fields changed

addedInput schema / $defs

Added value: +{
+  "services": {
+    "items": {
+      "oneOf": [
+        {
+          "allOf": [
+            {
+              "properties": {
+                "type": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type"
+              ],
+              "title": "Service"
+            },
+            {
+              "properties": {
+                "broadcasterId": {
+                  "type": "string"
+                },
+                "broadcasterLogin": {
+                  "type": "string"
+                },
+                "thumbnailUrl": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            }
+          ],
+          "required": [
+            "broadcasterId",
+            "broadcasterLogin"
+          ],
+          "title": "Twitch"
+        }
+      ]
+    },
+    "type": "array"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / services / $ref
```
Added value: +"#/$defs/services"
```

removedInput schema / properties / payload / properties / services / items

Removed value: -{
-  "oneOf": [
-    {
-      "allOf": [
-        {
-          "properties": {
-            "type": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "type"
-          ],
-          "title": "Service"
-        },
-        {
-          "properties": {
-            "broadcasterId": {
-              "type": "string"
-            },
-            "broadcasterLogin": {
-              "type": "string"
-            },
-            "thumbnailUrl": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        }
-      ],
-      "required": [
-        "broadcasterId",
-        "broadcasterLogin"
-      ],
-      "title": "Twitch"
-    }
-  ]
-}

removedInput schema / properties / payload / properties / services / type
```
Removed value: -"array"
```
addedInput schema / properties / services / $ref
```
Added value: +"#/$defs/services"
```

removedInput schema / properties / services / items

Removed value: -{
-  "oneOf": [
-    {
-      "allOf": [
-        {
-          "properties": {
-            "type": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "type"
-          ],
-          "title": "Service"
-        },
-        {
-          "properties": {
-            "broadcasterId": {
-              "type": "string"
-            },
-            "broadcasterLogin": {
-              "type": "string"
-            },
-            "thumbnailUrl": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        }
-      ],
-      "required": [
-        "broadcasterId",
-        "broadcasterLogin"
-      ],
-      "title": "Twitch"
-    }
-  ]
-}

removedInput schema / properties / services / type
```
Removed value: -"array"
```

Changedsubmit_shop_batch1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedtoggle_product_availability1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_collection1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_collection_availability1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_collection_products1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_gifting_config10 fields changed

addedInput schema / $defs

Added value: +{
+  "products": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Products Policy X Request"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "ALL",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "All Products"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Products Policy X Request"
+          },
+          {
+            "properties": {
+              "offerIds": {
+                "items": {
+                  "format": "uuid",
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "EXCLUDED",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "offerIds"
+        ],
+        "title": "Excluded Products"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Products Policy X Request"
+          },
+          {
+            "properties": {
+              "offerIds": {
+                "items": {
+                  "format": "uuid",
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "SELECTED",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "offerIds"
+        ],
+        "title": "Selected Products"
+      }
+    ]
+  },
+  "shipping": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Shipping Policy X Request"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "ALL_CREATOR",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "All Creator"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Shipping Policy X Request"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "ALL_WINNER",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "title": "All Winner"
+      },
+      {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "title": "Shipping Policy X Request"
+          },
+          {
+            "properties": {
+              "max": {
+                "format": "double",
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "properties": {
+              "type": {
+                "const": "MAX_CREATOR",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "max"
+        ],
+        "title": "Max Creator"
+      }
+    ]
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / products / $ref
```
Added value: +"#/$defs/products"
```

removedInput schema / properties / payload / properties / products / oneOf

Removed value: -[
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Products Policy X Request"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "ALL",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "title": "All Products"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Products Policy X Request"
-      },
-      {
-        "properties": {
-          "offerIds": {
-            "items": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "EXCLUDED",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "offerIds"
-    ],
-    "title": "Excluded Products"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Products Policy X Request"
-      },
-      {
-        "properties": {
-          "offerIds": {
-            "items": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "SELECTED",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "offerIds"
-    ],
-    "title": "Selected Products"
-  }
-]

addedInput schema / properties / payload / properties / shipping / $ref
```
Added value: +"#/$defs/shipping"
```

removedInput schema / properties / payload / properties / shipping / oneOf

Removed value: -[
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Shipping Policy X Request"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "ALL_CREATOR",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "title": "All Creator"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Shipping Policy X Request"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "ALL_WINNER",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "title": "All Winner"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Shipping Policy X Request"
-      },
-      {
-        "properties": {
-          "max": {
-            "format": "double",
-            "type": "number"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "MAX_CREATOR",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "max"
-    ],
-    "title": "Max Creator"
-  }
-]

addedInput schema / properties / products / $ref
```
Added value: +"#/$defs/products"
```

removedInput schema / properties / products / oneOf

Removed value: -[
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Products Policy X Request"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "ALL",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "title": "All Products"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Products Policy X Request"
-      },
-      {
-        "properties": {
-          "offerIds": {
-            "items": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "EXCLUDED",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "offerIds"
-    ],
-    "title": "Excluded Products"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Products Policy X Request"
-      },
-      {
-        "properties": {
-          "offerIds": {
-            "items": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "SELECTED",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "offerIds"
-    ],
-    "title": "Selected Products"
-  }
-]

addedInput schema / properties / shipping / $ref
```
Added value: +"#/$defs/shipping"
```

removedInput schema / properties / shipping / oneOf

Removed value: -[
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Shipping Policy X Request"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "ALL_CREATOR",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "title": "All Creator"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Shipping Policy X Request"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "ALL_WINNER",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "title": "All Winner"
-  },
-  {
-    "allOf": [
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "type"
-        ],
-        "title": "Shipping Policy X Request"
-      },
-      {
-        "properties": {
-          "max": {
-            "format": "double",
-            "type": "number"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "properties": {
-          "type": {
-            "const": "MAX_CREATOR",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "max"
-    ],
-    "title": "Max Creator"
-  }
-]

Changedupdate_product_state10 fields changed

addedInput schema / $defs

Added value: +{
+  "state": {
+    "description": "Target lifecycle state. `PUBLIC` makes the product visible on the storefront; `HIDDEN` keeps it unlisted. The sold-out (`available`) flag is preserved across the transition — use `PUT /products/{productId}/availability` to flip it.",
+    "enum": [
+      "PUBLIC",
+      "HIDDEN"
+    ],
+    "type": "string"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / state / $ref
```
Added value: +"#/$defs/state"
```

removedInput schema / properties / payload / properties / state / description

Removed value: -"Target lifecycle state. `PUBLIC` makes the product visible on the storefront; `HIDDEN` keeps it unlisted. The sold-out (`available`) flag is preserved across the transition — use `PUT /products/{productId}/availability` to flip it."

removedInput schema / properties / payload / properties / state / enum
```
Removed value: -[
-  "PUBLIC",
-  "HIDDEN"
-]
```
removedInput schema / properties / payload / properties / state / type
```
Removed value: -"string"
```
addedInput schema / properties / state / $ref
```
Added value: +"#/$defs/state"
```

removedInput schema / properties / state / description

Removed value: -"Target lifecycle state. `PUBLIC` makes the product visible on the storefront; `HIDDEN` keeps it unlisted. The sold-out (`available`) flag is preserved across the transition — use `PUT /products/{productId}/availability` to flip it."

removedInput schema / properties / state / enum

Removed value: -[
-  "PUBLIC",
-  "HIDDEN"
-]

removedInput schema / properties / state / type
```
Removed value: -"string"
```

Changedupdate_promotion14 fields changed

addedInput schema / $defs

Added value: +{
+  "Shop": {
+    "properties": {
+      "minimumOrderValue": {
+        "properties": {
+          "currency": {
+            "type": "string"
+          },
+          "value": {
+            "minimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "currency",
+          "value"
+        ],
+        "title": "Money",
+        "type": "object"
+      }
+    },
+    "title": "Shop",
+    "type": "object"
+  },
+  "appliesTo": {
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "title": "Open Api Update Promotion Applies To"
+          },
+          {
+            "properties": {
+              "type": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "type"
+        ],
+        "title": "Entire Order"
+      },
+      {
+        "allOf": [
+          {
+            "title": "Open Api Update Promotion Applies To"
+          },
+          {
+            "properties": {
+              "oncePerOrder": {
+                "type": "boolean"
+              },
+              "productIds": {
+                "items": {
+                  "format": "uuid",
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          }
+        ],
+        "required": [
+          "productIds"
+        ],
+        "title": "Selected Products"
+      }
+    ]
+  }
+}

addedInput schema / properties / appliesTo / $ref
```
Added value: +"#/$defs/appliesTo"
```

removedInput schema / properties / appliesTo / oneOf

Removed value: -[
-  {
-    "allOf": [
-      {
-        "title": "Open Api Update Promotion Applies To"
-      },
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "type"
-    ],
-    "title": "Entire Order"
-  },
-  {
-    "allOf": [
-      {
-        "title": "Open Api Update Promotion Applies To"
-      },
-      {
-        "properties": {
-          "oncePerOrder": {
-            "type": "boolean"
-          },
-          "productIds": {
-            "items": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "productIds"
-    ],
-    "title": "Selected Products"
-  }
-]

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / appliesTo / $ref
```
Added value: +"#/$defs/appliesTo"
```

removedInput schema / properties / payload / properties / appliesTo / oneOf

Removed value: -[
-  {
-    "allOf": [
-      {
-        "title": "Open Api Update Promotion Applies To"
-      },
-      {
-        "properties": {
-          "type": {
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "type"
-    ],
-    "title": "Entire Order"
-  },
-  {
-    "allOf": [
-      {
-        "title": "Open Api Update Promotion Applies To"
-      },
-      {
-        "properties": {
-          "oncePerOrder": {
-            "type": "boolean"
-          },
-          "productIds": {
-            "items": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "type": "object"
-      }
-    ],
-    "required": [
-      "productIds"
-    ],
-    "title": "Selected Products"
-  }
-]

addedInput schema / properties / payload / properties / requirements / $ref
```
Added value: +"#/$defs/Shop"
```

removedInput schema / properties / payload / properties / requirements / properties

Removed value: -{
-  "minimumOrderValue": {
-    "properties": {
-      "currency": {
-        "type": "string"
-      },
-      "value": {
-        "minimum": 0,
-        "type": "number"
-      }
-    },
-    "required": [
-      "currency",
-      "value"
-    ],
-    "title": "Money",
-    "type": "object"
-  }
-}

removedInput schema / properties / payload / properties / requirements / title
```
Removed value: -"Shop"
```
removedInput schema / properties / payload / properties / requirements / type
```
Removed value: -"object"
```
addedInput schema / properties / requirements / $ref
```
Added value: +"#/$defs/Shop"
```

removedInput schema / properties / requirements / properties

Removed value: -{
-  "minimumOrderValue": {
-    "properties": {
-      "currency": {
-        "type": "string"
-      },
-      "value": {
-        "minimum": 0,
-        "type": "number"
-      }
-    },
-    "required": [
-      "currency",
-      "value"
-    ],
-    "title": "Money",
-    "type": "object"
-  }
-}

removedInput schema / properties / requirements / title
```
Removed value: -"Shop"
```
removedInput schema / properties / requirements / type
```
Removed value: -"object"
```

Changedupdate_webhook8 fields changed

addedInput schema / $defs

Added value: +{
+  "allowedTypes": {
+    "items": {
+      "enum": [
+        "ORDER_PLACED",
+        "ORDER_UPDATED",
+        "GIFT_PURCHASE",
+        "PRODUCT_CREATED",
+        "PRODUCT_UPDATED",
+        "DONATION",
+        "SUBSCRIPTION_PURCHASED",
+        "SUBSCRIPTION_EXPIRED",
+        "SUBSCRIPTION_CHANGED",
+        "NEWSLETTER_SUBSCRIBED",
+        "THANK_YOU_SENT",
+        "GIFT_DRAW_STARTED",
+        "GIFT_DRAW_ENDED",
+        "PROMOTION_CREATED",
+        "PROMOTION_UPDATED",
+        "PROMOTION_STATUS_CHANGED",
+        "PLATFORM_APP_DISCONNECTED",
+        "MEMBERSHIP_POST_UPSERTED",
+        "MEMBERSHIP_SERIES_UPSERTED",
+        "MEMBERSHIP_SERIES_DELETED",
+        "MEMBERSHIP_TAG_CREATED",
+        "MEMBERSHIP_TAG_UPDATED",
+        "MEMBERSHIP_TAG_DELETED",
+        "MEMBERSHIP_TIER_UPSERTED",
+        "MEMBERSHIP_TIER_DELETED",
+        "COLLECTION_UPDATED",
+        "CART_ABANDONED_1H",
+        "CART_ABANDONED_24H",
+        "CART_ABANDONED_72H"
+      ],
+      "type": "string"
+    },
+    "type": "array"
+  }
+}

addedInput schema / properties / allowedTypes / $ref
```
Added value: +"#/$defs/allowedTypes"
```

removedInput schema / properties / allowedTypes / items

Removed value: -{
-  "enum": [
-    "ORDER_PLACED",
-    "ORDER_UPDATED",
-    "GIFT_PURCHASE",
-    "PRODUCT_CREATED",
-    "PRODUCT_UPDATED",
-    "DONATION",
-    "SUBSCRIPTION_PURCHASED",
-    "SUBSCRIPTION_EXPIRED",
-    "SUBSCRIPTION_CHANGED",
-    "NEWSLETTER_SUBSCRIBED",
-    "THANK_YOU_SENT",
-    "GIFT_DRAW_STARTED",
-    "GIFT_DRAW_ENDED",
-    "PROMOTION_CREATED",
-    "PROMOTION_UPDATED",
-    "PROMOTION_STATUS_CHANGED",
-    "PLATFORM_APP_DISCONNECTED",
-    "MEMBERSHIP_POST_UPSERTED",
-    "MEMBERSHIP_SERIES_UPSERTED",
-    "MEMBERSHIP_SERIES_DELETED",
-    "MEMBERSHIP_TAG_CREATED",
-    "MEMBERSHIP_TAG_UPDATED",
-    "MEMBERSHIP_TAG_DELETED",
-    "MEMBERSHIP_TIER_UPSERTED",
-    "MEMBERSHIP_TIER_DELETED",
-    "COLLECTION_UPDATED",
-    "CART_ABANDONED_1H",
-    "CART_ABANDONED_24H",
-    "CART_ABANDONED_72H"
-  ],
-  "type": "string"
-}

removedInput schema / properties / allowedTypes / type
```
Removed value: -"array"
```

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / allowedTypes / $ref
```
Added value: +"#/$defs/allowedTypes"
```

removedInput schema / properties / payload / properties / allowedTypes / items

Removed value: -{
-  "enum": [
-    "ORDER_PLACED",
-    "ORDER_UPDATED",
-    "GIFT_PURCHASE",
-    "PRODUCT_CREATED",
-    "PRODUCT_UPDATED",
-    "DONATION",
-    "SUBSCRIPTION_PURCHASED",
-    "SUBSCRIPTION_EXPIRED",
-    "SUBSCRIPTION_CHANGED",
-    "NEWSLETTER_SUBSCRIBED",
-    "THANK_YOU_SENT",
-    "GIFT_DRAW_STARTED",
-    "GIFT_DRAW_ENDED",
-    "PROMOTION_CREATED",
-    "PROMOTION_UPDATED",
-    "PROMOTION_STATUS_CHANGED",
-    "PLATFORM_APP_DISCONNECTED",
-    "MEMBERSHIP_POST_UPSERTED",
-    "MEMBERSHIP_SERIES_UPSERTED",
-    "MEMBERSHIP_SERIES_DELETED",
-    "MEMBERSHIP_TAG_CREATED",
-    "MEMBERSHIP_TAG_UPDATED",
-    "MEMBERSHIP_TAG_DELETED",
-    "MEMBERSHIP_TIER_UPSERTED",
-    "MEMBERSHIP_TIER_DELETED",
-    "COLLECTION_UPDATED",
-    "CART_ABANDONED_1H",
-    "CART_ABANDONED_24H",
-    "CART_ABANDONED_72H"
-  ],
-  "type": "string"
-}

removedInput schema / properties / payload / properties / allowedTypes / type
```
Removed value: -"array"
```

Changedupload_file1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

Changedvalidate_dns1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval for this exact provider effect or local private-file operation."New value: +"Set true only when the user asked for exactly this action."

86 tool updatesv2.0.0Oct 4, 2026
- First observedarchive_product
- First observedattach_product_images
- First observedconfirm_digital_file_upload
- First observedcreate_collection
- First observedcreate_fulfillment
- First observedcreate_gifting_checkout
- First observedcreate_giveaway
- First observedcreate_giveaway_checkout
- First observedcreate_giveaway_links
- First observedcreate_product
- First observedcreate_promotion
- First observedcreate_webhook
- First observeddelete_webhook
- First observeddisable_giveaway_checkout
- First observedend_streaming
- First observedexport_resources
- First observedfinish_giveaway
- First observedfinish_giveaway_draw
- First observedget_collection
- First observedget_collection_products
- First observedget_dns_status
- First observedget_donation
- First observedget_gift_purchase
- First observedget_gifting_config
- First observedget_giveaway_draw
- First observedget_giveaway_package
- First observedget_member
- First observedget_operation_schema
- First observedget_order
- First observedget_order_by_friendly_id
- First observedget_pro_subscription
- First observedget_product
- First observedget_product_inventory
- First observedget_product_template
- First observedget_promotion
- First observedget_public_token
- First observedget_report
- First observedget_sample_balance
- First observedget_shop
- First observedget_shop_contact
- First observedget_streaming_status
- First observedget_thank_you
- First observedget_webhook
- First observedget_webhook_event
- First observedlist_accounts
- First observedlist_collections
- First observedlist_contributions
- First observedlist_donations
- First observedlist_giveaway_packages
- First observedlist_mailing_list
- First observedlist_media_images
- First observedlist_members
- First observedlist_membership_tiers
- First observedlist_orders
- First observedlist_product_templates
- First observedlist_product_templates_by_category
- First observedlist_product_templates_by_category_paged
- First observedlist_product_templates_paged
- First observedlist_products
- First observedlist_promotions
- First observedlist_reports
- First observedlist_webhook_events
- First observedlist_webhooks
- First observedmark_download_complete
- First observedpreview_shop_batch
- First observedremove_digital_file
- First observedremove_product_images
- First observedrequest_digital_file_upload_url
- First observedrequest_media_upload_url
- First observedsave_media_image
- First observedsearch_product_templates
- First observedsearch_product_templates_grouped
- First observedsearch_product_templates_grouped_paged
- First observedsearch_product_templates_paged
- First observedstart_streaming
- First observedsubmit_shop_batch
- First observedtoggle_product_availability
- First observedupdate_collection
- First observedupdate_collection_availability
- First observedupdate_collection_products
- First observedupdate_gifting_config
- First observedupdate_product_state
- First observedupdate_promotion
- First observedupdate_webhook
- First observedupload_file
- First observedvalidate_dns

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

C2.9/5.0

Scored 2026-10-07 15:00 across 86 tools

Disambiguation2/5

Many tools have overlapping purposes, especially the eight product-template tools (e.g., list_product_templates vs list_product_templates_paged vs search_product_templates_grouped) and the giveaway/gifting cluster (create_giveaway, create_giveaway_checkout, create_giveaway_links, finish_giveaway, finish_giveaway_draw). An agent could easily misselect among these.

Naming Consistency5/5

All tool names use consistent snake_case with a verb_noun structure (get_, list_, create_, update_, delete_, etc.). Minor suffixes like _paged or _grouped are predictable and the pattern holds throughout.

Tool Count1/5

86 tools is far beyond the recommended 3-15 range for an MCP server and indicates an extreme mismatch. The surface is unwieldy and significantly increases selection complexity.

Completeness3/5

While many lifecycles are covered (promotions, webhooks, collections partially), there are notable gaps: no delete_collection, no general product update for name/description, no create/update for members or mailing list, and no shop settings update. These gaps may force workarounds.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Shopify MCP by InsightfulPipeOAuth
com.insightfulpipe
Hosted Shopify MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
E-commerce & Retail App Automation
11
Store MCPOAuth
com.store-mcp
Connect AI to store orders, products and inventory with scoped access and human approvals.
E-commerce & Retail ERP Systems
1
Final POS – Custom POS Builder AOAuth
com.finalpos
Build custom POS apps with your AI agent. Final's MCP server gives developers what they need to ship a custom point of sale: scaffold a checkout flow, adapt vetted screen blueprints for counter POS, self-checkout kiosks, restaurant ordering and payment terminals, ground every call in Final's version-locked POS APIs, validate, boot a live preview and deploy to real hardware with integrated card payments. The same server also manages the store behind it: products, stock, orders, customers and sales reports. Remote Streamable HTTP with OAuth 2.1.
Developer Tools E-commerce & Retail Payments & Billing
1771
Regenique Elegance Commerce A
com.regenique-elegance.agents
AI-powered commerce API for luxury skincare shopping. Enables AI agents to search products, browse collections, manage shopping carts, and generate checkout URLs for the Regenique Elegance Shopify store.
E-commerce & Retail App Automation Marketing
2

Related MCP Servers

Clind MCP Server
E-commerce & Retail Customer Support App Automation
lirad
F
license
Not graded
quality
Not graded
maintenance
A Shopify-focused MCP server that enables AI agents to manage store operations like order tracking, product discovery, and checkout link generation. It facilitates customer-facing interactions including shipping estimates and real-time inventory searches.
Updated 9 months ago (2026-02-06 03:10 UTC)
-
Shopify Store MCP Server
E-commerce & Retail Developer Tools App Automation
Brahim-Benzarti
A
license
Not graded
quality
C
maintenance
Enables AI agents to interact with live Shopify stores through Admin and Storefront APIs for tasks like GraphQL execution, bulk operations, and file uploads. It includes built-in rate limiting and operation logging to manage store data and schema discovery securely.
Updated 8 months ago (2026-02-13 13:35 UTC)
17 npm
3
ISC
cob-shopify-mcp
E-commerce & Retail Agent Orchestration Developer Tools
callobuzz
A
license
Not graded
quality
A
maintenance
A production-grade MCP server and CLI tool that enables AI agents to manage Shopify stores through 49 built-in tools across products, orders, inventory, and analytics. It supports natural language workflows for tasks like inventory tracking, customer support, and sales reporting.
Updated 6 days ago (2026-10-16 23:06 UTC)
78 npm
18
MIT
shopify-admin-mcp
E-commerce & Retail
ChaseWNorton
A
license
Not graded
quality
D
maintenance
Production-grade MCP server for the Shopify Admin GraphQL API, exposing typed tools for AI agents to manage products, orders, customers, and more.
Updated 7 months ago (2026-04-03 08:50 UTC)
201 npm
MIT

Fourthwall MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Set up your account

Settings

3. Install

4. Output and exit codes

5. Which surface and what each costs

6. Tools

get_webhook

update_webhook

delete_webhook

start_streaming

end_streaming

get_public_token

get_promotion

update_promotion

update_product_state

toggle_product_availability

mark_download_complete

finish_giveaway

create_giveaway_checkout

disable_giveaway_checkout

finish_giveaway_draw

get_gifting_config

update_gifting_config

update_collection

get_collection_products

update_collection_products

update_collection_availability

list_webhooks

create_webhook

list_promotions

create_promotion

list_products

create_product

attach_product_images

remove_product_images

confirm_digital_file_upload

remove_digital_file

request_digital_file_upload_url

request_media_upload_url

list_media_images

save_media_image

create_giveaway

create_giveaway_links

create_gifting_checkout

create_fulfillment

validate_dns

list_collections

create_collection

list_webhook_events

get_webhook_event

get_thank_you

list_contributions

get_streaming_status

get_shop

get_shop_contact

get_sample_balance

list_reports

get_report

get_product

archive_product

get_product_inventory

list_product_templates

get_product_template

search_product_templates

search_product_templates_paged

search_product_templates_grouped

search_product_templates_grouped_paged

list_product_templates_paged

list_product_templates_by_category

list_product_templates_by_category_paged

get_pro_subscription

list_orders