/wix-app

Tools Provider Service Plugin Reference

Overview

The Tools Provider SPI lets your app handle tool invocations from the Wix AI assistant. Implement the runTool handler — it receives the tool's methodName and a JSON payload, runs your business logic, and returns a response the AI assistant uses to answer the user.

This is the execution side of the App Tools feature. The declaration side lives in the APP_TOOLS extension. See APP_TOOLS.md for the full picture.

Request and Response Schema

Before implementing, call ReadFullDocsMethodSchema on the docs URL to get the full request/response types.

Example: Routing Tool Calls by methodName

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');
        }
        // fetch order status...
        return {
          response: {
            status: 'shipped',
            trackingNumber: 'TRACK123'
          }
        };
      }

      default:
        throw new Error(`Unknown tool: ${methodName}`);
    }
  }
});

Manual Setup Required

This handler is only invoked by the real Wix AI assistant deciding a tool is relevant — there's no direct API to force-invoke a specific tool for testing. Two things must both be true before it can fire at all: (1) a paired APP_TOOLS extension declares the tool with activated: true (see APP_TOOLS.md), and (2) a user actually asks the AI assistant something the tool's description matches. Verify by asking the assistant a matching question on the live site, not by calling this handler directly.

Key Implementation Notes

1. Route on methodName — use a switch or map to dispatch to the right handler logic
2. Validate inputs defensively — requestSchema is advisory for the AI assistant; Wix does not validate the payload before calling your handler
3. Handle all activated tools — cover every methodName with activated: true in your APP_TOOLS declaration; unhandled names should throw a clear error
4. Respond quickly — the AI assistant is waiting; slow responses degrade the user experience
5. Elevate permissions for Wix API calls — wrap SDK methods with auth.elevate from @wix/essentials