API tools

Retrieval answers what you published. Tools answer what is true right now.

Describe an endpoint in one sentence and CustomerBot writes the tool schema. The assistant then decides, mid-conversation, when to call it — and answers from the response.

What you write

“Look up an order by its number and return the status and tracking link.”

One sentence, no schema

What gets generated

{
  "name": "get_order_status",
  "description": "Look up an order by its number and
                  return status and tracking",
  "method": "GET",
  "endpoint": "https://api.example.com/orders/{order_number}",
  "headers": {
    "Authorization": "Bearer ••••••••••••"
  },
  "parameters": {
    "order_number": {
      "type": "string",
      "description": "The customer's order number",
      "required": true
    }
  }
}

Build a tool Plans with API access

Which questions need a tool at all

Most do not. Tools are for facts that change per person or per minute; everything else belongs in the knowledge base, where it is cheaper and easier to audit.

Question	Answered by	Because
“What is your returns window?”	Knowledge base	A published fact. It does not change per customer and it is on a page you wrote.
“Where is order #48120?”	API tool	True only right now, and only for this person. No page can hold it.
“Do you have the blue one in medium?”	API tool	Stock moves faster than a crawl. Read it live or do not claim it.
“How do I cancel my subscription?”	Knowledge base	A procedure. Publishing it once is the right answer.

From a sentence to a working call

Describe it in a sentence

Write what the endpoint does in plain English — “look up an order by its number and return the status and tracking link”. That is the whole input.

The schema is generated

CustomerBot produces a tool definition: a name, a description the model reads to decide when to call it, and typed parameters with their own descriptions.

You supply the wiring

URL, method (GET, POST or PUT), any headers such as an Authorization bearer token, and a body template for writes. Placeholders in the URL and body are filled from the parameters at call time.

The model decides when to use it

During a conversation, the model picks tools by their descriptions. It can chain several calls — up to four rounds — before it answers, so a compound question becomes one reply.

Four things that decide whether a tool works well

Tool calling fails for boring reasons far more often than exotic ones. These four account for most of it.

Write the description for the model, not for yourself

The tool description is the only thing the model has when deciding whether this is the right call. “Get order” is ambiguous. “Look up a customer order by its order number and return delivery status and tracking link” is not.

Name the parameters the way a customer would

A parameter described as “order_number: the customer’s order number, e.g. 48120” gets filled correctly far more often than one described as “id”.

Return small, readable JSON

The response goes into the model’s context. An endpoint that returns forty fields when the answer needs three makes replies slower, more expensive and vaguer. Build a purpose-shaped endpoint if you can.

Fail informatively

An endpoint that returns a clear “order not found” lets the assistant say so. One that returns an opaque 500 leaves it guessing, and guessing is the behaviour you are trying to eliminate.

Scope it as if a stranger were holding the wheel

Because one is. A visitor's message is what causes the call, so treat every connected endpoint as reachable by the public even though the credential stays on our side.

Expose the narrowest endpoint that answers the question, not a general-purpose data API
Never wire up an endpoint that returns more personal data than the answer requires
Treat anything the assistant can call as publicly reachable in effect — a visitor is driving it
Prefer reads. Use POST and PUT only where a write is genuinely the point, and scope it tightly
Rotate the token you put in the header like any other credential

Tool questions

What is an API tool, in one sentence?

A description of one of your endpoints that the model can choose to call mid-conversation, so it can answer from live data instead of only from your published content.

Do I need to write JSON schemas by hand?

No. You describe the endpoint in plain English and the schema is generated for you. You then fill in the URL, method, headers and any body template — the parts only you know.

Which HTTP methods are supported?

GET, POST and PUT. GET parameters are sent as query parameters; POST and PUT use a body template where placeholders are substituted from the parameters the model supplies.

How many tools can one assistant have?

Several. The practical constraint is that too many similar tools makes the model’s choice harder — a handful of well-described, clearly distinct tools works far better than fifteen overlapping ones.

Can it call more than one tool for a single question?

Yes. The assistant runs up to four tool rounds before it answers, so “where is my order and can I still change the address” can be resolved in one reply.

What happens if my endpoint is down?

Calls time out rather than hanging the conversation, and the assistant tells the visitor it cannot check right now rather than inventing a status. This is the correct behaviour and it is worth testing deliberately before you go live.

Is API access on every plan?

API access is included on the paid plans. The free plan is for training and testing against your published content.

Worked examples:Order lookups for stores Viewing slots for agents Availability for hotels

Give it one endpoint and see what changes.

Start with a read-only lookup. It is the smallest possible tool and it removes the largest single category of tickets.

Start free