Agent tools - PlatformDTC

Merchants run their store with an AI assistant: Claude, ChatGPT, Codex, Cursor or the PlatformDTC dashboard Assistant, all connected to https://api.platformdtc.com/mcp. Agent tools put your app in that assistant’s hands. A merchant who installed your loyalty app can say “give Maria 500 points for the late delivery”, and the assistant calls your award_points tool. You never share your database. You declare what the assistant may ask your app to do, and your server does it. Apps plug in two ways:

	What you do	What the assistant gets
Actions (this page)	Declare tools on an app version; answer signed calls at your HTTPS endpoint	New tools in its list, only on stores that installed your app
Data (below)	Write your data into metafields and metaobjects your app owns	Reads them with the tools it already has

Coming from Shopify? Agent tools are the PlatformDTC version of Sidekick app extensions. The declaration is the same idea (a name, a description and a JSON Schema input, 20 per app, shipped with an app version). The difference is where the tool runs: on Shopify it runs in the admin’s browser sandbox; here the merchant’s agent is outside any browser, so the platform calls your server with a signed request, like a webhook.

1. Declare tools on a version

Tools belong to an app version, next to its scopes and extensions. Send them as agent_tools when you create the version:

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/apps/$APP_ID/versions \
  -H "Authorization: Bearer $PARTNER_JWT" -H "X-CSRF-Token: $CSRF" -H "Content-Type: application/json" \
  -d @version.json

version.json

{
  "requested_scopes": ["read_customers", "write_customers"],
  "scope_justifications": {
    "read_customers": "Show each customer's points balance",
    "write_customers": "Tag customers when they reach a reward tier"
  },
  "agent_tools": [
    {
      "name": "award_points",
      "title": "Award loyalty points",
      "description": "Adds loyalty points to one customer. Use when the merchant asks to reward or compensate a customer. Returns the new balance.",
      "input_schema": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string", "description": "PlatformDTC customer id (from dtc_list_customers)" },
          "points": { "type": "integer", "minimum": 1, "maximum": 100000 },
          "reason": { "type": "string" }
        },
        "required": ["customer_id", "points"]
      },
      "required_scopes": ["write_customers"],
      "url": "https://loyalty.example.com/agent/award_points"
    },
    {
      "name": "get_balance",
      "title": "Look up a points balance",
      "description": "Returns a customer's points balance and tier.",
      "input_schema": {
        "type": "object",
        "properties": { "customer_id": { "type": "string" } },
        "required": ["customer_id"]
      },
      "required_scopes": ["read_customers"],
      "url": "https://loyalty.example.com/agent/get_balance",
      "read_only": true
    }
  ]
}

Field	Required	Rules
`name`	yes	`^[a-z][a-z0-9_]{0,39}$`, unique within the version.
`title`	yes	1–64 characters. The merchant reads this: on your App Store listing and on approval requests. Say what it does in plain words.
`description`	yes	1–512 characters. The assistant reads this to decide when to call the tool. Say when to use it and what it returns.
`input_schema`	yes	A JSON Schema object with `"type": "object"`, at most 16 KiB.
`required_scopes`	yes	1–10 scopes, each one of the version’s `requested_scopes` or `optional_scopes`.
`url`	yes	A public `https` URL, at most 1,024 characters. Not `localhost`, not a private IP.
`read_only`	no	`true` for tools that change nothing. Tells the assistant it can call it freely. Default `false`.
`requires_approval`	no	`true` to make the merchant approve every call first. Always on when a required scope moves money or contacts customers (see Approval). A read-only tool cannot require approval.

Limits: 20 tools per version. Skill and built-in apps cannot declare tools (they have no server to call). A version is fixed once created: to change a tool, create a new version and submit it for review, exactly like a scope change. When you submit the version, review sends each tool’s url one call signed with the wrong secret (shop app-review.invalid, empty arguments). Every tool must answer 401, or the agent_tools_reject_invalid_signature requirement fails. The review team reads your tools with the rest of the version. Keep each tool inside what your app does and what your listing says, and never use a tool to promote other products or ask for reviews.

2. What the assistant sees

On a store where your app is installed, the assistant’s tool list gains your tools, named

app_<your app handle>__<tool name>        e.g. app_loyalty-pro__award_points

and titled "<App name>: <title>". If that name would pass 64 characters (the limit most AI clients enforce), the handle is shortened and given a 6-character suffix; your test call shows the exact name. A tool is listed only when all of these hold, checked on every list and every call:

your app is installed on that store and not suspended, and the tool is on the version that install approved;
the merchant granted every one of the tool’s required_scopes to your app (a declined optional scope hides the tool);
the merchant’s assistant also holds every one of those scopes. An assistant the merchant connected read-only never sees your write tools, so your app can never give an assistant more power than the merchant gave it;
the caller is the merchant’s assistant or the merchant, not another app. Apps do not call each other’s tools.

When the merchant uninstalls your app, or your app is suspended, its tools disappear at once.

3. Handle the call

Each call is a POST to the tool’s url:

POST /agent/award_points
Content-Type: application/json
User-Agent: PlatformDTC-AgentTools/1
X-PlatformDTC-Signature: sha256=<hex HMAC-SHA256(client_secret, raw_body)>
X-PlatformDTC-Tool: award_points
X-PlatformDTC-Shop: acme.myshopquantum.ai
Idempotency-Key: mcp-3f1c…

{
  "tool": "award_points",
  "arguments": { "customer_id": "c_81f…", "points": 500, "reason": "Late delivery" },
  "shop": "acme.myshopquantum.ai",
  "store_id": "…",
  "app_install_id": "…",
  "idempotency_key": "mcp-3f1c…",
  "request_id": "…",
  "timestamp": 1727500000,
  "actor": { "type": "agent" }
}

actor.type is agent when the merchant’s assistant made the call and merchant when the merchant made it from the dashboard. shop and store_id tell you which store to act on; use the access token your app got when that store installed it.

Verify it

The signature is the same algorithm and the same client_secret as your webhooks: HMAC-SHA256(client_secret, raw_body), hex, prefixed sha256=. Compute it over the raw request bytes, compare in constant time, then:

Answer 401 on a bad signature.
Refuse a timestamp more than 5 minutes old (replay protection).
De-duplicate on idempotency_key. A retried call carries the same key: do the work once and answer the saved result again.

import hashlib, hmac, json, time

def verify(client_secret: str, raw_body: bytes, header: str) -> dict | None:
    expected = "sha256=" + hmac.new(client_secret.encode(), raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, header or ""):
        return None                       # → 401
    call = json.loads(raw_body)
    if abs(time.time() - call["timestamp"]) > 300:
        return None                       # → 401, too old
    return call                           # then check call["idempotency_key"] against your store

import crypto from "node:crypto";

export function verify(clientSecret, rawBody, header) {
  const expected = "sha256=" + crypto.createHmac("sha256", clientSecret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header || "");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return null; // → 401
  const call = JSON.parse(rawBody);
  if (Math.abs(Date.now() / 1000 - call.timestamp) > 300) return null;     // → 401, too old
  return call; // then check call.idempotency_key against your store
}

During the 72-hour secret-rotation grace, accept a body that verifies against either secret.

Answer it

Answer within 10 seconds with JSON. What you return is what the assistant reads, so keep it small and plain: the facts it needs to answer the merchant, not your whole record.

Your answer	What the assistant gets
`2xx` with a JSON object or array, at most 64 KiB	The JSON, as the tool’s result
`2xx` that is not JSON	Error `APP_BAD_RESPONSE`
A body over 64 KiB	Error `APP_RESPONSE_TOO_LARGE`
`4xx`	Error `APP_ERROR` with your status and your message: the first string found in `message`, `error` or `error.message`, up to 500 characters
`5xx`, a redirect, or a network error	Error `APP_UNAVAILABLE`
No answer in 10 s	Error `APP_TIMEOUT`

Use 4xx for anything the assistant can fix: a customer that does not exist, a value out of range. A clear message such as {"message": "Customer c_81f has no loyalty account yet"} lets it correct the call or explain the problem to the merchant. Redirects are not followed: answer at the URL you declared. Before calling you, the platform checks that arguments is a JSON object (at most 256 KiB) with every top-level required property of your input_schema. Validate the rest yourself and answer 422 with a message when it is wrong.

4. Tools that need the merchant’s approval

A tool with requires_approval: true, or any tool needing a scope that moves money or contacts customers (write_discounts, write_gift_cards, marketing:send, ads:write, checkout:recover, store:publish, publish_themes), never runs straight from the assistant:

The assistant’s call comes back as pending_approval with a job id. Your server is not called yet.
The merchant sees the request in their dashboard (Agents, under Waiting for you) as “App action”, with your app name and the tool’s title, and approves or denies it.
On approval, the platform checks again that your app is still installed with those scopes, then calls your tool exactly as above. The assistant reads your result from the job.

When the merchant uses the tool themselves from the dashboard, they are the approver and it runs at once.

5. Limits and reliability

60 calls per minute per store for each installed app. Past that the assistant gets RATE_LIMIT_EXCEEDED with a Retry-After.
Circuit breaker. After 5 failures in a row (5xx, network errors, timeouts; not 4xx), calls to your app stop for 30 seconds and fail at once with APP_UNAVAILABLE, then one call is let through to test you. A slow or down app cannot slow the merchant’s assistant down.
Every call is recorded in the merchant’s agent audit log with your app, the tool and the outcome.

6. Test a tool

In the Partner dashboard, open your app → Versions, expand a version and choose Test next to a tool. Pick one of your development stores, enter arguments, and the platform sends the exact production request (same envelope, signature and limits) to your URL. You see the status, the time it took, the name the assistant will see, and your response or the error it would get. The same test is available over the API (10 calls a minute per app; you must be an owner, admin or developer of the app’s partner organization):

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner-agent-tools/apps/$APP_ID/test \
  -H "Authorization: Bearer $PARTNER_JWT" -H "Content-Type: application/json" \
  -d '{"version_id":"…","tool":"get_balance","store_id":"<development store id>","arguments":{"customer_id":"c_81f…"}}'

{ "ok": true, "status_code": 200, "duration_ms": 142, "agent_name": "app_loyalty-pro__get_balance",
  "result": { "points": 1250, "tier": "Gold" } }

A failed test returns "ok": false and error: {code, message} with the same codes as the table above.

7. Declare tools with the CLI

With the CLI, agent tools live in an extension folder, like Shopify’s tools.json:

extensions/assistant/platformdtc.extension.toml

type = "agent_tools"
handle = "assistant"
name = "Assistant tools"
tools = "tools.json"

tools.json is the agent_tools array from step 1. A tool’s url may also be a path such as "/agent/award_points", resolved against your application_url. dtc app deploy (and dtc app config push) checks every rule above before sending, and puts the array on the new version. An app has at most one agent_tools folder. See App configuration. Some things are better read than called. Write them into custom data your app owns, and the merchant’s assistant reads them with the tools it already has. Nobody else can change them.

	Your app	The merchant and their assistant	Other apps
Your metafields (namespace `$app` or `$app:<sub>`)	read and write	read	cannot see them
Your metaobjects (type `$app:<type>`)	read and write	read	cannot see them

Use your app’s access token (the sq_agt_… key your app got at install). The platform stores $app as app--<your app id> and $app:<sub> as app--<your app id>--<sub>, and returns the stored form in responses. Writing an app--… namespace or type that is not yours is refused (403), and $app from anything but an app token is a 400. The merchant’s dashboard shows your data read-only. When a merchant uninstalls your app, your data stays for 48 hours, the same window as shop/redact. If they reinstall inside it, nothing is lost. After it, the platform deletes your metafields and metaobjects on that store, just before it sends shop/redact. Your metafield definitions go once your app is installed on none of the merchant’s stores. Metafields (reference, scopes read_metafields / write_metafields):

curl -X POST https://api.platformdtc.com/api/v1/metafields \
  -H "Authorization: Bearer $APP_TOKEN" -H "X-Store-ID: $STORE_ID" -H "Content-Type: application/json" \
  -d '{"owner_type":"customer","owner_id":"c_81f…","namespace":"$app:loyalty","key":"tier","type":"single_line_text_field","value":"Gold"}'

Metaobjects (Agent Gateway, scopes store:read / store:write; writes need an Idempotency-Key):

curl -X POST https://api.platformdtc.com/api/v1/agent/v1/metaobjects \
  -H "Authorization: Bearer $APP_TOKEN" -H "X-Store-ID: $STORE_ID" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"$app:reward","handle":"free-shipping","display_name":"Free shipping","fields":{"cost_points":500}}'

Update one by sending its metaobject_id in the same body; list yours with GET /api/v1/agent/v1/metaobjects?type=$app:reward. The merchant’s assistant finds them with dtc_list_metaobjects and dtc_get_metaobject.

​1. Declare tools on a version

​2. What the assistant sees

​3. Handle the call

​Verify it

​Answer it

​4. Tools that need the merchant’s approval

​5. Limits and reliability

​6. Test a tool

​7. Declare tools with the CLI

​Share data with the assistant

1. Declare tools on a version

2. What the assistant sees

3. Handle the call

Verify it

Answer it

4. Tools that need the merchant’s approval

5. Limits and reliability

6. Test a tool

7. Declare tools with the CLI

Share data with the assistant