Setting the file. One moment.
Subchapter 2.3
references/APP_TOOLS.mdMarkdown6 KBView on GitHub
App Tools lets your app expose custom tools that the Wix AI assistant can discover and invoke on behalf of site collaborators. It requires two extensions working together:
| Extension | What it does |
|---|
| Reference |
|---|
APP_TOOLS | Declares your tools (names, descriptions, schemas) so the AI assistant knows they exist | app-tools/TOOLS.md |
TOOLS_PROVIDER_CONFIG | The service plugin handler Wix calls at runtime when the AI assistant invokes a tool | service-plugin/TOOLS_PROVIDER.md |
Developer declares tools in APP_TOOLS
↓
AI assistant reads declarations to understand available tools
↓
User interacts with Wix AI assistant
↓
AI assistant invokes your toolsProvider service plugin (runTool handler)
↓
Your handler routes on methodName, runs business logic, returns response
↓
AI assistant uses the response to answer the userThe methodName field is the linking key: it must match exactly between the APP_TOOLS declaration and the switch (or routing map) in your runTool handler.
Adding another tool to an existing setup? Skip this step. Add the new tool entry to your existing
APP_TOOLS.extension.tsfile and add a matchingcaseto your existingrunToolhandler — no new extensions needed.
Run these two commands once — the CLI generates all files and updates src/extensions.ts automatically:
wix generate --params '{"extensionType":"APP_TOOLS","name":"my-tools"}'
wix generate --params '{"extensionType":"SERVICE_PLUGIN","pluginType":"TOOLS_PROVIDER_CONFIG","name":"my-tools-provider"}'Open the generated src/extensions/backend/app-tools/my-tools/my-tools.extension.ts and replace the stub tool with your own. Read app-tools/TOOLS.md for the full field reference and constraints.
import { extensions } from '@wix/astro/builders';
export default extensions.appTools({
id: '<generated-uuid>',
name: 'my-tools',
tools: [
{
methodName: 'get-order-status',
description: 'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order. Use this tool when a collaborator or customer asks where their order is, whether it has shipped, when it will arrive, or needs a tracking number. Requires a valid orderId.',
requestSchema: {
type: 'object',
properties: {
orderId: { type: 'string' }
},
required: ['orderId']
},
responseSchema: {
type: 'object',
properties: {
status: { type: 'string' }
}
},
activated: true
}
]
});Open the generated src/extensions/backend/service-plugins/my-tools-provider/my-tools-provider.ts and implement the runTool logic. Read service-plugin/TOOLS_PROVIDER.md for the full implementation guide.
import { toolsProvider } from '@wix/app-tools/service-plugins';
toolsProvider.provideHandlers({
runTool: async ({ request, metadata }) => {
const { methodName, payload } = request;
switch (methodName) {
case 'get-order-status': {
const orderId = payload?.['orderId'];
if (typeof orderId !== 'string' || !orderId) {
throw new Error('orderId is required');
}
// your logic here
return { response: { status: 'shipped' } };
}
default:
throw new Error(`Unknown tool: ${methodName}`);
}
}
});The description field is the primary signal the AI assistant uses to decide whether your tool is relevant to a user’s request. A one-liner like "Returns order status" works technically but limits relevance matching.
Write descriptions as a short prompt — 2–4 sentences covering:
// narrow — easy to miss
'Returns order status.'
// wide — reliably matched
'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order.
Use this tool when a collaborator or customer asks where their order is, whether it has shipped,
when it will arrive, or needs a tracking number. Requires a valid orderId.'.extension.ts (replace the stub myMethod)activated: true on every tool you want the AI assistant to invoke (activated: false tools are declared but never called)runTool handler covers every methodName that has activated: trueauth.elevate from @wix/essentialswix build) and released (wix release) — changes don’t take effect until releasedrequestSchema and responseSchema in APP_TOOLS are advisory — the AI assistant uses them for context. Wix does NOT validate the payload against the schema before calling your handler.activated: true are invoked by the AI assistant.methodName must be unique within an APP_TOOLS extension (1–30 characters).