Skip to content
AppmakeDocs
Log inGet started
Kalle by Appmake API · Endpoints

Tool use

Describe your functions, and Kalle by Appmake asks you to run them when it needs data or wants to act.

Base URLhttps://api.kalle.build/v1AuthBearer kalle_sk_…VersionKalle-Version: 2026-11-01

Define a tool

Each tool has a name, a description that explains when to use it, and an input_schema in JSON Schema. Clear descriptions give better results.

POST/v1/messages
curl https://api.kalle.build/v1/messages \
  -H "Authorization: Bearer $KALLE_API_KEY" \
  -H "Kalle-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kalle-turbo-max",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_schedule",
        "description": "Get the class schedule for one day.",
        "input_schema": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string",
              "description": "The date as YYYY-MM-DD"
            }
          },
          "required": [
            "date"
          ]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Which classes are on Friday?"
      }
    ]
  }'
Open in Appmake

Run the tool and reply

  1. 1Kalle by Appmake asksThe response has stop_reason: "tool_use" and a tool_use block with the tool's name, an id and the input.
  2. 2You run itCall your own function with the input.
  3. 3You send the resultSend the conversation again, with the assistant message and a new user message containing a tool_result block with the same id.
  4. 4Kalle by Appmake answersIt uses the result in its reply, or asks for another tool.
Tool result
{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "tool_9fK2",
    "content": "07:00 Morning flow, 12:15 Lunch yoga, 18:00 Yin"
  }]
}

Controlling tool use

tool_choiceobject{"type": "auto"} lets the model decide (default). {"type": "any"} requires a tool. {"type": "tool", "name": "get_schedule"} requires that tool. {"type": "none"} turns tools off.

Kalle by Appmake can ask for several tools in one reply. Run them all and send all the results in one message. With Kalle-Version: 2026-09-15, a reply has at most one tool_use block.

Each tool_use block has a fresh id starting with tool_. Send it back unchanged in the assistant message and as tool_use_id in the result. Set is_error: true on a result when your function failed.