Made in 10Docs
GuidesAPI
Characters

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.

Coming soonIn the dashboard

The dashboard's Connectors & tools page is coming soon. Today, make tools through the API.

Make a tool

Create 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:

PUT /v1/characters/{id}/tools
{ "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):

The request
{
  "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"
}
  • arguments are the character's, a JSON object of at most 16 KB. They are not checked against your parameters: check them yourself.
  • metadata is what your server sent when it started the call, {} otherwise.
  • The request is signed exactly as webhooks are, with the tool's secret: webhook-id is the tcl_… 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.

Verify and answer (Node)
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):

tool_calls on 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 organization50
Tools per character20
parameters16 KB
Arguments, and your answer16 KB each
timeout_ms500 to 15,000 (5,000 by default)
Coming soonConnectors

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.

On this page