Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

# App Tools Extension Files and Code

When you add an [App Tools](fallback::https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/app-tools) extension to a Wix CLI or Wix-managed headless project, the CLI adds the following file to your project:

- `<your-extension-name>.extension.ts`: The [App Tools builder](fallback::#app-tools-builder), which declares the tools your app exposes to [Aria](fallback::https://dev.wix.com/docs/overview/ai-the-wix-platform/about-aria), Wix's AI assistant.

The CLI creates the file in the following default folder structure:

```bash
src/
  └── extensions/
      └── backend/
          └── app-tools/
              └── <your-extension-name>/
                  └── <your-extension-name>.extension.ts
```

The CLI also registers the extension in `src/extensions.ts`, the entry point that lists every extension in your app. If you don't pass an extension to `app().use()`, it isn't part of your app:

```typescript
// Wix-managed app
import { app } from '@wix/custom-extensions';
```

```typescript
// Wix-managed headless project
import { app } from '@wix/astro/builders';
```

```typescript
import appTools from './extensions/backend/app-tools/<your-extension-name>/<your-extension-name>.extension.ts';

export default app().use(appTools);
```

You can move the file anywhere inside the `src/` folder as long as you update its path in `src/extensions.ts`.

An App Tools extension only declares your tools. To run them, you also add a Tools Provider service plugin. Learn more about the [Tools Provider handler](fallback::https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/introduction#tools-provider-handler).

## App Tools builder

The `<your-extension-name>.extension.ts` file declares the tools your app exposes to Aria. After you build and release your app, Aria uses these declarations to discover which tools exist and decide when to call them. This file shouldn't contain any business logic.

Import `extensions` from the package your project uses:

```typescript
// Wix-managed app
import { extensions } from '@wix/custom-extensions';
```

```typescript
// Wix-managed headless project
import { extensions } from '@wix/astro/builders';
```

The file uses the following schema:

```typescript
export default extensions.appTools({
  id: string,     // Auto-generated UUID. Don't change this manually.
  name: string,   // Internal name for this group of tools.
  tools: [        // Array of tool declarations. Min 1, max 100.
    {
      methodName: string,       // Required. Unique identifier for this tool.
      description: string,      // Required. Used by Aria to decide when to call the tool.
      requestSchema: object,    // Optional. JSON Schema for the input.
      responseSchema: object,   // Optional. JSON Schema for the output.
      activated: boolean        // Required. Whether Aria can call this tool.
    }
  ]
});
```

Here's an example file with a single tool declaration:

```typescript
export default extensions.appTools({
  id: '00eeeac1-d01a-4d96-9d76-5617d8658735',
  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 Wix user asks where their order is, whether it has shipped, or needs a tracking number. ' +
        'Requires a valid orderId.',
      requestSchema: {
        type: 'object',
        properties: {
          orderId: { type: 'string', description: 'The order ID to look up.' }
        },
        required: ['orderId']
      },
      responseSchema: {
        type: 'object',
        properties: {
          status: { type: 'string' },
          trackingNumber: { type: 'string' }
        }
      },
      activated: true
    }
  ]
});
```

### App Tools extension configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | Auto-generated UUID that uniquely identifies this extension. |
| `name` | `string` | Yes | Internal name for this group of tools. |
| `tools` | `array` | Yes | Array of tool declarations. Max: 100. |
| `tools[].methodName` | `string` | Yes | Unique identifier for the tool. Used to route calls in the [Tools Provider](fallback::https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/introduction) handler. Max: 30 characters. |
| `tools[].description` | `string` | Yes | Description Aria uses to decide when to call the tool. 10 to 1000 characters. See [effective tool descriptions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions#effective-tools) for guidance. |
| `tools[].requestSchema` | `object` | No | JSON Schema describing the tool's input. Helps Aria determine what information to gather before calling the tool. |
| `tools[].responseSchema` | `object` | No | JSON Schema describing the tool's output. |
| `tools[].activated` | `boolean` | Yes | Whether Aria can call this tool. Set to `true` for tools you want Aria to call. |

> **Note:** Wix doesn't check the `payload` Aria sends against your `requestSchema` before calling your handler. Handle missing or unexpected fields in your implementation.

## See also

- [App Tools](fallback::https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/app-tools)
- [About the Tools Provider Service Plugin](fallback::https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/introduction)
- [Service Plugin Extension Files and Code](resourceId::9e2fd9d6-0da1-4b99-a819-502e2fa00d54*fallback::https://github.com/wix-private/developer-docs/blob/4e26c6081490f4abebb7ad0fe616382b36a7e3e6/references/backend-extensions/service-plugins/service-plugin-extension-files-and-code.md*original::../service-plugins/service-plugin-extension-files-and-code.md)
- [Sample Flows](fallback::https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/sample-flows)

Field	Type	Required	Description
`id`	`string`	Yes	Auto-generated UUID that uniquely identifies this extension.
`name`	`string`	Yes	Internal name for this group of tools.
`tools`	`array`	Yes	Array of tool declarations. Max: 100.
`tools[].methodName`	`string`	Yes	Unique identifier for the tool. Used to route calls in the Tools Provider handler. Max: 30 characters.
`tools[].description`	`string`	Yes	Description Aria uses to decide when to call the tool. 10 to 1000 characters. See effective tool descriptions for guidance.
`tools[].requestSchema`	`object`	No	JSON Schema describing the tool's input. Helps Aria determine what information to gather before calling the tool.
`tools[].responseSchema`	`object`	No	JSON Schema describing the tool's output.
`tools[].activated`	`boolean`	Yes	Whether Aria can call this tool. Set to `true` for tools you want Aria to call.