Tools guide

A brief tells a worker what the conversation is for. Tools are what let it act inside that conversation — look a customer up, book the slot, move the screen the visitor is looking at. Without them a worker can only describe. With them it can do the next thing and then talk about what it did.

Tools are registered per worker in the console at app.delegateworker.com. Open the worker, go to Tools, and add one under the Custom category. Two kinds are available, and the choice is simply where the work happens.

Two kinds of tool

Webhook tools

A webhook tool points at an endpoint you own. When the worker calls it, our side makes the request, waits for your response, and hands the response back into the conversation. Nothing about it touches the visitor browser, so it works the same whether you shipped the embed widget or built your own interface.

You configure four things:

• Endpoint. The URL to call. It must be reachable from the public internet and served over HTTPS.
• Auth header. An optional header sent with every call — a bearer token, an API key, whatever your endpoint expects. It is stored encrypted and is never returned to the browser or shown again after you save it.
• Method. GET or POST.
• Body fields. For POST, the body-field builder maps the tool parameters into the JSON body your endpoint wants, so you do not have to reshape anything on your side. For GET, parameters go on the query string.

Write the endpoint to be fast and to answer in plain language. The worker is holding a live conversation while it waits, and it speaks from your response — so {"answer":"three seats left on the Tuesday session"} reads better out loud than a full record dump. Return an error status and the worker is told the tool failed; it will say so rather than guess.

Tools that run in your page

A tool that runs in your page has no endpoint. In the console you give it a name and its parameters and nothing else; the work happens in your frontend, in a handler you pass to clientTools when you start the session. The name in the console and the key in clientTools must match exactly.

clientTools: {
  update_dashboard: async (params) => {
    // params holds exactly the parameters you declared in the console.
    const view = typeof params?.view === 'string' ? params.view.trim() : '';
    if (!view) return 'no view was named';
    if (!showPanel(view)) return 'there is no panel called ' + view;

    // Short, factual, and true of the page right now.
    return 'the ' + view + ' panel is now on screen';
  },
}

The handler return value is the tool result — the worker speaks from it. Return nothing and the SDK answers ok, which is the right result for a tool that only changes the page. Throw, and the error message goes back as a failed result. A tool with no matching handler is answered unhandled automatically, so a tool you have registered but not yet built cannot stall a session. The full contract is in the headless SDK quickstart.

One tool that runs in your page, per worker, today. One handler is enough for most interfaces if you make its parameters do the work — a single update_dashboard with a view parameter covers what five one-purpose tools would. Support for more than one is on the roadmap.

Writing a good one

• Name it as an action: update_dashboard, open_record, fill_form. The worker chooses tools by name and description.
• Keep parameters few and flat, and describe each one in the console. That description is how the worker knows what to put in it.
• Validate everything. Parameters arrive from a live conversation, so treat a missing or unexpected value as a normal case and answer it in words rather than throwing.
• Return quickly. The conversation is waiting. If the real work is slow, change the screen, return, and let the worker cover the wait.
• Say what is true of the page now. The worker will describe the screen from your string, so it should match what the visitor can actually see.

Interactive onboarding: act, then react

The pattern that makes a guided walkthrough feel alive is small and easy to miss: call the tool first, then talk about what the visitor now sees.

Left to itself, a worker will narrate before it acts — “sure, let me bring up your billing page for you” — and the visitor spends a second staring at the old screen while the words arrive first. Reversed, the panel changes as the request lands and the worker picks up from there: “that is your billing view — the plan is on the left, and your next invoice date is under it.” The same tool call, the same sentence, in the order that matches what the visitor is looking at.

This is a prompt instruction, not a setting. Put it in the worker brief, in plain language:

You are walking a new customer through their dashboard.

When the customer asks to see part of the product, call update_dashboard
first, with the view they asked for. Wait for the result. Then describe
what is now on their screen, in one or two sentences.

Never describe a screen before you have called the tool. Never say you
are about to do something — do it, then talk about what they can see.
If the tool answers that the view does not exist, say so plainly and
offer the views that do.

Three things make it hold. Tell the worker to call the tool before it speaks, in those words. Tell it to describe the result rather than announce the intention. And return a string from your handler that is true of the page right now, so the sentence the worker builds from it is accurate. If your handler returns nothing, the worker has only the brief to go on and will describe the screen from memory.

The same pattern carries the failure case. When the handler answers that a view does not exist, the worker should say so and offer what does exist — not apologise at length, and not pretend the screen changed.

Choosing between them

Ask where the result belongs. If it belongs in your database, your calendar, or your CRM, it is a webhook tool. If it belongs on the screen in front of the visitor, it runs in your page. A guided onboarding usually needs both: a webhook tool to fetch the account, and the page tool to show it.

And keep the line clear about what a tool should not do. Booking a slot, opening a record, moving a panel — fine. Handing back a decision that should belong to a person is not a tool call; it is a handoff, and it deserves its own tool that puts a human in the loop.

Next

• Headless SDK quickstart — a complete page with update_dashboard wired up.
• Session lifecycle and events — what happens around the tool calls.
• Integration overview — widget or SDK.