Tools: the agent calls your HTTP endpoints

Everything the agent does beyond talking goes through tools: reading a calendar, booking, checking an order, opening a ticket. A tool is a GET or POST endpoint on your side, described for the model with a JSON schema. The model decides when to call it and with which arguments; the platform performs the request.

Defining a tool

A tool has a name, a description written for the model, a JSON schema of its arguments, and the runtime part: URL, method, headers and an optional body template. Write {{name}} placeholders in the URL, in header values or in the body; each placeholder must be declared in the schema with a description. The model fills it from the conversation and the runtime substitutes it, URL-encoded in the URL and escaped in a JSON body.

{
  "name": "book_appointment",
  "description": "Books an appointment. Call it only after the caller confirmed day, time and name.",
  "method": "POST",
  "url": "https://api.example.ch/clinics/{{clinic}}/appointments",
  "headers": { "Authorization": "Bearer sk_…" },
  "body": "{ \"start\": \"{{start}}\", \"name\": \"{{name}}\", \"phone\": \"{{phone}}\" }",
  "schema": { "type": "object", "properties": {
    "clinic": { "type": "string", "description": "Clinic code: always 'zurich'" },
    "start":  { "type": "string", "description": "Start, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Caller's first and last name" },
    "phone":  { "type": "string", "description": "Caller's phone number, digits only" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

What your endpoint receives and must answer

Every request carries a token header with the agent's tool token: check it first. Answer 200 with a JSON body. On success, { "success": true, "message": "…" } plus any data: the message is meant to be relayed to the caller. On a business error, { "success": false, "error": "…" } with the error written as a sentence for the model, for example what to propose instead. On 401 or 500 the agent apologises and offers a callback. Keep responses under a few seconds: the caller is waiting on the line.

app.post('/clinics/:clinic/appointments', express.json(), async (req, res) => {
  if (req.get('token') !== process.env.SWISSAI_TOOL_TOKEN) return res.status(401).end();
  const { start, name, phone } = req.body;
  if (!(await isFree(req.params.clinic, start)))
    return res.json({ success: false, error: 'That time is taken. Offer 11:00 or 14:30 on the same day.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Appointment booked for ' + start + '.' });
});

One list of tools, shared by agents

Tools live in the Tools section of the dashboard and agents use them by reference: edit a tool once and every agent that uses it is updated. A tool assigned to a customer can be used only by that customer's agents. Before saving, the dashboard checks the definition with Claude and builds the schema from the placeholders.

Try without hosting anything

The sandbox is a live set of example endpoints with separate sample data for each account: calendar, restaurant tables, stock, callbacks, contacts, orders. Its 22 tools are already in the Tools section; each one has a guide with the parameters, a worked example of request and response, and the code of the endpoint, which you can download and use as a base.

Related pages

• Appointment booking over the phone, handled by an AI agent
• A SIP URI for every voice agent
• A call button on your website, answered by the agent