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 two types, 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.

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 two types of tool#

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. This is advanced — reach for it only when the action genuinely needs to happen in the visitor's browser context.

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.

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.

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