Configure Tools

Tools let a managed agent look things up and take actions mid-conversation: check an order, book a slot, hand over to a person. Everything lives on the agent’s Capabilities page.

Pick the right tool

Section on Capabilities	Use it for	What you build
API Tools	One HTTP request: order status, stock check, create a lead	A REST endpoint
Website Tools	Live answers from a web page	Nothing
Agent Handoffs	Passing the chat to a specialist agent	Another agent
Connector Tools	Every tool from an MCP server	An MCP server
Shopify Stores	Catalogue, policies, customer login and orders	Install the Shopify app
Apps	Tools from an installed Wassist App, which get signed conversation context	An App (alpha)
Support Handoff	Handing over to your team in Gorgias, eDesk or the WhatsApp Business app	Nothing

Not sure whether you need an API tool, a connector or an App? See the comparison.

API tools

An API tool describes one HTTP request. The agent decides when to call it from the Description, fills in the parameters from the conversation, and reads the response.

Add the tool

Open the agent, go to Capabilities → API Tools and click Add Tool.

Name and describe it

The Description is what the model reads to decide when to call the tool, so say when to use it, not just what it does:

Use when the customer asks where their order is. Needs an order number like ACM-12345. If they don’t have it, ask for it first.

Define the request

Set the Method and URL (put path parameters in braces: https://api.acme.com/orders/{order_id}), then add Path Parameters, Query Parameters, Headers and a Request Body as needed.Every parameter is either filled in by the model from a description you write, or a fixed value, like an API key.

Save and test

Click Save Tool, then ask the agent a question that needs it in Test Chat on the agent’s page. Tool calls are recorded on the conversation in the dashboard, so you can see what the agent sent and got back.

The schema

The same tool as JSON (apiSchema in the API, and what the form builds for you):

{
  "url": "https://api.acme.com/orders/{order_id}",
  "method": "GET",
  "path_params": {
    "order_id": {
      "type": "string",
      "input": { "type": "description", "description": "The order number, like ACM-12345" }
    }
  },
  "query_params": {
    "required": [],
    "properties": {
      "phone": { "type": "string", "input": { "type": "value", "value": "%PHONE_NUMBER%" } }
    }
  },
  "request_headers": {
    "Authorization": { "input": { "type": "value", "value": "Bearer sk_live_..." } }
  }
}

For POST, PUT and PATCH, add a request_body:

"request_body": {
  "type": "object",
  "required": ["email"],
  "properties": {
    "email": { "type": "string", "input": { "type": "description", "description": "The customer's email address" } },
    "source": { "type": "string", "input": { "type": "value", "value": "whatsapp" } }
  }
}

Input type	Filled in by	Example
`description`	The model, from the conversation	An order number, a date, a product size
`value`	You, fixed	An API key, a constant flag, a template variable

Template variables can be used inside any value:

Variable	Becomes
`%PHONE_NUMBER%`	The customer’s WhatsApp number
`%IMAGE_URL%`	The image the customer just sent, if the message was an image
`%CALLBACK_URL%`	A URL you can POST to later to send a follow-up into the conversation, which is useful for slow jobs

Every request also carries X-Wassist-Conversation-Id and X-Wassist-Contact-Id headers, so your API knows which chat it’s serving. Your endpoint has 60 seconds to respond. Keep responses small and flat, because the model reads all of them.

Website tools

Capabilities → Website Tools → Add Website Tool. Give it a URL and a prompt that says what to look for (“Current prices and opening hours”). The agent reads the page live when a question needs it.

Agent handoffs

Capabilities → Agent Handoffs → Add Handoff. Pick another agent in your organization and describe when to hand over (“Billing or refund questions”). The conversation continues with that agent.

Connector tools (MCP)

Use any MCP server (Streamable HTTP, no auth or OAuth) as a source of tools:

Go to Integrations → Connectors → New Connector, enter the server URL and finish any OAuth login.
On the agent, open Capabilities → Connector Tools → Add Connector, pick it, and choose which of its tools the agent may use.

Connectors don’t get any Wassist context. If your server needs to know which business or customer is calling, or needs to read the conversation, build an App instead.

Shopify stores

Install the Shopify app, then add the store under Capabilities → Shopify Stores → Add Store. The agent gets tools named after the store: product search, best sellers, policies and FAQs, and a customer login that unlocks order status and history.

Apps (alpha)

Installed Apps appear under Capabilities → Apps, with a switch for each tool. You choose agents and tools while installing, and can change them here later. App tools reach the model with the app’s slug as a prefix (acme_loyalty__get_points), so they never clash.

Support handoff

Connect Gorgias, eDesk or the WhatsApp Business app under Capabilities → Support Handoff. When a customer needs a person, the agent opens a ticket or hands the chat over with the full thread, and steps back until your team hands it back.

Manage tools from code

API tools, website tools, handoffs and connectors are all fields on the agent. Each array you send replaces that list: entries with an id are updated, entries without one are created, and existing entries you leave out are deleted. To add one tool, fetch the agent and send its current tools plus the new one.

import { Wassist } from "@wassist/sdk";

const wassist = new Wassist({ apiKey: process.env.WASSIST_API_KEY });
const agent = await wassist.agents.get(agentId);

await wassist.agents.update(agentId, {
  tools: [
    ...agent.tools, // keep the existing tools
    {
      name: "check_order_status",
      description: "Use when the customer asks where their order is. Needs an order number like ACM-12345.",
      apiSchema: {
        url: "https://api.acme.com/orders/{order_id}",
        method: "GET",
        path_params: {
          order_id: { type: "string", input: { type: "description", description: "The order number" } },
        },
        request_headers: {
          Authorization: { input: { type: "value", value: `Bearer ${process.env.ACME_KEY}` } },
        },
      },
    },
  ],
  websiteTools: [
    ...agent.websiteTools,
    { url: "https://acme.com/shipping", prompt: "Shipping times and costs by country" },
  ],
});

Tips

Write descriptions for the model

Say when to call the tool, which inputs it needs, and what to do if the customer hasn’t given them yet. Vague descriptions are the most common reason a tool never gets called.

Return errors the agent can explain

Return {"error": "No order ACM-99999 for this phone number"} rather than a stack trace. The agent passes the message on in its own words.

Don't trust the model with authorization

Put secrets in fixed value inputs, never in descriptions. Check that the order belongs to %PHONE_NUMBER% (or the X-Wassist-Contact-Id) on your side, rather than relying on the prompt.

Start Here

Shopify

Managed Agents

Webhooks

Apps (Alpha)

WhatsApp Numbers

Platforms

Developer Tools

Pick the right tool

API tools

The schema

Website tools

Agent handoffs

Connector tools (MCP)

Shopify stores

Apps (alpha)

Support handoff

Manage tools from code

Tips

What’s next

Build an App

Examples

​Pick the right tool

​API tools

​The schema

​Website tools

​Agent handoffs

​Connector tools (MCP)

​Shopify stores

​Apps (alpha)

​Support handoff

​Manage tools from code

​Tips

​What’s next

Build an App

Examples

Pick the right tool

API tools

The schema

Website tools

Agent handoffs

Connector tools (MCP)

Shopify stores

Apps (alpha)

Support handoff

Manage tools from code

Tips

What’s next