Katexs
Custom functions

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.

parameters
{
  "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:

POST https://api.example.com/katexs/order-status
{
  "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:

200 OK
{
  "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

order-status.ts (any Node runtime)
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