Tools during calls

#Allerto's own tools

Two ready-made tools, switched on in the agent with systemTools. Each does one thing and returns what it found; what the agent does with it is up to its instructions (for example "if the person called before about the same problem, say you are flagging it as a reminder"). Nothing is on unless you switch it on.

"systemTools": {
  "notes": true,
  "history": { "match": "caller" }
}

The agent only ever gets dates, never what earlier calls were about: caller ID can be spoofed and anyone can say a name. Only calls of the same client where someone spoke are counted, and site web calls (where the visitor types the number) have no history. System tool calls are logged in tool_calls and do not count towards the limit of 15 calls to your tools.

#Data before the call

Before the agent speaks, Allerto can ask your own system what it knows about the call: who is calling, an open case, a balance. Set precall.url (https) on the agent:

"precall": { "url": "https://crm.example.com/allerto/call" }

When the call starts, Allerto sends a POST signed like webhooks (x-allerto-signature over timestamp.body, with your account's signing secret, which publishing requires):

{
  "event": "call.starting",
  "call": {
    "id": "…",
    "direction": "inbound",
    "from": "+393331234567",
    "livemode": true,
    "agent": { "id": "…", "version": 3 },
    "client": { "id": "…", "external_id": "studio-42" }
  }
}

Answer within 2.5 seconds with {"variables": {"name": "Mario Rossi", "open_case": "Leak in the garage"}}: up to 20 keys (letters, digits, _), values of text, numbers or yes/no, cut to 200 characters on one line. They reach the agent's prompt as data, never as instructions; what to do with them goes in the agent's instructions ("greet the person by name; if there is an open case, ask whether they are calling about it"). If your endpoint is slow, fails or answers something else, the call starts without them. Every request is logged in the call's tool_calls as dati_prima_della_chiamata, with its status and duration.

The same keys fill the agent's placeholders: write {{name}} in the greeting or the instructions ("Good morning {{name}}, this is Giulia"). Keys are read in lowercase. When a value is missing the placeholder disappears with no gap left ("Good morning, this is Giulia"), so write sentences that still read well without it. Every inbound agent also has {{numero_chiamante}} (the caller's number, empty when hidden), {{data_oggi}} (today, in words) and {{ora}} (the time in Italy). Any other placeholder needs precall: without it the agent is refused with Unknown variable, so a typo never goes silent.

#Your functions

The simplest way to let the agent read or update your system during the call: describe a function and the https address that runs it. When the agent needs it, Allerto sends the data to your address and the agent reads back your answer. No MCP server to run: one endpoint per function is enough.

"functions": [
  {
    "name": "cerca_pratica",
    "description": "Looks up an open case by address. Use it when the caller reports a fault.",
    "parameters": [
      { "name": "indirizzo", "type": "string", "description": "Street and number", "required": true }
    ],
    "url": "https://crm.example.com/allerto/cerca-pratica"
  },
  {
    "name": "apri_pratica",
    "description": "Opens a case for a fault.",
    "parameters": [
      { "name": "indirizzo", "required": true },
      { "name": "descrizione", "required": true },
      { "name": "urgente", "type": "boolean" }
    ],
    "url": "https://crm.example.com/allerto/apri-pratica",
    "action": true
  }
]

Up to 10 functions per agent, on both voice models, next to the tools of an MCP server (a function wins over a tool with the same name). Publishing an agent with functions requires your account's signing secret.

When the agent calls a function, Allerto sends a POST signed like webhooks (x-allerto-signature over timestamp.body):

{
  "event": "function.call",
  "function": "cerca_pratica",
  "arguments": { "indirizzo": "Via Garibaldi 12" },
  "call": {
    "id": "…",
    "direction": "inbound",
    "from": "+393331234567",
    "livemode": true,
    "agent": { "id": "…", "version": 3 },
    "client": { "id": "…", "external_id": "studio-42" }
  }
}

Answer with a 2xx and {"result": "Case 4071, opened on 28 October, plumber assigned"}: the agent reads result. Any other body is read as it is, so plain text or your own JSON work too. A 4xx/5xx tells the agent your system answered with an error, together with your body. An executed action also carries the header idempotency-key, the same for a repeated request, so you can refuse duplicates.

Reads and actions, time limits and the 15 calls per call work as for MCP tools, below. Every call is logged in the call's tool_calls with its arguments, result and duration.

#Your MCP server

An agent can use the tools of your own MCP server while it is on the phone: check availability, look up a case, book an appointment. Allerto knows nothing about your domain; it connects to the server you name, offers its tools to the voice model and applies the same safety rules to every customer.

Tools work with both voice models. gemini-3.8-live calls them itself and keeps talking while they run. gpt-live-1 hands the request to an Allerto back office (a text model) that reads the conversation, calls your tools with the same rules and confirmations, and tells the agent what to say; its tokens are reported separately as usage.delegation_usage.

{
  "type": "inbound",
  "name": "Reception",
  "persona": "Giulia",
  "model": "gemini-3.8-live",
  "voice": "Erinome",
  "greeting": "Buongiorno, sono Giulia dello Studio Rossi. Come posso aiutarla?",
  "instructions": "Help the caller find and book a cleaning appointment.",
  "result": [{ "key": "name", "label": "Name", "type": "text" }],
  "mcp": {
    "url": "https://agenda.example.com/mcp",
    "tools": ["availability", "book"]
  }
}

Store the bearer token Allerto sends as Authorization: Bearer … separately. It is encrypted and never returned (the agent shows mcp_token_set):

curl -X PUT https://api.allerto.cloud/v1/agents/$AGENT/mcp-token \
  -H "Authorization: Bearer $ALLERTO_API_KEY" -H "Content-Type: application/json" \
  -d '{"token": "…"}'
curl -X POST https://api.allerto.cloud/v1/agents/$AGENT/mcp-test \
  -H "Authorization: Bearer $ALLERTO_API_KEY"

mcp-test connects with the draft's settings and lists the tools the agent would get, each marked read or action. The same is available as allerto agents mcp-token / allerto agents mcp-test, as the MCP tools set_agent_mcp_token / test_agent_mcp, and in the console (agent → Tools).

#Reads and actions

A tool annotated readOnlyHint: true, or a function without "action": true, is a read: it runs as soon as the agent calls it. Every other tool is an action, and Allerto enforces a confirmation that the model cannot skip:

1. The agent calls the action with its data. Nothing is sent to your server: the agent gets back a summary and a one-time confirmation code.
2. The agent reads the summary to the person and asks for an explicit yes.
3. Only a second call with the same data and the code reaches your server or your function, once. A repeated call returns the first result without calling you again.

Each executed action carries _meta["allerto/idempotency_key"] (and every call _meta["allerto/call_id"]), so your server can refuse duplicates on its side too.

#When your server is slow or down

• Tools are listed when the call starts (at most 4 seconds, then cached for 5 minutes). If the server cannot be reached the call goes on without tools and the error is logged on the call.
• A read waits at most 5 seconds, an action 8 seconds. After that the agent is told the system is not answering; after an action it is told it does not know whether the action went through, must not say it is done, and that the team will get back to the person.
• Results are cut to 1,500 characters and treated as data, never as instructions. At most 15 tool calls per call.

Keep results short and phone-sized (two or three options, not a full list): the agent reads them aloud.

#Documents

An agent can also answer from documents you upload: building rules, office hours, frequent questions. No MCP server is needed. Up to 5 documents per agent, 5 MB per file, with at most 200,000 characters of text for all of them together. Formats: pdf, docx, doc, odt, rtf, xlsx, ods, csv, txt, md. Scanned PDFs (images only) are refused: upload a version with selectable text.

curl -X POST "https://api.allerto.cloud/v1/agents/$AGENT/documents?filename=Regolamento.pdf" \
  -H "Authorization: Bearer $ALLERTO_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @Regolamento.pdf

• The file is turned into text when it is uploaded; only the text is kept, encrypted. Check it with GET …/documents/{doc} or in the console (agent → Documents).
• Documents apply at once, to test and phone calls, without publishing: they are not part of the agent document or its versions.
• During the call the voice model does not read them itself. A text model with all the documents answers the question in a few sentences: on gemini-3.8-live through the consulta_documenti tool (logged in tool_calls like any tool), on gpt-live-1 inside its back office. If the documents do not say, the agent says so and collects the request.

#What you get after the call

Every tool call is on the call as tool_calls (API, call.completed, console):

"tool_calls": [
  { "name": "availability", "status": "ok", "arguments": { "day": "thursday" }, "result": "Thursday 15:30 or 17:00.", "duration_ms": 640, "at": "2026-10-01T09:12:03.000Z" },
  { "name": "book", "status": "confirmation_required", "arguments": { "time": "15:30" }, "result": "…", "duration_ms": 1, "at": "…" },
  { "name": "book", "status": "ok", "arguments": { "time": "15:30" }, "result": "Booked, code R-1001.", "duration_ms": 810, "at": "…" }
]

status is ok, error (your server answered with an error), confirmation_required, timeout, unknown_tool or limit. An action whose last entry is not ok did not happen, whatever the agent said: check tool_calls, not the transcript.