Custom tools

A tool lets the AI call your API. It's the difference between "contact us about your order" and "your order shipped Tuesday, here's the tracking link".

You define tools in the dashboard: a name, a description, parameters, an HTTP method and a URL.

Naming and describing#

The description is not documentation — it's the instruction the model uses to decide whether to call the tool. It's the highest-leverage field on the form.

Say what it returns and when to use it:

Look up a customer's orders by their verified email address. Use this whenever someone asks about order status, shipping or tracking.

Not:

Orders endpoint.

Tool and parameter names are snake_case: track_order, order_number.

Prefer a few specific tools over one general one. track_order and list_orders each get called correctly far more often than a single orders(action) tool.

Requiring verification#

Each tool has a requires verification setting, and it defaults to on.

When it's on, the tool doesn't exist in the assistant's toolset until the visitor has verified their email. It isn't offered and refused — it's absent, so the AI can't mention it or promise to use it.

Turn it off only for tools that expose nothing personal: store hours, stock levels, shipping rates.

This controls exposure, not enforcement. Your backend still has to scope every response to the verified email. See Visitor verification.

Signed POST tools#

How a tool is called depends on its method, and the difference matters:

POST with a workspace signing secret — sent as a signed event envelope to the tool's URL, with the visitor's verified email injected server-side when a verified session exists. The model can't supply, omit or alter that email. Your handler verifies the signature and can trust the address. This is the right choice for anything touching customer data.

POST without a signing secret, or GET, PUT, PATCH, DELETE — a plain HTTP request with no signed envelope and no injected email. Fine for public, non-personal lookups. Don't use them for anything you'd need to trust.

If a tool returns customer data, make it a POST.

The envelope, the signature header, and how to verify it are documented in The webhook contract.

Parameters#

Give each parameter a description too — the model reads those as well.

Keep the list short. A tool with two clear parameters gets called correctly far more often than one with eight optional ones.

Some parameters have a natural alias: an order number might arrive as order_number or orderNumber depending on how a handler was written. Check what your endpoint expects before renaming anything.

Testing#

Add the tool, then ask the widget the question a customer would ask. If it doesn't fire:

• Confirm the visitor has verified, if the tool requires it.
• Re-read the description as if you were deciding from it alone. Vague descriptions are the usual cause.
• Check the tool's URL is reachable from the internet — not localhost.

Once it fires, check what your endpoint actually returned. The AI can only be as accurate as the payload, and the most common bug is an endpoint returning everything about a customer rather than the one thing the tool was for.