Tools
Custom functions
Connect an agent to any API. Define the function with a JSON schema, point it at your HTTPS endpoint, and return a short result the agent can say.
Define a function
In the agent's Functions tab, add a function:
- namestringrequired
- Up to 64 characters. Letters, numbers,
_and-, starting with a letter or_. Unique per agent. - descriptionstring
- Up to 1000 characters. Tell the model exactly what the function does and when to call it.
- parametersJSON schemarequired
- An object schema:
type: "object",properties,required. Every required name must exist in properties. - serverUrlhttps URL
- Your endpoint. Must be
https://. If empty, the agent's Advanced Server URL is used. - asyncboolean
- Default false. When true, the agent doesn't wait for your answer. See Latency and async tools.
An agent can have up to 50 functions. A function can't reuse the name of a built-in tool.
{
"type": "object",
"properties": {
"order_id": { "type": "string", "description": "The order number the caller reads out" },
"zip": { "type": "string", "description": "Delivery ZIP code, 5 digits" }
},
"required": ["order_id"]
}The request your endpoint receives
Katexs sends a POST with Content-Type: application/json:
{
"message": {
"type": "tool-calls",
"toolCallList": [
{
"id": "call_9f2b1c",
"type": "function",
"function": {
"name": "get_order_status",
"arguments": { "order_id": "A-10442", "zip": "78701" }
}
}
],
"call": {
"id": "c1a4e7d0-0000-4000-8000-000000000000",
"customer": { "number": "+15125550123" }
}
}
}The response to return
Return 200 with the result. The recommended shape echoes the tool call id:
{
"results": [
{
"toolCallId": "call_9f2b1c",
"name": "get_order_status",
"result": "Order A-10442 shipped this morning and should arrive Thursday."
}
]
}Katexs also accepts { "result": "..." }, { "message": "..." }, any other JSON (sent to the model as JSON text) or a plain-text body. Results longer than 1000 characters are cut, and only the first 16 KB of your response is read.
Tip
Return a sentence, not a data dump. "Your order shipped this morning and arrives Thursday" lets the agent answer instantly; a 40-field JSON object makes it slower and more likely to read out something odd.
Example endpoint
import { z } from "zod";
const ToolCall = z.object({
id: z.string(),
function: z.object({
name: z.string(),
arguments: z.object({ order_id: z.string(), zip: z.string().optional() }),
}),
});
const Body = z.object({ message: z.object({ toolCallList: z.array(ToolCall).min(1) }) });
export async function POST(req: Request): Promise<Response> {
const parsed = Body.safeParse(await req.json().catch(() => null));
if (!parsed.success) return Response.json({ error: "bad request" }, { status: 400 });
const call = parsed.data.message.toolCallList[0];
const status = await lookupOrder(call.function.arguments.order_id); // keep this under ~500 ms
return Response.json({
results: [{ toolCallId: call.id, name: call.function.name, result: status.sentence }],
});
}Rules your endpoint must follow
- HTTPS only — , publicly reachable. Katexs refuses URLs with credentials in them, local or internal hostnames, private and cloud-metadata IP ranges, and IPv6 literals.
- No redirects. — A 3xx response is treated as a failure.
- Answer fast. — Voice functions have an 800 ms budget end to end. See Latency and async tools.
- Return 2xx on success. — Any other status is a failure and the agent says "That didn't go through on my side. The team will follow up to confirm."
- Validate the arguments. — Katexs checks required fields, types and enums against your schema before calling you, but treat every request as untrusted input.
Securing your endpoint
See Securing your endpoint. In short: use an unguessable path, validate the payload shape, check the call id against your own records when it matters, and never trust arguments for authorization decisions.
Test before you go live
Use Test tool in the Functions tab. It sends exactly the same envelope as a live call, with sample arguments you type, so an endpoint that passes the test behaves the same on a real call.
Last updated November 2026 · Found a problem? Email support@katexs.com
