Tools for the merchant's assistant

Every Storeware admin has an assistant the merchant talks to. Your app can give it tools, so a merchant can ask "draft a restock email for the boots" and the assistant asks your app to do it.

Declare themCopy Anchor Link

[[assistant.tools]] takes the same keys as [[mcp.tools]], plus read_only:

[oauth]
scopes = ["products:read"]

[[assistant.tools]]
name = "summarise_reviews"
description = "Summarises what shoppers say about a product in its reviews."
url = "https://reviews.example.com/assistant/summarise"
scopes = ["products:read"]
read_only = true
input_schema = { type = "object", properties = { product_handle = { type = "string" } }, required = ["product_handle"] }

[[assistant.tools]]
name = "draft_campaign"
description = "Drafts a restock email in the app for the products the merchant names."
url = "https://reviews.example.com/assistant/draft-campaign"
scopes = ["products:read"]

The keys are the same as an MCP tool's, listed in the manifest reference. The assistant sees a tool as app_<your slug>_<name>. An app may declare up to 20. The merchant sees each one on your app's permissions screen before they install it, and a release that adds a tool, or turns a read into a write, is asked about again.

Writes wait for the personCopy Anchor Link

A tool is a write unless it says read_only = true, which a tool with a :write scope cannot. The assistant holds a write only once the person has said it may change things for that question, and a background run never holds an app's tool. The assistant runs as the person, so a tool is offered only when your app was granted its scopes and the person holds them too.

The callCopy Anchor Link

Storeware posts to url, signed the way a webhook is, with your installation's secret. Verify it as you verify an MCP tool call, with app.verifyRequest(request, 'tool'):

{
  "tool": "draft_campaign",
  "arguments": { "products": ["fjell-boot"] },
  "surface": "assistant",
  "store_id": "8c1f...",
  "installation_id": "5a2e...",
  "actor_type": "staff",
  "request_id": "req_..."
}

surface is assistant here and agent for an MCP tool. Answer JSON within five seconds; the model reads up to 16,000 characters. The call goes to the release that shop is on, hosted or not.

The assistant names your appCopy Anchor Link

Your app's name is on the line the merchant watches while it works and in every answer the model reads, and the assistant says which app it asked. A write is listed with what it changed, linked to your app's page.

Being foundCopy Anchor Link

Ask the assistant "is there an app that does this?" and it ranks every public listing by meaning against the need, from its name, tagline, categories, tags and description. Each app it names links to its permissions screen, where the merchant decides; it never installs anything. Those installs are recorded with the source assistant.

Apps merchants are asking forCopy Anchor Link

When the assistant finds no app for a need, or a merchant asks for one in the App Store, the need is counted. Developer, Apps merchants ask for lists needs asked at least twice in 90 days, with counts. No merchant's name or shop is kept, only the words and the day.