HelpStackDocs

Guides

Agent tools (overview)

Agent tools give your AI custom abilities. Instead of only answering from text it knows, the AI can call your systems while drafting a reply — for example to "look up order status" or "check a delivery date" — and weave the result into its answer. This guide is the conceptual, task-oriented overview: what tools are, the four types you create, how to create one, how to write a description the AI actually uses well, importing from OpenAPI, and assigning tools to channels. For endpoint, security, and JSON Schema specifics, see the integrator guide linked throughout.

You'll find tools at Settings → Agent Tools (route /settings/agent-tools). Managing agent tools requires the OWNER or ADMIN role; agents and viewers can generally read them.

Custom agent tools need the Growth plan or higher. On Free and Starter, creating a tool or assigning one to a channel is refused with "Custom agent tools are available on the Growth plan and up." The Shopify and WooCommerce tools that appear automatically when you connect a store are not affected by this: those come with the integration on any plan.

The built-in store tools check who is asking. The order and tracking tools that arrive with a Shopify or WooCommerce connection need the order number and the email the order was placed with, and give nothing back unless the two match. A tool you build yourself gets no such check for free — if it returns one customer's data on an identifier another customer could guess, the AI will hand it over. See Getting started with Shopify for how the built-in ones behave.

What an agent tool is#

A tool is a custom ability you give the AI. When a customer's message calls for live or account-specific information — say, the status of their order — the AI can call the tool, get back real data, and use it to write an accurate reply. This turns the AI from something that only knows your documentation into something that can act on your behalf within the boundaries you define.

The four types of tool you create#

HelpStack has seven tool types in total. Four are the ones you build, described below. The other three arrive on their own and are not created from this screen: Shopify and WooCommerce tools appear when you connect a store, and Control tools are built in and ship with HelpStack. You cannot create or delete those three, but you can add a note to them so the AI knows how your business handles them.

Server-side (SERVER_SIDE)

HelpStack calls an HTTP endpoint you provide. You define:

  • Name
  • Description (see Writing a great description — this is the most important field)
  • URL of your endpoint
  • HTTP method
  • Optional headers
  • A Parameters JSON Schema describing the inputs the AI must supply

This is the common case: HelpStack reaches out to your backend, which returns the data.

Client-side (CLIENT_SIDE)

The tool runs in the website visitor's browser rather than on your server. Reach for it when the action genuinely belongs in the visitor's browser: pointing at a button in your own UI, reading which screen they are on, opening a panel for them.

Your page provides the handler. Register it by name with the widget script:

window.HelpStack('registerTool', 'highlight', async ({ section }) => {
  document.querySelector(`#${section}`)?.scrollIntoView({ behavior: 'smooth' });
  return { highlighted: section };
});

Whatever the handler returns is what the AI reads. See Custom Agent Tools for the queue shim that lets you register before the script loads, and for the underlying postMessage contract if you would rather answer it yourself.

Email inquiry (EMAIL_INQUIRY)

Server-side and client-side tools answer inside the same reply. An email inquiry does not. Some questions cannot be answered from your own systems at all: a parcel is late and only the carrier knows where it is, a part is delayed and only the supplier can say when it ships. This type lets the AI ask them, and picks the conversation back up when the answer arrives.

What happens in practice:

  1. A customer asks something the AI cannot answer on its own.
  2. The AI writes the email itself, in its own words, and sends it to the address you named from one of your connected mailboxes. There is no template.
  3. It tells the customer you are checking, using the wording you configured.
  4. The conversation moves to the Waiting on Reply status (WAITING). It is not "needs a human", so it stays out of your team's action queue, and the time spent waiting is subtracted from your resolution-time analytics.
  5. When the counterparty replies, HelpStack matches the reply back to the question it belongs to, and the AI writes to the customer with what it learned. The conversation goes back to Open with an unread mark.

While it waits, the AI keeps answering the customer normally. If they chase, it says it is still waiting rather than emailing the carrier a second time.

Email inquiry tools are off by default for every organization. They need the Growth plan like any other custom tool, and HelpStack has to switch the feature on for you. This is deliberate: no other tool sends real mail from your own domain on the AI's initiative, and that should not arrive with a plan upgrade nobody discussed.

What you configure

Alongside the usual name, description and Parameters JSON Schema:

  • Who the AI emails. The address the question goes to, for example a carrier's support inbox.
  • Send from. One of your active email channels. The same mailbox sends the question and receives the reply, so it has to be a mailbox HelpStack polls.
  • How long to wait. Between 1 and 720 hours.
  • If nobody replies in time. Send a reminder, hand the conversation to a human, or tell the customer there is still no answer.
  • What the AI tells the customer while it waits. A short instruction, not a script. Keep it short and do not promise a time.
  • How the question is sent. "Send it automatically" is the only option that works today. "Draft it for approval" is shown next to it, deliberately disabled: the approval queue it would need is not built yet, so a tool set that way would refuse every call after the AI had already told the customer it was checking. It is shown rather than hidden so you are not hunting for a control that seems to be missing.

The tool's description is where your rules for that counterparty belong. "Reference the order number only, never the customer's email or phone" is the kind of line the AI reads before it writes.

Give the tool a field for the order or tracking number

This one matters more than it looks.

Before an inquiry leaves your mailbox, HelpStack strips things that look sensitive out of the subject and the body: long runs of digits, labelled secrets such as a password or card number, email addresses. Anything the AI put into a named parameter of your tool, trackingNumber or orderId, is passed through untouched. Anything it typed into the free text is not.

So a tool whose parameters are only subject and body cannot ask about a parcel. The tracking number goes out redacted and the carrier has nothing to work with. The same shape breaks a second thing: HelpStack recognises a repeat question by comparing the named parameters, so with none to compare, the next genuinely different question on that conversation is refused as a duplicate of the first.

The tool form warns you about this under the parameters editor, and the warning clears as soon as the schema has a field of its own for the identifier. The by-hand dialog shows the same warning for the same reason.

The filter is a safety net, not a guarantee. It catches obvious mistakes. It is not a data-loss-prevention system and does not claim to find everything. Keep the tool's description explicit about what the AI may and may not mention, and choose counterparties you would already trust with the question.

What you see on the conversation

Under the customer's thread, each question the AI sent out gets a card. Expand one and you see the question as it actually went out (with a note when something was removed on the way), and every message exchanged with the counterparty since. That side thread does not appear anywhere else in your inbox, so this card is the only place to read it.

A card is in one of these states: Waiting for a reply, Answered, Needs your read, No reply in time, Cancelled, or Could not be sent.

Needs your read means a reply came back and HelpStack could not tell whether it answered the question. The conversation is handed to a human and the card offers three choices, right next to the exchange they are about:

  • This is the answer. Settles the question with that reply and lets the AI write to the customer. The conversation leaves your queue.
  • Not the answer, keep waiting. Leaves the question open so a later, clearer message can still settle it, and puts the conversation back to Waiting.
  • Close the loop. Gives up on the question. The customer is told nothing and the conversation stays with you.

If two questions are open on the same conversation at once, both cards show the flag. The flag belongs to the conversation rather than to one question, so it cannot say which reply triggered it. That is exactly why the card renders the exchange: read each one and you can see which counterparty actually wrote back.

You can also ask a counterparty yourself. Open the conversation's ⋮ menu and choose Ask a counterparty, pick the tool, fill in its fields and edit the subject and body. It goes out through the same path the AI uses, with the same limits. There is no matching shortcut for deciding a reply: those three buttons stay inside the card, so nobody accepts an answer they have not read.

What the AI does with the reply

When the reply is judged to be an answer, its text is given to the AI as context for the message it writes to your customer. The AI is told to answer in your voice and not to mention tools or internal process, and the usual reply rules apply, but the counterparty is writing into a prompt. If that matters for a particular mailbox, leave approval on for the channel so a person reads the draft before it goes out.

Async job (CALLBACK_JOB)

An async job is the email inquiry's sibling, for work rather than questions, and for a machine rather than a person. The AI hands a job to one of your own systems, the conversation waits, and it picks back up when that system reports the job finished.

Use it when the work genuinely takes longer than a reply can wait: a rebuild, a bulk update, a render, anything queued behind your own workers. If your system can answer while the request is open, use a server-side tool instead — you get a simpler setup and the answer arrives in the same reply.

Where it differs from an email inquiry:

Email inquiryAsync job
Who is askedA personOne of your systems
Typically waitsHours or daysSeconds to an hour
Is the reply an answer?The AI judges itYour system says so outright
If nobody repliesIt can send a reminderNo reminders; the deadline decides

Setting one up needs an engineer on your side: your system has to accept the job and call HelpStack back when it is done. The contract is written up in Async tools (callback).

Availability. Async jobs are behind a feature flag. Ask us to switch it on for your organization; after that you create and edit the tool yourself in Settings → Agent Tools, the same as an email inquiry.

Creating and managing tools#

From Settings → Agent Tools you can:

  • Create a tool (pick its type, then fill in its fields).
  • Edit an existing tool.
  • Delete a tool.
  • Toggle a tool Active / inactive without deleting it.

Tool calls are logged, so you can review what the AI invoked.

Adding a note to a built-in tool

Shopify, WooCommerce and Control tools cannot be edited or deleted — they are maintained by us, and an update to how they work reaches you automatically. That would normally leave you no way to tell the AI something specific about your business, so those tools take a note instead.

The note is added to the tool's description rather than replacing it, which is what lets both things be true at once: we keep improving the wording, and your instruction survives every update. Use it for the things only you know:

Orders placed after 14:00 ship the next working day.

We do not ship to PO boxes. Ask for a street address before promising delivery.

Leave the note empty to remove it. Everything else about the tool stays ours.

Writing a great description#

The description is critical — it's what the AI reads to decide when to call the tool. Write it like instructions to a new teammate who has never seen your systems:

  • Say when to use it and what it's for.
  • Say what information is required to call it.

A good example:

"Use this when the customer asks about the status of an existing order. Requires their order number."

Here ORDER_NUMBER would be one of the parameters defined in the tool's Parameters JSON Schema. A vague description leads the AI to call the tool at the wrong time or skip it entirely; a clear one makes it reliable.

Import from OpenAPI#

If your systems already have an OpenAPI specification, you don't have to define tools one by one. Use "Import from OpenAPI" and provide your spec — HelpStack generates tools from it. This is the fastest way to expose an existing API to the AI.

Org-wide vs. per-channel tools#

  • Tools can be defined organization-wide so they're available everywhere.
  • Tools can also be assigned or overridden per channel in Settings → Channels → channel → Tools.

This means you can keep a shared set of tools and still tailor which tools a particular channel can use — for example, exposing an order-lookup tool only on your support channel.

Email inquiry tools are organization-wide only. You create and edit them under Settings → Agent Tools, never inside a channel's Tools tab; a channel-scoped one would not be listed anywhere you could edit or switch it off. They still reach every channel, and the mailbox they send from is part of the tool itself.

Where to go deeper#

This guide stays conceptual on purpose. For the technical details — endpoint contracts, authentication and security, headers, and how to write the Parameters JSON Schema — see the integrator guide:

Related#

Edit this page on GitHub