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

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.

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.

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-2.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 output for an agent. --select projects requested output fields. Errors go to stderr. --yes suppresses interactive presentation; it never replaces --confirm.

Exit	Meaning
0	Successful command
2	Usage, invalid arguments or refused effect
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

No matched completed Codex task/token measurement has been collected for this integration. Counts, schema characters, discovery costs and another integration's benchmark are not task savings. A fair comparison must record equivalent inputs, current client/model, permissions, successful native outcomes, errors/retries and total tokens. Software is free under AGPL-3.0; provider fees and plans remain separate.

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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.

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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.

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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.

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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.

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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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	Explicit approval for this exact provider effect or local private-file operation.
`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.

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

The SDK stdio server and CLI in-memory transport 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	2.0.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

Old cursor/limit fields become 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-2.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. CLI can avoid loading unused MCP schemas, but command help, results, retries and task completion also cost context. Matched completed Codex task/token measurements remain pending; no savings percentage is invented.

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

MCP SDK, Ajv and 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)A

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	Explicit approval for this exact provider effect or local private-file operation.
`product_id`	Yes	Native productId

TDQS

A3.5/5.0

Behavior1/5

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

The description claims 'Idempotent: re-DELETE on an already-archived product also returns 204,' which directly contradicts the annotation idempotentHint=false. Despite otherwise valuable disclosures (rate limit, terminal state, admin-only restoration), the explicit contradiction of structured metadata forces a 1.

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-loads the rate limit, then the core behavior, then the terminal-state warning and idempotency note. Every sentence carries relevant information, though the rate-limit bullet is somewhat boilerplate against the more distinctive terminal-state semantics.

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 no output schema, the description covers destructiveness, irreversibility, restoration restrictions, rate limits, and return code. The only completeness defect is the idempotency claim, which is wrong rather than 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 the schema already documents account, confirm, and product_id. 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?

States a specific verb+resource and the exact resulting state: 'Soft-archives the product — sets it to `Archived`.' It is readily distinguishable from state-toggling siblings like update_product_state and toggle_product_availability.

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?

Provides strong usage context by declaring the operation terminal at this surface (cannot return to PUBLIC/HIDDEN via open-api, restoration admin-only), which tells the agent this is a one-way action to use deliberately. It does not explicitly name an alternative sibling for reversible state changes, but the context is clear.

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	List of images to attach
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Explicit approval for this exact provider effect or local private-file operation.
`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.6/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 covered. The description adds genuinely new context — a concrete rate limit (100 requests / 10 seconds per shop) and the upload prerequisite — but it never explains what the "destructive" label means here, i.e., whether attaching replaces or appends to existing images, which is the key ambiguity an agent faces.

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 lines with zero filler; the prerequisite sentence carries the most action-guiding content. Leading with the rate-limit note rather than the purpose is slightly backwards, 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, six-parameter mutation with nested objects and no output schema, the description covers prerequisites and throttling but omits the lifecycle outcome (replace vs. append), the role of confirm/account, and any error behavior. It is workable but leaves the highest-risk question unanswered.

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 url/width/height and the payload/payload_file alternatives. The description adds nothing about the mutation-relevant parameters (confirm, account) or about how multiple images in the array are ordered or deduplicated, 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?

"Attaches images to a product" is a specific verb+resource statement that an agent can act on immediately, and the tool name reinforces it. It does not explicitly contrast with the obvious inverse sibling remove_product_images, but the intent 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 Guidelines4/5

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

The description supplies a real prerequisite: images must be uploaded first via the media upload endpoint, which routes the agent to the upload flow before calling this tool. It gives no when-not guidance (e.g., what to do if images are already attached), so it stops short of explicit alternative routing.

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	Explicit approval for this exact provider effect or local private-file operation.
`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

A4.1/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 bar is lower. The description goes beyond them by disclosing a concrete rate limit (100 requests / 10 seconds per shop) and a hard precondition that the file must already exist in storage, which are useful non-obvious behavioral facts.

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 sentences with no filler; the rate-limit note is front-loaded as a callout and the actionable purpose follows immediately. Slightly awkward that the operational purpose comes after the rate-limit reference, 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 7-parameter, nested-object mutation with no output schema, the description covers the essential precondition and rate limit, and annotations carry the safety profile. Minor gaps remain around failure modes, but the definition is sufficient 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 description coverage is 100%, so the schema already documents all 7 parameters including the nested payload object. The description adds no field-level meaning (e.g. payload vs. top-level fileName/fileUrl precedence) beyond what the schema provides, so the baseline 3 is appropriate.

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 ('link the file to the product') and ties itself into the upload flow by referencing the presigned URL, which disambiguates it from siblings like request_digital_file_upload_url and remove_digital_file. An agent can tell exactly what this 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 Guidelines4/5

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

Clearly specifies when to call it ('after uploading a file to the presigned URL') and states the precondition ('The file must exist in storage before calling this endpoint'). It lacks an explicit when-not or named alternative, but the sequential context is strong and actionable.

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	Explicit approval for this exact provider effect or local private-file operation.
`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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds a concrete rate limit (100 requests / 10 seconds per shop), which is genuine behavioral context, but it says nothing about the effect of creating a duplicate collection, permission requirements, or the confirm/account gating mechanism implied by the 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?

Two short blocks with no filler sentences. Leading with the rate-limit aside before the purpose is slightly awkward ordering, but the text is tight and complete for its length.

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 annotations carrying destructiveness, openness, and non-idempotency, and no output schema to explain, the description's main job is minimal. It still leaves the mutually exclusive body variants (payload, payload_file, and flat flags) and the confirm requirement unexplained, which is a real gap for a 7-parameter tool with a nested required 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 71%, and the schema itself documents account, confirm, payload, payload_file, and offerIds. The description only restates name/description/product list, adding essentially no meaning beyond the structured fields, and ignores the payload-vs-payload_file alternation entirely.

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 ('Creates a new collection') and names the fields it accepts (name, description, optional product list). An agent can tell it is a create operation, but the description never names or contrasts with siblings such as update_collection, list_collections, or get_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?

There is no guidance on when to call this versus update_collection or the other collection tools, and no prerequisites stated. The only operational note 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.

create_fulfillmentCreate a fulfillment for an orderB

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	Explicit approval for this exact provider effect or local private-file operation.
`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

B3.2/5.0

Behavior4/5

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

Annotations already declare destructive=true, idempotentHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond that: a concrete rate limit (100 req/10s per shop) and the downstream side effects (order.status transitions through IN_PRODUCTION/PARTIALLY_SHIPPED/SHIPPED and order-updated webhooks fire). It does not say what a duplicate call does or what response 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?

Compact and front-loaded, with the rate limit placed first, then purpose, then state-transition behavior. Every sentence carries information and there is no filler.

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 with an intricate payload/body-flag schema and no output schema, the description covers side effects and rate limiting well but leaves the parameter-shape ambiguity, confirmation semantics and error/repeat-call behavior undocumented. Adequate but with clear gaps for an agent to invoke it correctly.

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 coverage is only 57% and the description mentions only the concepts 'order items' and 'shipment tracker', adding no meaning beyond that. Critically, the schema exposes an ambiguous dual shape (top-level items/orderId/shippingLabel vs a nested payload object containing the same fields, plus payload_file, account and confirm), and the description does nothing to clarify which set to use or how confirm/account behave.

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 ('Creates a fulfillment') and adds the distinguishing detail that it attaches a shipment tracker for provided order items. No sibling tool covers fulfillment creation, so there is little to differentiate against, but the 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?

No guidance on when to create a fulfillment versus not, no prerequisites (e.g. order must be in a fulfillable state), and no mention of alternatives. The only contextual hint is the 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.

create_gifting_checkoutCreate a gifting checkoutB

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	Explicit approval for this exact provider effect or local private-file operation.
`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	Display currency for the checkout. Defaults to the shop's currency.
`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

B3.1/5.0

Behavior3/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, so the mutation/irreversibility profile is covered structurally. The description adds one genuinely useful piece of context beyond that – the checkout is 'paid', i.e. it involves a monetary charge – but says nothing about when the charge occurs, required permissions, or the confirm flag's role.

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 front-loaded sentence with no filler or redundancy. It is appropriately sized for what it says, though the terseness is a symptom of missing content rather than efficient compression.

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 7-parameter tool with a nested payload object, zero required parameters, no output schema, and a monetary effect, one sentence is not enough. It omits what the tool returns (e.g. a checkout URL or ID), how the payload relates to the top-level offerId/quantity/currency duplicates, and what 'confirm' and 'account' gate.

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 the nested payload fields, offerId, quantity, currency, account, confirm, and payload_file, is already documented in the schema. The description adds no 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.

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 paid checkout') plus the scope ('for gifting a product to live chat'), which is clear enough to distinguish it from unrelated siblings like create_webhook. It does not, however, contrast itself with the nearby create_giveaway_checkout or get_gifting_config, so differentiation from the closest alternatives 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?

There is no statement of when to use this tool versus create_giveaway_checkout, create_fulfillment, or the gifting config tools, and no prerequisites or exclusions are given. The only usage signal is the phrase 'to live chat', which is context, not guidance.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.9/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 largely covered. The description usefully adds the rate limit, but it does not explain the confirm/approval requirement, payload-vs-body semantics, or what the destructive/open-world behavior means 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.

Conciseness4/5

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

The description is short and front-loads the rate-limit constraint before the operation sentence. It is efficient, though the second sentence mostly restates the tool name and title.

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 an 8-parameter, destructive, open-world mutation with no output schema, the description is far too thin. It does not explain how the nested payload relates to top-level fields, what confirm does, or how to construct a valid invocation.

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%, and the description adds no parameter meaning at all. Important top-level fields such as message, offerId, quantity, and username have no schema descriptions and no explanation in the tool description.

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 giveaway." That is clear, but it does not distinguish this tool from closely named siblings such as create_giveaway_checkout, create_giveaway_links, finish_giveaway, or finish_giveaway_draw.

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 only gives a rate limit. It provides no when-to-use guidance, no prerequisites, and no alternatives among the many giveaway-related sibling tools.

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	Explicit approval for this exact provider effect or local private-file operation.
`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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the upsert ('creates or updates') semantics are consistent with the declared non-idempotence. The description adds a genuinely useful behavioral fact not present in the annotations — the 100 requests / 10 seconds rate limit — but says nothing about what an update overwrites or what side effects the destructive write has.

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 filler, but the structure is front-loaded with a boilerplate rate-limit banner and relegates the actual purpose to a trailing fragment, which is backwards for tool selection.

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 9 parameters, 0 required fields, a nested payload object, and no output schema, the description omits prerequisites, the create-vs-update discriminator, and the confirm/account semantics that the schema only hints at. It is not complete enough to call this tool safely.

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% (heading, iconUrl, disabled, buttonText, description have no descriptions), and the description adds zero parameter meaning. With 9 parameters, an optional top-level set that shadows nested payload fields, and a payload/payload_file mutual exclusion, the description should clarify the relationship but does not.

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 gives a verb and resource ('Creates a new giveaway or updates existing one'), but the 'or' leaves the operation ambiguous — an agent cannot tell which branch fires, or on what key an update targets. It also does not distinguish this from the sibling tools create_giveaway and create_gifting_checkout, which sound nearly identical.

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 create_giveaway, create_gifting_checkout, or disable_giveaway_checkout. The only contextual note is a rate limit, which is a constraint, not usage guidance.

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	Explicit approval for this exact provider effect or local private-file operation.
`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, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description does add one genuinely useful non-annotation fact — the 100 requests / 10 seconds per shop rate limit and a link to the throttling guide. It says nothing about what the destructive effect actually does or why 'confirm' exists.

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, no padding, and the operative verb statement is easy to find. Leading with the rate-limit caveat ahead of the purpose statement is a minor front-loading miss but it is still compact.

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 destructive, non-idempotent, open-world mutation with a nested request body, 6 parameters, zero required parameters and no output schema. The description omits what a 'package' is, how the flat number/productId relate to the nested payload, how confirm gates the operation, and what is returned — substantial gaps for a tool of this complexity.

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 67%, and the schema documents account, confirm, payload and payload_file. The description only glosses 'specified number', which mildly clarifies the otherwise undocumented top-level 'number' and leaves 'productId' plus the payload-vs-flat-parameter relationship unexplained.

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 names a specific verb and resource ('Creates a new package with ... giveaway links') and the 'package' framing dovetails with siblings like list_giveaway_packages and get_giveaway_package. It does not, however, distinguish itself from create_giveaway or create_giveaway_checkout, so an agent must infer the boundary.

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 and no mention of any alternative among the many giveaway siblings (create_giveaway, create_giveaway_checkout, finish_giveaway, list_giveaway_packages). The only contextual sentence is a rate limit, which is not usage routing.

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

create_productCreate a productA

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	Explicit approval for this exact provider effect or local private-file operation.
`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

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnly=false, destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds genuinely new operational context the annotations lack: a concrete rate limit (5 requests/minute per shop) with a link to the rate-limiting guide. It still omits auth expectations and the `confirm` approval requirement, 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 lines with no waste; the rate-limit warning is front-loaded as a bolded callout and the one-line purpose follows. Slightly odd to lead with a constraint rather than the action, but 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?

For a destructive, non-idempotent creation tool with a deeply nested discriminated payload, the description leans almost entirely on annotations and schema. It does not explain what is returned (no output schema, so a product id or created resource is never mentioned) nor the required media-registration precondition, leaving real gaps an agent calling this cold would 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%, so parameters (account, confirm, payload, payload_file) and the nested payload variants are already thoroughly documented in the schema itself. The description adds nothing parameter-specific beyond restating the two product types, 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 ('Creates a product') and names both creation modes ('from a design or a digital product'), which maps cleanly onto the discriminated `type` field. It does not explicitly differentiate from siblings like update_product_state or archive_product, but the create verb is unambiguous among 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 two modes are named but there is no guidance on when to choose design vs digital, no prerequisites (e.g. the media registration and product-template lookup the schema requires), and no exclusions. Usage is only implied by the mode names and the 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_promotionCreate a promotionC

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	Explicit approval for this exact provider effect or local private-file operation.
`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

C2.4/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description's one genuine contribution beyond that is the rate limit (100 requests / 10 seconds per shop), which is real behavioral context, but it says nothing about required permissions, side effects, or the create semantics of the union payload.

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 rate-limit callout is placed ahead of the single purpose sentence, which front-loads an operational detail over the tool's function. Nothing is padded, yet nothing is front-loaded usefully either.

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 destructive write with a complex five-variant union payload (MEMBERSHIPS_MULTI/SINGLE, SHOP_MULTI/SINGLE) and no output schema. The description does not explain the variant selection, the required code/discount combinations, or the meaning of the confirm gate, leaving substantial gaps for a tool of this complexity.

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 account, confirm, payload, and payload_file, including the oneOf variants and the mutual-exclusion rules. The description adds no parameter meaning at all, so the baseline 3 for a fully documented schema 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 says only "Creates a promotion," which restates the name and title without adding a verb-plus-resource distinction beyond them. It gives no hint of the promotion variants (membership vs shop, single vs multi code) that the schema actually requires, nor any differentiation from siblings like update_promotion or list_promotions.

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, and no routing to alternatives such as update_promotion. The rate-limit note is operational, not usage guidance, so an agent gets nothing about when this tool is the right choice.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.6/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) with a link, which is genuinely useful beyond the annotations, but it says nothing about the required 'confirm' approval, what a created webhook enables, or failure modes.

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 the rate limit is front-loaded, so it is not bloated. However, the 'Create a webhook' sentence duplicates the title and the rate-limit line is doing nearly all the work, so the text is thin rather than efficiently packed.

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 six-parameter, destructive, nested-payload mutation with no output schema and zero required parameters, the description is far too sparse. It omits the confirm/approval semantics, the account scoping, and which payload representation to supply, leaving key invocation decisions unaddressed.

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 67% and the description mentions no parameters at all. The nested payload object, the enum of allowed event types, and the mutually exclusive payload/payload_file/body-flag options are left entirely to the schema, with no clarifying prose about which form to use.

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 'Create a webhook', which gives a verb and a resource, but it is essentially a restatement of the title and adds no scope, constraints, or distinguishing detail. With four sibling webhook tools (get_webhook, update_webhook, delete_webhook, list_webhooks) it does not help the agent discriminate among 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_webhook or list_webhooks. The only content is a rate-limit note, which is operational context 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.

delete_webhookDelete a webhookB

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	Explicit approval for this exact provider effect or local private-file operation.
`webhook_configuration_id`	Yes	Native webhookConfigurationId

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description's only added value is the rate limit (100 requests / 10 seconds per shop), which is genuine operational context, but it says nothing about permanence, effect on pending deliveries, or the 'confirm' requirement.

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 with no filler sentences, though the rate-limit banner is placed ahead of the purpose statement, which slightly buries the front-loaded intent. Nothing is wasted, but nothing is elaborated either.

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, open-world deletion with no output schema, the description should warn that the action is irreversible and note whether dependent webhook events are affected. Neither the description nor the schema covers consequences, leaving a real gap for a destructive 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 all three parameters (account, confirm, webhook_configuration_id) are already documented in the schema. The description adds no parameter-level 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+resource ('Delete a webhook') that cleanly distinguishes it from siblings create_webhook, update_webhook, get_webhook, and list_webhooks. It is clear but offers no scope detail (e.g. whether the webhook is removed permanently or only deactivated).

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 update_webhook or disable-style siblings, and no prerequisites, confirmations, or warnings about irreversibility. The agent must infer everything from the name alone.

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	Explicit approval for this exact provider effect or local private-file operation.

TDQS

C2.7/5.0

Behavior3/5

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

The description adds genuinely useful context beyond the annotations: a rate limit of 100 requests / 10 seconds per shop with a link to the rate-limiting guide. That is real operational information the annotations do not carry. It does not, however, describe what disabling actually does to an active checkout, whether it is reversible, or why the destructive-flagged operation expects confirmation.

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 ordering is poor: the rate-limit boilerplate is front-loaded and the actual purpose ("disables a giveaway config") trails at the end in lowercase. The one sentence that matters is the least prominent part.

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 no output schema and no required parameters, the description is too thin. It omits what state changes occur, whether an existing active checkout is cancelled, and whether the operation can be undone, leaving the agent to infer consequences from annotations 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 the baseline is 3. The description adds nothing about the account label or the confirm flag, but the schema already explains both, so no compensation is required.

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 ("disables a giveaway config"), which is enough to know it turns something off. However, it never clarifies what a "giveaway config" is, whether this refers to a checkout config specifically, or how it relates to siblings like create_giveaway_checkout or finish_giveaway. Without that differentiation the purpose is only minimally 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 guidance on when to use this tool versus finish_giveaway, create_giveaway_checkout, or update_gifting_config. No prerequisites, no mention of the confirm parameter being needed, and no conditions under which this is the right call are stated.

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	Explicit approval for this exact provider effect or local private-file operation.
`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, readOnlyHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds a concrete operational constraint, the 100 requests / 10 seconds per shop rate limit, which is genuine value beyond annotations. It does not explain what 'ended' implies for the stream or why the confirm flag exists.

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 elements with zero waste; the rate-limit constraint is front-loaded and the purpose sentence follows. Nothing redundant or padded.

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?

With 5 parameters, zero required fields, a nested payload object, and three apparently exclusive ways to supply the body (payload, payload_file, services), the description never clarifies which to use or what confirm is for. Annotations cover the destructive profile, but the invocation-shape ambiguity is left entirely 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 80%, so the schema does most of the work and 3 is the baseline. The description's phrase 'for specified services' loosely maps to the services parameter, but adds nothing about the mutually exclusive payload / payload_file / services body mechanisms or the confirm flag.

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 ended for specified services'. Combined with the name end_streaming, an agent can tell it apart from the sibling start_streaming and get_streaming_status without opening schemas. It does not explicitly name those siblings, 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?

No when-to-use guidance, no stated prerequisites (e.g. an active stream, a prior start_streaming call), and no alternatives or exclusions. The only usage-adjacent content is a rate-limit note, which is a constraint 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.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.3/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 safety is partly covered. The description adds substantial context beyond them: exclusive 0600 file creation, page/item/5MiB budgets, page/offset continuation, and explicit non-guarantees (no atomic backup, no link following, no binary downloads).

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 sentences with no filler, but the density of hyphenated jargon ('native page/size/results', 'exclusive0600', 'page/item/5MiB') hurts readability and front-loading. It is compact yet not easily skimmable.

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, nested-object write tool with no output schema, the description covers file permissions, size caps and non-guarantees, which is meaningful. It still omits the file's format/structure, failure behavior, and permission requirements, so it 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 coverage is only 38%, so the description needs to compensate. It does explain the page/item budget and offset-continuation concepts, which map to max_pages, max_items and start_offset, but account, confirm, arguments and operation 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?

The description names the verb (export) and the resource (bounded private metadata written to a new exclusive 0600 file), which is enough to distinguish it from the many list_*/get_* siblings that only read data. The phrasing 'native page/size/results export' is jargon-heavy and takes effort to parse, but the core action is identifiable.

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 statement of when to use this over the sibling list_products/list_orders/list_promotions calls it wraps, nor any when-not guidance. The word 'Confirmed' hints that a confirmation step is expected, but the description never says so directly or names an alternative.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.1/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds a useful operational constraint (100 requests / 10 seconds per shop), but omits what an agent most needs to know here: that selecting winners is irreversible and presumably requires the confirm/approval flow surfaced in the 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?

Two short lines with no filler. The only structural nit is ordering: the rate-limit boilerplate is front-loaded ahead of the actual statement of what the tool does, which is the more important content for tool selection.

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, open-world mutation with 6 parameters, nested objects and no output schema, the description is far too thin: it never warns that finishing is irreversible, never distinguishes the two 'finish/giveaway' siblings, and never explains the confirm/payload/payload_file parameter families an agent must reason about.

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 and payload_file. The description adds no parameter-level meaning (e.g. the participants vs payload vs payload_file distinction) 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.

Purpose4/5

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

"Finish giveaway and select winners" gives a specific verb (finish) and resource (giveaway) plus the concrete consequence of the call. However, it does not distinguish itself from the near-identical sibling finish_giveaway_draw (nor from create_giveaway / create_giveaway_checkout), so an agent cannot tell from the description alone which of these two 'finish' tools to pick.

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 states no when-to-use condition, no prerequisites, and never names an alternative. A rate-limit line is the only operational guidance, and it does not help the agent choose between finish_giveaway and finish_giveaway_draw.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.1/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, readOnlyHint=false, so the safety profile is covered structurally. The description usefully adds the concrete rate limit (100 req/10s per shop) which annotations cannot express, but says nothing about irreversibility, winner-selection behavior, or confirmation requirements beyond the schema's 'confirm' 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, no waste, rate limit front-loaded. Slightly terse for a destructive nested-payload operation, but nothing is redundant.

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 destructive, non-idempotent mutation with a nested participants payload and no output schema, yet the description explains none of the consequences: whether the draw is final, what happens to unselected participants, or what 'confirm' protects against. The rate-limit note is the only substantive 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 83%, so the schema largely documents id, account, confirm, payload, payload_file, and participants. 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 draw') plus the effect ('select winners'), which separates it from read-side siblings like get_giveaway_draw and from finish_giveaway. It does not explicitly contrast with the sibling finish_giveaway, 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?

No guidance on when to use this versus finish_giveaway, get_giveaway_draw, or list_giveaway_packages, and no prerequisites (e.g. draw must be in progress, participants must be supplied). Only the rate limit is given as context.

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 detailsA

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

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-redundant context: it is public and requires no authentication, and it enumerates what the response contains (variants, customizable areas, size guide, images). That auth disclosure is meaningful behavioral information the annotations do not carry.

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 with the core purpose front-loaded, followed by auth note and return contents. Some leading whitespace/indentation is wasted but the content itself is tight and non-redundant.

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 two-parameter read tool with no output schema, the description covers purpose, auth requirements, and a summary of returned fields, which is enough for correct invocation. It could be improved with explicit sibling routing (vs. get_product / search_product_templates), which is the only material 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%, so both parameters are already documented in the schema, including the notable caveat that 'account' is a profile label and not an authorization proof. The description adds nothing about parameter semantics, 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 uses a specific verb+resource ('Get detailed information about a specific product template'), which clearly distinguishes it from the sibling list/search tools like list_product_templates and search_product_templates. It stops short of naming those siblings, but the singular 'specific product template' framing signals the single-item retrieval role.

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: an agent can infer this is the tool for fetching one template by ID, but there is no explicit statement of when to use it over list_product_templates, search_product_templates, or get_product. No prerequisites or exclusions are given.

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	Explicit approval for this exact provider effect or local private-file operation.
`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, so the mutation risk profile is covered structurally. The description usefully adds the per-shop rate limit (100 requests / 10 seconds) and clarifies the get-or-create behavior. However it never explains why the operation is destructive (e.g., whether token issuance revokes prior tokens) or what permissions are required, leaving the most consequential trait undisclosed.

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. Minor issue: the italicized rate-limit note is front-loaded ahead of the actual behavioral sentence, which would be the more important lead for an agent deciding whether to call the 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 at least signal that the token lands in the owner-private receipt file; it leaves that entirely to the output_file parameter description. Combined with missing permission/prerequisite context for a destructive, non-idempotent operation, it is adequate but incomplete.

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 already explains account, confirm, and output_file in detail (including the exclusive 0600 receipt file). The description adds no parameter-level detail, 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 states a specific resource and behavior: returns the shop's existing public token or creates one if absent. That 'get or create' semantics is precise and unambiguous. It does not differentiate from any sibling, though no sibling in the list clearly overlaps.

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, no mention of alternatives, and no prerequisites for obtaining a token. The only operational context given is a rate limit, which is a constraint rather than guidance on selection.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.9/5.0

Behavior4/5

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

Annotations declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds concrete behavioral context (conditional download creation with defaultFileUrl) and includes an explicit rate limit (100 req/10s per shop), which goes 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?

Front-loads the rate limit and the primary action, then adds the conditional creation clause. Every sentence carries meaning. Slightly dense but no waste.

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 the core action, the conditional creation path, and rate limit for a mutation tool whose safety profile is already in annotations. No output schema exists, but the description needn't explain returns for a mark-complete operation. Could still note auth/confirmation expectations given the 'confirm' parameter.

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 params well. The description references defaultFileUrl and adds business semantics (creates a download when none exists) that the schema text does not, but does not clarify account/confirm/payload_file constraints.

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+resource ('Marks digital download as downloaded') and adds a conditional behavior (creating a download when none exists and defaultFileUrl is supplied). Distinct from sibling tools like confirm_digital_file_upload or remove_digital_file.

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?

Implied usage via the conditional creation clause, but no explicit when-to-use vs alternatives or when-not-to-use guidance. The agent must infer this tool applies to digital-order fulfillment flows.

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	Explicit approval for this exact provider effect or local private-file operation.
`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 clear. The description adds a rate limit (100 req/10s per shop), which is useful behavioral context. However, it doesn't disclose consequences of removal (e.g., permanent deletion, effect on existing purchases) or any authentication requirements beyond what annotations imply, leaving gaps 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?

The description is very concise: a rate-limit line and a single sentence stating the purpose. It is front-loaded with the rate limit and then the core action. No extraneous information, though the rate limit could be considered slightly tangential to the core purpose.

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 is minimal. It states what it does and a rate limit, but omits important context such as whether the removal is permanent, what happens to associated downloads, or any required permissions. Annotations cover the safety profile, but the description could provide more operational context to help an agent understand the full impact.

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. The description mentions 'by its file URL', which corresponds to the fileUrl parameter, but adds no format details or constraints beyond what the schema provides. With high 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?

The description clearly states the verb ('Removes') and resource ('digital file from the product') and specifies the identifier ('by its file URL'). It doesn't explicitly differentiate from siblings like 'remove_product_images' or 'confirm_digital_file_upload', but the resource (digital file) and operation (remove) are specific enough to distinguish it.

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 is provided. There is no mention of prerequisites (e.g., digital file must exist), conflicts with other tools, or conditions under which removal should occur. The agent must infer usage entirely from the name and purpose.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.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 covered. The description adds a concrete operational constraint (100 requests / 10 seconds per shop with a docs link), which is genuine value beyond the schema, but it says nothing about reversibility, partial-failure behavior, or what happens when URLs don't match.

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; the rate limit is front-loaded and the purpose follows immediately. Nothing is padded, though the rate-limit line arguably belongs in a shared constraints section rather than this tool's description.

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 over a nested payload with no output schema, the description covers the essential action and rate limit but omits outcomes: no mention of what the response indicates, whether removed images can be restored, or how the mutually exclusive payload/payload_file/confirm options should be chosen. Adequate, with clear 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 every parameter is already documented in the schema; baseline 3 applies. The description restates the imageUrls concept but adds no format, count-limit, or matching-rule detail 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+resource ('Removes specified images from a product') and clarifies the identification mechanism (by their URLs). It is clearly distinguishable from the sibling attach_product_images, though it never names the counterpart 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?

No when-to-use / when-not-to-use guidance, no prerequisites, and no reference to alternatives such as attach_product_images. The only contextual statement is a rate limit, which is a constraint 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.

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	Explicit approval for this exact provider effect or local private-file operation.
`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

A3.9/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 partially covered. The description adds genuinely new behavioral context: an explicit rate limit of 100 requests / 10 seconds per shop with a link, plus the two-phase workflow requirement that the upload is incomplete until the confirm call runs.

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 plus a one-line rate-limit note; every sentence earns its place and there is no filler. Minor deduction because the leading rate-limit notice precedes the purpose statement rather than following it.

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 9-parameter, nested-schema tool with no output schema, the description covers the workflow, the rate limit, and the required confirm step. It does not mention the confirm_digital_file_upload sibling by name, but with full schema coverage and annotations the definition is sufficient to call the tool 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 description coverage is 100% across all 9 parameters, including the nested payload object and the size/header matching constraint, so the schema carries the semantics. The description only references uploadUrl indirectly and adds no parameter-level meaning beyond what the schema already 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?

The description states a specific verb and resource: 'Returns a presigned URL to upload a digital file to.' An agent immediately knows this is the first step of a two-step upload flow. It does not, however, distinguish itself from the sibling request_media_upload_url, which follows the same pattern for images.

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 sequencing context: receive the URL, PUT the file bytes to uploadUrl, then call the confirm endpoint to link the file to the product. That is actionable workflow guidance. It stops short of exclusions or naming alternatives (e.g., the media-upload sibling), so it is not a full 5.

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 URLA

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	Explicit approval for this exact provider effect or local private-file operation.
`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

A3.7/5.0

Behavior4/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), the description adds two useful behavioral facts: a concrete rate limit (20 requests/minute per shop) and the required post-response workflow of PUTting bytes to uploadUrl. It does not, however, explain the destructive or non-idempotent nature flagged by 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 the rate limit stated up front and the workflow second; nothing is wasted. The leading rate-limit line is slightly less important than the tool's core purpose, but overall it is well front-loaded.

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 correctly explains what comes back (an uploadUrl) and the next action to take. Combined with annotations covering the safety profile, an agent has enough to invoke and follow through, though it omits details like URL expiry or response 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 there are 8 parameters (including a nested payload object), so the schema already documents size, fileName, contentType, etc. The description adds no parameter-level detail beyond what the schema provides, 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?

The description states a specific verb and resource: returns a pre-signed upload URL for uploading a new image. It clearly distinguishes the tool's output from siblings like save_media_image or attach_product_images, though it doesn't explicitly name the alternative upload-URL tool (request_digital_file_upload_url).

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 describes the follow-up step (PUT the image bytes directly to the uploadUrl), which implies usage, but gives no guidance on when to choose this tool over request_digital_file_upload_url, save_media_image, or upload_file. Context is implied rather than stated.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.1/5.0

Behavior3/5

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

Adds genuinely useful context the annotations do not carry: the 100 requests / 10 seconds per shop rate limit with a docs link. However, with destructiveHint=true and idempotentHint=false, the description never explains what the operation destroys, whether repeats create duplicates, or why the 'confirm' flag exists – gaps that matter for a 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 tight sentences with no filler. The ordering places the rate-limit note ahead of the actual purpose, which is slightly backwards for front-loading, but the total length is well controlled.

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 payload object, no output schema, and no required-parameter signaling, the description omits too much: what gets destroyed, return behavior, and how the account/confirm semantics affect the call. The rate-limit note is the only extra context supplied.

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 coverage is only 57% and the description explains none of the 7 parameters. It notes an image was uploaded but does not map fileUrl, width, height, account, confirm, or the payload/payload_file body alternatives, leaving the agent without guidance on a schema where no parameters are even marked required.

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: 'Persists an uploaded image in the media library', and adds the workflow precondition (client already PUT to the signed URL). This differentiates it from siblings like request_media_upload_url and list_media_images, though it never names them explicitly.

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 phrase 'after the client has PUT it to the signed URL' implies when to call it (second step of the upload flow), but no alternative is named and no explicit when-not condition is given. 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.

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	Explicit approval for this exact provider effect or local private-file operation.
`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 declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the agent knows this is a mutating, non-idempotent, open-world operation. The description adds a rate limit (100 req/10s per shop), which is useful context beyond annotations. However, it doesn't clarify the destructive nature, what state changes occur, or the confirm parameter's role in preventing accidents. Some value added but gaps remain.

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?

Extremely concise: two sentences, with the rate limit front-loaded and the operation stated clearly. No waste.

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 tool with nested objects and no output schema, the description is too thin. It omits prerequisites, required permissions, what 'services' expects, and any warning about irreversibility. The rate limit is helpful but insufficient for safe 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 80%, so the schema documents most parameters. The description adds no parameter details beyond 'specified services,' which is already in the schema. The confirm parameter's purpose (explicit approval for destructive effect) is in the schema description, not the tool description. 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: 'Sets streaming status to started for specified services.' It implies a counterpart (end_streaming exists as a sibling), though it doesn't explicitly name it. The purpose is clear but lacks direct 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?

No guidance on when to use this vs end_streaming or get_streaming_status. The description mentions 'specified services' but doesn't explain prerequisites, which services are supported, or when to prefer alternatives. Implied usage only.

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 effectsA

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	Explicit approval for this exact provider effect or local private-file operation.
`review_sha256`	Yes

TDQS

A3.9/5.0

Behavior5/5

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

This goes well beyond the annotations: it discloses that all effects are validated and hash-checked before the first request, that execution halts on the first failure, that receipts are split into known vs unattempted, and that there is no retry, rollback, or implicit continuation. That is exactly the atomicity, partial-failure, and irreversibility information an agent needs for a destructive, non-idempotent batch call.

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 clauses, zero filler, with the critical constraints front-loaded. It is slightly telegraphic ('Confirmed ordered effects' is a fragment rather than a stated action), 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 4-parameter destructive batch with no output schema and no nested objects, the description covers validation, ordering, failure behaviour, and the absence of rollback — the key things. The remaining gap is the preview-then-submit relationship and any note on the account/confirm 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 coverage is 75%, so the schema already documents most parameters; the description adds only marginal meaning ('ordered' implies sequence significance for tasks, 'hash checked' ties to review_sha256) and says nothing about the account parameter. Baseline 3 is appropriate when the schema carries most of 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?

The description makes clear this executes a pre-validated, hash-checked batch of ordered effects, and the failure semantics ('stop on first failure') sharpen what kind of operation it is. It never uses an explicit verb like 'execute' or 'submit', and it does not name the obvious sibling (preview_shop_batch), so differentiation is left to inference from the tool name.

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?

'Confirmed ordered effects' plus the required review_sha256 imply this is the post-review execution step, so the when-to-use is implied. However, the tool never names preview_shop_batch as the alternative, nor states the precondition that a preview must have produced the hash — the agent must infer the workflow.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.1/5.0

Behavior3/5

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

The annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact -- the rate limit of 100 requests / 10 seconds per shop -- but says nothing about what the mutation affects, permission needs, or how the `confirm` requirement works.

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?

It is short and the rate-limit notice is front-loaded, with zero filler. However, the bulk of the text is an operational note rather than task description, leaving the core statement to a single clause.

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 destructive mutation with 6 parameters, a nested payload object, a payload_file alternative, and a `confirm` approval flag, and there is no output schema to lean on. The description explains none of this complexity or the mutation's blast radius, leaving the agent under-informed for a destructive operation.

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 itself documents product_id, account, confirm, payload, and payload_file. The description adds no parameter-level 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?

The description states a specific verb and resource: 'Updates a product (offer) availability'. It is clear what the tool does, but it offers no differentiation from closely related siblings such as update_product_state or update_collection_availability. Note also that the tool name says 'toggle' while the payload takes an explicit `available` boolean, a mild inconsistency the description does not resolve.

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 any alternative, and no prerequisites or conditions for use are given. With siblings like update_product_state and update_collection_availability in the same namespace, the absence of routing guidance is a real gap.

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	Explicit approval for this exact provider effect or local private-file operation.
`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, openWorldHint=true, so the risk profile is partly covered. The description adds a genuinely useful non-annotation detail: 100 requests / 10 seconds per shop. However, it never explains the destructive semantics implied by offerIds (replacing the collection's product list) nor mentions the required confirm/account fields for this 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 compact sentences with no filler; the rate-limit note is a single pointer to documentation rather than an essay. Slight deduction because the operational note is placed ahead of the actual statement of purpose, so the substance is not fully 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 an 8-parameter, nested-object, non-idempotent mutation with no output schema, the description covers rate limiting but omits how the mutually exclusive payload, payload_file, and flat body flags interact, and says nothing about the confirm requirement. Adequate but with clear gaps an agent would need to resolve 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 75%, so structured fields already document most parameters, and 75% is high enough that the baseline is 3. The description maps cleanly onto name/description/offerIds but adds no format or behavioral detail beyond what the schema states, and is silent on the payload-vs-flat-field alternatives.

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 names a specific verb (Updates) and resource (collection) and enumerates the mutable fields: name, description, product list. That is clear enough for an agent to know what the tool does, but it does not distinguish itself from close siblings like update_collection_products or update_collection_availability, which overlap with the 'product list' wording.

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 update_collection_products, update_collection_availability, or create_collection, and no stated prerequisites. The only contextual information is a rate-limit pointer, 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.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.4/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 a genuinely useful rate limit (100 requests / 10 seconds per shop) that is not in the annotations, but says nothing about what the destructive effect is or why a 'confirm' parameter exists.

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, front-loaded lines with the rate limit stated first and the action second; nothing is padded. Slightly weakened by the redundant parenthetical restating 'availability'.

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 mutation tool with rich annotations, a clear schema, and no output schema, the description covers the operational constraint an agent most needs (the per-shop rate limit). No return values need explaining.

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% and the schema already documents account, confirm, payload, payload_file, and collection_id. The description adds no parameter-level meaning of its own, 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 names a specific verb and resource: 'Toggle collection availability (available/unavailable)'. It implicitly distinguishes itself from the sibling toggle_product_availability by the 'collection' resource, but it never explicitly contrasts 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?

There is no guidance on when to use this rather than update_collection or toggle_product_availability, nor any stated prerequisites. The '(available/unavailable)' parenthetical describes the state values, not when to invoke it.

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 productsB

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	Explicit approval for this exact provider effect or local private-file operation.
`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

B3.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds two things beyond that: an explicit rate limit (100 req / 10s per shop) and the 'full list' replacement semantics, which implies existing products not in the list are removed. Worth noting: 'sets the full list' reads as idempotent while idempotentHint is false, a mild inconsistency rather than a direct contradiction.

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 is front-loaded before the purpose statement, which is slightly odd ordering for a tool-selection decision, but the description is otherwise tight and earns its length.

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 6-parameter mutation with nested objects and multiple body-passing mechanisms (offerIds, payload, payload_file) and no output schema, the description leaves the agent to reconcile the overlapping input paths and the confirm/account requirements from the schema alone. It is minimally adequate given full schema coverage, but a destructive replace operation would benefit from stating what gets removed.

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, collection_id, account, confirm and payload_file is already documented in the schema. The description restates the offerIds meaning ('product IDs') but adds no syntax, format, or relationship detail (e.g., how offerIds, payload.offerIds and payload_file interact). Baseline 3 for schema-covered 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: 'Sets the full list of product IDs in the collection.' The word 'full' conveys replacement semantics, which distinguishes it in spirit from get_collection_products, update_collection and update_collection_availability. It does not name or explicitly differentiate from those siblings, 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 instead of update_collection (metadata), update_collection_availability, or get_collection_products. The only contextual note is a rate limit, which is not usage selection guidance. The agent must infer from the name that this is the mutation path for collection membership.

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	Explicit approval for this exact provider effect or local private-file operation.
`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.8/5.0

Behavior4/5

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

Annotations already declare destructive=true, openWorld=true and idempotent=false, so the safety profile is covered. The description adds genuinely useful non-schema behavior: server-side validation (duration 20-180s, valid shipping/products), the one-platform-per-shop mutex, and upsert semantics. Minor tension exists between the PUT-upsert framing and idempotentHint=false, and the confirmation/auth requirement is not disclosed.

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?

Three tight sentences, front-loaded with the write scope, then validation/mutex, then the upsert caveat. Every sentence carries distinct information relevant to invocation, with no 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 destructive, 8-parameter upsert with no output schema, the description covers the critical behavioral facts (validation range, per-shop mutex, row materialization). It omits the confirm/account gating and the payload-vs-payload_file exclusivity, which an agent must still discover from 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 75%, so the baseline is 3. The description refers to "four creator-controlled gifting rule fields" and restates the 20-180s duration that is already documented on entryTimeLimitSeconds, but adds no meaning for account, confirm, or the payload/payload_file mutual exclusion, all of which live only in 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: "Writes the four creator-controlled gifting rule fields," which cleanly pairs with the sibling get_gifting_config. It does not explicitly name the read sibling or route between them, but the write-vs-read distinction is unambiguous from the wording.

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 rather than stated: an agent can infer this is the mutation counterpart to get_gifting_config, and the description notes the upsert behavior on first PUT. It gives no explicit when-to-use/when-not-to-use guidance and never names an alternative tool.

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	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`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Explicit approval for this exact provider effect or local private-file operation.
`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.7/5.0

Behavior1/5

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

The description asserts 'Idempotent: no-op if the product is already in the requested state,' but the annotations declare idempotentHint=false. This is a direct contradiction on a behavioral trait an agent uses to decide whether retries are safe. The description also frames the operation as a benign visibility toggle while annotations mark it destructiveHint=true, further muddying the risk profile.

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 with no filler; each sentence carries a distinct fact (rate limit, transition scope, archive exclusion, flag preservation, idempotency). The rate-limit caveat is placed first, which is slightly odd for front-loading but not 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 mutation tool with no output schema and a nested payload/payload_file body, the description covers rate limits, the reachable state set, the excluded ARCHIVED state, flag preservation, and retry behavior. The nested body alternatives are documented in the schema. The one gap is that the idempotency claim is wrong, which undermines completeness on the retry-safety question.

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 product_id, state, account, confirm, payload, and payload_file are all documented in the schema itself, including the enum semantics of state. The description's only added parameter-adjacent value is the availability-flag preservation note, which is already duplicated in the state property description. 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.

Purpose5/5

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

States a specific verb+resource ('Transitions the product between PUBLIC and HIDDEN') and explicitly bounds the scope by naming what is NOT reachable here ('ARCHIVED is not reachable here'), which separates it from the sibling archive_product. An agent can distinguish this from toggle_product_availability and archive_product 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 Guidelines5/5

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

Gives explicit routing: use DELETE /products/{productId} to archive, use PUT /products/{productId}/availability to flip the sold-out flag, and this tool only moves between PUBLIC and HIDDEN. Both the when-to-use and when-not-to-use conditions are stated, along with the sibling operation for each excluded case.

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

update_promotionUpdate a promotionB

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	Explicit approval for this exact provider effect or local private-file operation.
`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

B3.4/5.0

Behavior4/5

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

Adds real context beyond the annotations: an explicit rate limit (100 requests / 10 seconds per shop) and merge/patch semantics for omitted fields. Annotations already declare destructive=true, idempotent=false, openWorld=true, so the safety profile is covered; the description usefully complements it. It does not disclose whether updates are reversible or what authorization is required.

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-loads the rate limit, then two tight sentences covering update semantics and status handling. No filler. Slightly dense in a single opening block but every sentence 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?

For a 9-parameter destructive mutation with nested objects, no output schema, and mid-range schema coverage, the description covers the essentials (rate limit, partial update, status) but omits the payload vs. payload_file vs. body-flags choice and any auth/confirm guidance, leaving meaningful gaps an agent would need to fill from the schema.

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 56% and the description adds almost no parameter meaning. It never clarifies the relationship between the top-level fields (limits/status/appliesTo/requirements), the payload object, and payload_file, even though the schema itself flags these as mutually exclusive and nested. Only the status parameter is obliquely touched via 'status changes'.

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.' An agent can distinguish it from create_promotion/get_promotion. It stops short of explicitly differentiating from siblings or stating what a promotion is, but the intent 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 Guidelines3/5

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

Gives partial-update semantics ('only provided fields are updated; omitted fields remain unchanged') and notes that status changes go through the same call, which is useful usage context. However, it never says when to use this over alternatives, nor mentions prerequisites such as the confirm/account parameters or which promotion states are eligible.

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	Explicit approval for this exact provider effect or local private-file operation.
`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?

Annotations already declare that the operation is destructive, non-idempotent, open-world, and not read-only. The description adds a concrete rate limit of 100 requests per 10 seconds per shop, which is useful behavioral context beyond the annotations, but it does not explain update semantics, partial-update behavior, 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?

It is only two short lines, with the rate-limit constraint front-loaded and no wasted words. However, the second sentence is essentially tautological, so conciseness comes at the cost of useful content.

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 tool with seven parameters and a nested payload object, the description is far too thin. It provides a rate limit and the tool title, but omits what fields can be updated, how payload and payload_file interact, and what the update affects.

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 gives no parameter meaning at all. With 71% schema description coverage, the schema documents several parameters, but the description does nothing to clarify update-specific fields such as url, allowedTypes, payload, or 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 rather than explaining what can be updated. It does not distinguish this tool from sibling webhook operations such as 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 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_webhook, create_webhook, delete_webhook, or other update tools. The rate-limit note is operational context, not usage selection guidance.

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 receiptC

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private shop profile label; not a provider identity or authorization proof.
`confirm`	No	Explicit approval for this exact provider effect or local private-file operation.
`input_file`	Yes
`receipt_file`	Yes

TDQS

C2.1/5.0

Behavior2/5

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

Annotations already disclose readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description redundantly restates that it is an explicit PUT with 'explicitly confirmed' approval, adding little beyond the destructive/non-idempotent profile. It does not explain irreversibility, what gets overwritten, or auth requirements beyond 'no Fourthwall credentials.'

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 compact and front-loaded with the core action, but the dense jargon makes it less readable than a plain statement would be, and 'exact size/Content-Type and x-goog-content-length-range are preserved' is detail that could be trimmed.

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, open-world upload with no output schema, the description omits the receipt/input file lifecycle, failure modes, and what the agent should do after a successful PUT. It never mentions the sibling confirm_digital_file_upload, so the agent lacks the surrounding workflow context.

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 coverage is only 50%. The description clarifies that receipt_file and input_file are a private receipt and a local regular file, but it does not map or explain account or confirm beyond what the schema already says. The two required parameters are implied, not documented, leaving gaps for a 4-parameter tool.

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 it is a 'Google Storage PUT' from a 'private upload receipt' to a 'bounded local regular file,' which is a specific action, but the vocabulary (private receipt, bounded local regular file, content-length-range) is opaque and not differentiated from related siblings like request_digital_file_upload_url or confirm_digital_file_upload. An agent cannot quickly tell what resource is being uploaded or how it relates to the receipt flow.

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 or when-not-to-use guidance. The phrase 'no automatic registration/publishing' implies a boundary but does not name siblings or prerequisites, so the agent must infer when this exact-bytes PUT is preferred over the request/confirm upload siblings.

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	Explicit approval for this exact provider effect or local private-file operation.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare non-read-only, non-idempotent, open-world, destructive behavior; the description adds the useful operational context that this contacts actual DNS servers and mutates verification status, plus a concrete rate limit. It stops short of saying whether re-running is safe or how long propagation takes, which matters given 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, zero waste: the rate-limit caveat is front-loaded and the operational effect follows immediately. Nothing redundant with the title.

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 two-parameter mutation with no output schema, the description covers the effect, the external interaction, and the rate limit. It leaves implicit that a 'confirm' flag gates a destructive-ish effect, but the schema covers that, so coverage is adequate.

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 the 'account' and 'confirm' semantics are already documented in the schema; the description adds no parameter detail, 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+resource: 'Triggers a live DNS validation by checking all configured records against actual DNS servers and updates their verification status.' The scope (all configured records, live check, status update) is concrete and an agent can distinguish it from get_dns_status, a read of current status. However, the description never names that sibling, so the differentiation is inferential rather than explicit.

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?

Provides a rate limit (20 requests/minute per shop) but no when-to-use guidance: it doesn't say when to trigger validation versus checking get_dns_status, nor what prerequisites must hold before a live check is meaningful. No exclusions or alternatives are named.

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.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.8/5.0

Scored 2026-10-04 00:45 across 86 tools

Disambiguation2/5

Multiple tools have unclear boundaries: nine product-template tools (list/search/paged/grouped/by-category variants) overlap heavily, finish_giveaway vs finish_giveaway_draw are nearly identical, and update_collection overlaps with update_collection_products. Descriptions help somewhat but do not resolve which variant to pick in common cases.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (e.g., list_products, get_order, create_webhook, update_promotion, archive_product). There are no mixed conventions like camelCase or vague verbs.

Tool Count1/5

86 tools is far beyond a well-scoped set (typically 3-15) and is extreme even for a broad platform, with many redundant variants. The count creates a high risk of misselection and cognitive overload.

Completeness3/5

The surface covers many resources (products, orders, collections, promotions, giveaways, webhooks, media, reports, etc.), but notable gaps exist such as no general update_product for name/description/price, no delete for collections or promotions, and limited order modification. Agents can work around some gaps but will hit dead ends for common updates.

Maintenance

ActivityNo data

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

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
mcp-gateway A
xyz.trusteed
Agentic commerce gateway: discovery, search, checkout across Shopify/Woo/Odoo/PrestaShop.
E-commerce & Retail Search
232
SentinelX MCPOAuth
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
210
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 8 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
D
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)
28 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-09-30 21:00 UTC)
363 npm
18
MIT
shopify-graphql-mcp
E-commerce & Retail CRM Marketing
UVU-Store
A
license
C
quality
D
maintenance
A Model Context Protocol server that provides comprehensive access to the Shopify Admin GraphQL API, enabling AI assistants to manage Shopify stores programmatically.
Updated 7 months ago (2026-03-11 15:18 UTC)
100
1
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

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

get_order