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.
API tools
AI agent 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 schemaWhat 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
}
}
}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
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.
01
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.
02
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”.
03
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.
04
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.
Four rules that keep tool calling reliable
The most common mistake is exposing everything. Selection accuracy falls as the list of tools grows — this is a property of how models choose, not something a product can configure away, so it is worth designing around from the start.
Fewer tools, more reliable choices
Selection accuracy falls as the list grows. Developers building this by hand report models getting confused well before they reach a few dozen tools. Start with two or three that cover your highest-volume questions and add only when a real gap shows up in the transcripts.
Group endpoints rather than exposing them all
Sixty endpoints does not mean sixty tools. Wrap the related ones into a handful that take a parameter, so the assistant makes one clear decision instead of picking from a wall of near-identical options.
Write the description for the model, not the docs
The description is how the assistant decides whether a tool applies. “Look up the status of a customer order by order number” beats “order service endpoint” every time, because it says when to reach for it.
Return less than the endpoint offers
A response with forty fields gives the model forty chances to quote the wrong one. Trim to what an answer actually needs.
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 tool calling, and how does it work here?
Tool calling is the ability of a model to reach outside its own knowledge and invoke something you have defined — an API, a lookup, an action — then use the result to answer. Here you describe the endpoint in plain English, the tool definition is generated for you, and the assistant decides during the conversation whether that tool applies. Retrieval answers what you published; tools answer what is true at the moment somebody asks.
How many tools can I add before it gets confused?
Fewer than you would expect, and this is a property of the technique rather than of any one product. Selection accuracy degrades as the list grows — people building tool-calling agents by hand hit this well before a few dozen tools. The fix is grouping: wrap related endpoints into a handful of parameterised tools rather than exposing each one, and write descriptions that say when to use the tool rather than what it is named.
Should I just build this myself with LangChain or the model APIs?
If tool orchestration is the interesting part of your problem, yes — build it, you will learn more and control everything. Buy it when the chat assistant is a supporting feature rather than your product, and you would rather not own a widget, a retrieval pipeline, transcript storage, model routing and the tool layer all at once. Neither answer is wrong; they suit different weeks.
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.
Keep reading
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