Custom Agent Tools

Give the AI live access to your systems: define tools the LLM can call during reply generation to fetch order status, look up accounts, check inventory, and more.

Quick facts#

For the conceptual overview, see the Agent tools guide. This page is the technical reference.

Tool anatomy#

A tool definition has these fields:

Worked example — get_order_status (SERVER_SIDE)#

Tool definition

Parameters schema (JSON Schema)

{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "The customer's order number, e.g. ORD-10432"
    }
  },
  "required": ["order_number"]
}

Request your endpoint receives

On a tool call, HelpStack sends the LLM-provided arguments as the request body (for POST/PUT/PATCH), with your configured headers plus Content-Type: application/json:

POST /orders/status HTTP/1.1
Host: api.YOURCOMPANY.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{ "order_number": "ORD-10432" }

Response contract your endpoint must honor

Return JSON the model can read. Keep it small — responses are capped at ~10 KB and the call times out at ~10s.

{
  "status": "shipped",
  "carrier": "DHL",
  "tracking_number": "JD0140...",
  "estimated_delivery": "2026-06-02"
}

The AI receives this payload as the tool result and weaves it into its reply. There is no required envelope — return whatever fields are useful, but make them self-describing so the model uses them correctly.

Writing good descriptions#

The description is the single most important field — it is the only thing the LLM uses to decide whether and when to call the tool.

• State what the tool returns and when to call it ("Call this when the customer asks ...").
• Mention the trigger phrases customers actually use.
• Describe each parameter clearly in its schema description.
• Keep under the ~2000 char limit (the save dialog validates and surfaces errors).

Security & SSRF protection#

• HTTPS only. Plain HTTP URLs are rejected.
• SSRF blocklist. Internal/private network targets (loopback, private RFC1918 ranges, link-local, metadata endpoints) are blocked so a tool cannot be pointed at internal infrastructure.
• Secret headers. Put API keys/tokens in Headers, which can be encrypted/masked rather than stored in plaintext.
• Treat the tool endpoint as internet-facing — authenticate requests (e.g. a bearer token in Headers) and validate input on your side.

Timeouts & caps#

Failures degrade gracefully — a broken or slow tool never blocks a reply; the AI simply proceeds without that data.

Org vs. channel tools + semantic filtering#

• Tools can be defined at the organization level and at the channel level.
• For a given conversation, org-level and channel-level tools are merged, and a channel tool overrides an org tool with the same name.
• The merged set is semantically filtered by relevance to the customer's query, so a large catalog of tools doesn't bloat every LLM call — only relevant tools are offered.
• Selected tools are converted to OpenAI/Anthropic function definitions and offered during reply generation.

OpenAPI import#

You can bootstrap tools from an existing API: paste or upload an OpenAPI 3.0 spec, and HelpStack extracts its operations into tool definitions you review and save. This is the fastest way to expose an existing REST API to the AI.

Logging#

Every tool call is recorded in ToolCallLog. View a tool's call history (arguments, outcome, timing) via:

GET /api/agent-tools/[id]/logs

Use the logs to debug why a tool was or wasn't called, and to spot timeouts/errors.

Client-side tools (advanced)#

CLIENT_SIDE tools are declared the same way (name, description, parameters schema) but execute in the website visitor's browser, mediated by the widget socket:

1. The AI emits a tool call for a CLIENT_SIDE tool.
2. The server emits tool:execute to the widget.
3. The widget runs it and replies with tool:result (or tool:error).
4. There is a ~5s timeout; on timeout the call degrades gracefully (tool unavailable).

There is no public JS API to register client-side tool handlers in the widget loader today. Client-side execution is server/iframe-mediated — treat it as an advanced capability and do not expect a registerTool()-style snippet on your page. See Widget Embed.

Related#

• Agent tools guide
• API Reference
• Widget Embed
• Glossary