> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Sample Flows

## Article: Sample use cases

## Article Link: https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/sample-flows.md

## Article Content:

# Tool Providers: Sample Flows

This article presents a possible use case and corresponding sample flow that you can support. This can be a helpful jumping off point as you plan your implementation.

## Get a package's status with Aria

Your app integrates with a 3rd-party shipping service to track packages. You can expose that tracking capability as a tool so [Aria](https://dev.wix.com/docs/overview/ai-the-wix-platform/about-aria.md) can look up shipment status for a Wix user during a chat. 

### App configuration prerequisites

1. In the **[App Tools](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md)** extension, define your tool using JSON:

```json
{
  "tools": [
    {
      "methodName": "getPackageTracking",
      "description": "Fetches the current tracking status of a package by its tracking number. Returns status, location, and estimated delivery date. Use when the Wix user wants to know where their package is or when it will arrive.",
      "requestSchema": {
        "type": "object",
        "required": ["trackingNumber"],
        "properties": {
          "trackingNumber": {
            "type": "string",
            "description": "The carrier tracking number for the package, for example '1Z999AA10123456784'."
          }
        }
      },
      "responseSchema": {
        "type": "object",
        "properties": {
          "trackingNumber": {
            "type": "string",
            "description": "The tracking number this result corresponds to."
          },
          "status": {
            "type": "string",
            "description": "Current shipment status, for example 'in transit', 'delivered', 'out for delivery', or 'delayed'."
          },
          "location": {
            "type": "string",
            "description": "Last known location of the package."
          },
          "estimatedDelivery": {
            "type": "string",
            "description": "Estimated delivery date in ISO 8601 format (YYYY-MM-DD), if available."
          }
        }
      },
      "activated": true
    }
  ]
}
```

2. In the **[Tools Provider Config](https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/extension-config.md)** extension, set your service plugin base URI. This enables Wix to locate your method implementation and invoke it.


3. Implement `runTool` so Wix can call your package-tracking method. Your handler routes on `methodName`, looks up the shipment, and returns the result:

```js
import { toolsProvider } from '@wix/app-tools/service-plugins';

toolsProvider.provideHandlers({
  runTool: async ({ request }) => {
    const { methodName, payload } = request;

    switch (methodName) {
      case 'getPackageTracking': {
        // Make sure to validate. Wix doesn't validate the payload against requestSchema. 
        const trackingNumber = payload?.trackingNumber;
        if (!trackingNumber) {
          throw new Error('trackingNumber is required');
        }

        // Look up the shipment in your system or a 3rd-party carrier API
        const shipment = await getShipmentByTrackingNumber(trackingNumber);

        return {
          response: {
            trackingNumber,
            status: shipment.status,
            location: shipment.location,
            estimatedDelivery: shipment.estimatedDelivery
          }
        };
      }
      // Handle other tools...
    }
  }
});
```

> **Note:** Wix doesn't check if `payload` matches your `requestSchema` before calling your service plugin. Handle missing or unexpected fields in your implementation. If your implementation returns an error or times out, Aria continues the conversation without the tool result.

### The flow

To track a package when a Wix user asks Aria for shipping status:

1. The Wix user asks Aria a question. For example, "Where's the package?".
1. Aria reads the active tools and selects `getPackageTracking` based on the tool's description.
1. Aria uses the request schema to ask the Wix user for a tracking number if they haven't provided one yet.
1. Once the Wix user provides the tracking number, Wix calls [Run Tool](https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/run-tool.md) on your service with a request like this:

```json
{
  "methodName": "getPackageTracking",
  "payload": {
    "trackingNumber": "4455dd"
  }
}
```

1. Your [`runTool`](https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/run-tool.md) handler returns a response like this:

```json
{
  "response": {
    "trackingNumber": "4455dd",
    "status": "In Transit",
    "location": "Distribution Center, New York",
    "estimatedDelivery": "2026-07-30"
  }
}
```

1. The service plugin passes the response back to Aria, which tells the Wix user the package is in transit and shares the location and estimated delivery date in natural language.