Tools
Let a character call your own HTTPS endpoints mid-call, to look up an order or book a slot, signed like webhooks and never retried.
A tool is one of your HTTPS endpoints a character may call during a call: "look up an order", "book a slot". You describe what it does and what it takes; the character decides when to call it, says a short line while it waits, and answers from what your endpoint returns.
A tool can also run on your website's page instead (runs_on: "page"): during a call in the bubble there, your page's own code does it, like adding to the cart. See Tools on your page.
The dashboard's Connectors & tools page is coming soon. Today, make tools through the API.
Make a tool
Prop
Type
curl https://talk.madein10.com/v1/tools \
-H "Authorization: Bearer $SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_status",
"description": "Looks up an order'\''s status by its number.",
"parameters": { "type": "object", "properties": { "order": { "type": "string" } }, "required": ["order"] },
"url": "https://example.com/hooks/order-status",
"filler": "One moment while I check."
}'The answer is { "tool": Tool, "secret": "whsec_…" }. The secret signs every request to your endpoint and is shown only now (and after a rotation): keep it.
Then set a character's tools with the whole ordered list:
{ "ids": ["tool_6Mx1Rb8QwT3kNv5LcZ9p"] }What your endpoint receives
When the character calls the tool, we POST to your url (content-type: application/json, user-agent: acme-tools/1):
{
"arguments": { "order": "A-17" },
"call_id": "call_2Gx7Mb9KpQ4sVn1ZrT6e",
"character_id": "chr_4fT9kQ2mXw7LbN3pZs8V",
"id": "tcl_4Zq9Hv2NcP7xMb1KrW6s",
"metadata": { "ticket": 7 },
"tool": "order_status",
"tool_id": "tool_6Mx1Rb8QwT3kNv5LcZ9p"
}argumentsare the character's, a JSON object of at most 16 KB. They are not checked against yourparameters: check them yourself.metadatais what your server sent when it started the call,{}otherwise.- The request is signed exactly as webhooks are, with the tool's secret:
webhook-idis thetcl_…id. Verify the raw body and refuse a timestamp more than 5 minutes off.
The reference has the request in full: A tool call to the tool's own URL.
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.TOOL_SECRET); // whsec_…
export async function POST(request) {
const raw = await request.text(); // the body exactly as it arrived
let call;
try {
call = wh.verify(raw, Object.fromEntries(request.headers));
} catch {
return new Response("bad signature", { status: 401 });
}
const status = await lookUpOrder(call.arguments.order);
return Response.json({ status, eta: "Tuesday" });
}With our SDK, readToolCall from @acme/client/server does the same checks (SDKs).
What your endpoint answers
A 2xx within timeout_ms, with JSON of any shape or plain text, at most 16 KB. The character gets it as the tool's result: text as it is, JSON as JSON, an empty body as "Done.".
Anything else is a failure, and the character is told in a few words of ours, never your endpoint's own text:
- no answer in time ("it didn't answer within 5 seconds");
- another status ("its endpoint answered 500");
- a redirect (not followed);
- more than 16 KB;
- a refused connection, or an address that now points inside a network.
Nothing is retried
A tool can book or charge, and a second request could do it twice, so we never retry. The character may call the tool again; that's a new request with a new webhook-id.
On a call
- The character gets its turned-on tools: their names, descriptions, parameters, timeouts and fillers, never their addresses.
- When it calls one, it says the filler at once, then waits for your answer. A person who talks over the wait interrupts it like any reply.
- At most 3 tool calls a turn; a turn's tools run at the same time.
- Tools work on tiers where our own pipeline takes the turns. A tier that runs on a speech-to-speech model takes no tools.
- Deleting a tool detaches it; a call that asks for it is told it's gone.
Each use is logged, never with its arguments or your answer, and shows on the call (Get a call):
[{ "id": "tcl_4Zq9Hv2NcP7xMb1KrW6s", "tool_id": "tool_6Mx1Rb8QwT3kNv5LcZ9p", "tool_name": "order_status",
"ok": true, "status_code": 200, "duration_ms": 412, "error": null, "created_unix": 1793300050 }]Your server also hears each use live on the call's live events socket as a tool message.
Rotate the secret
Rotate a tool's secret makes a new one, shown in the answer. For grace_seconds (a day by default, up to 7 days) both secrets sign every request, so you can switch without missing one; 0 stops the old one at once, for a leaked secret.
Limits
| Tools per organization | 50 |
| Tools per character | 20 |
parameters | 16 KB |
| Arguments, and your answer | 16 KB each |
timeout_ms | 500 to 15,000 (5,000 by default) |
Ready-made connections to apps such as calendars and chat tools are for later. Today, a character reaches other services through your own tools or your own MCP server.