# Connect the assistant to your business tools

A client tool lets the assistant call a function in the customer's browser. That
function can call your existing authenticated backend to look up an order, check
availability or perform an authorized business action.

## Keep business access on your server

The flow is: customer conversation → browser tool → your authenticated server
route → existing service client. Your server derives customer/tenant identity,
validates inputs and decides what the customer may access. Tool arguments and
model output are untrusted input, not proof of ownership.

Client tools run only during a live browser session. They do not create a native
provider integration, an unattended job, or a tool for voice/SMS/email agents.

## Example: order lookup

This browser-side example expects your application to implement
`GET /api/support/orders/:id`. That is your route, not a Masheev endpoint.

```ts
import { init, type ClientToolDefinition } from "@masheev/embed-sdk/js";

const lookupOrder: ClientToolDefinition = {
  name: "lookup_order",
  description: "Look up delivery status for an order owned by the signed-in customer.",
  parameters: {
    type: "object",
    properties: { orderId: { type: "string", description: "The order reference" } },
    required: ["orderId"],
  },
  execute: async (args) => {
    if (typeof args.orderId !== "string" || !args.orderId.trim()) {
      return { success: false, error: "Provide an order reference." };
    }
    try {
      const response = await fetch(`/api/support/orders/${encodeURIComponent(args.orderId)}`, {
        credentials: "same-origin",
        signal: AbortSignal.timeout(10_000),
      });
      if (!response.ok) return { success: false, error: "The order could not be retrieved." };
      const order = await response.json();
      return { success: true, data: { status: order.status, deliveryDate: order.deliveryDate } };
    } catch {
      return { success: false, error: "Order lookup is temporarily unavailable." };
    }
  },
};

init({ inboxId: "YOUR_INBOX_ID", tools: [lookupOrder] });
```

Mount once in the application's browser lifecycle. A React application can supply
the same tools in `useMasheev` configuration. Keep definitions stable between renders.

## Backend contract

Implement the route with the application's existing authentication. Look up the
order within the authenticated customer's tenant/account, not globally and then
trust a browser-supplied owner ID. Return only the fields the assistant needs.
Validate provider responses, cap request duration, and avoid logging sensitive payloads.

For write actions, enforce authorization and CSRF protection as appropriate to the
existing app, use a stable operation/idempotency key, and preserve business
confirmation. The SDK's `needsApproval` option can request user approval, but it
does not replace server permission checks.

## Verification

Test a successful lookup, another customer's order, a logged-out request, a provider
timeout, and an invalid argument. For mutations, test confirmation and repeated
requests. Verify the model receives a clear success or failure result and does not
claim an action succeeded when the backend rejected it.

For multi-step browser journeys, see [conversation workflows](https://docs.masheev.com/workflows.md).