---
slug: 51-llm-tool-calling
title: Tool calling
description: Let the model pick a tool safely with llm_step + call_tool — an in-language loop with an allow-list, per-tool least-privilege, frozen intent, and a bounded budget.
example_ids: [tool-calling]
---

# Tool calling

The four ops return text. To let the model pick a **tool** (a structured `{tool, args}` choice), Synsema adds `llm_step` + `call_tool`. The safety loop is written **in-language**, so the model never gains new powers.

```synsema
-- Doc example: tool-calling. A "tool" is just a task; call() invokes it with named
-- args. The llm_step loop that lets the MODEL pick a tool is shown in the prose.
intent: "doc example: tool-calling"
require llm

task get_weather(city)
    give "weather in " + city + ": sunny"

print(call(get_weather, {"city": "Lima"}))    -- run shows: weather in Lima: sunny

test "a tool is a normal task; call() invokes it with named args from a map"
    assert_eq(get_weather("Paris"), "weather in Paris: sunny")
    assert_eq(call(get_weather, {"city": "Lima"}), "weather in Lima: sunny")
```

## The primitives

- `llm_step(prompt, catalog, context)` → the model's decision: `{kind: "final", text, tokens}` or `{kind: "tool", name, args, tokens}`. `catalog` is plain data; `tokens` lets you enforce a budget.
- `call(task, args_map)` → call a task with named args from a map.
- `call_tool(task, args_map)` → dispatch a chosen tool **least-privilege**: it runs with only the capabilities it declared (∩ the agent's), even if the agent has more.

## The safe loop

```synsema
require llm

task get_weather(city)
    require net("api.weather.com")               -- the tool's own declaration
    give "weather in " + city + ": sunny"

let tools be {"get_weather": get_weather}        -- ALLOW-LIST (name → task)
let catalog be [{"name": "get_weather", "describe": "Weather for a city", "params": ["city"]}]

task run_agent(question, max_steps, budget)
    let spent be 0
    let n be 0
    let ctx be ""
    while (n < max_steps) and (spent <= budget)  -- bounded loop (budget guard in the condition)
        set n to n + 1
        let step be llm_step(question, catalog, ctx)
        set spent to spent + step["tokens"]
        when step["kind"] == "final"
            give step["text"]
        otherwise when contains(tools, step["name"])     -- only allow-listed names dispatch
            let result be call_tool(tools[step["name"]], step["args"])
            set ctx to ctx + " [" + step["name"] + " => " + text(result) + "]"
        otherwise
            set ctx to ctx + " [" + step["name"] + " => not allowed]"   -- injected/hallucinated → rejected
    give "out of steps"
```

The model only returns a tool **name**; your program decides whether to run it. Security = allow-list + per-task capability gate + frozen intent + bounded loop. Offline, `llm_step` returns `{kind: "final", text: "[no llm provider]", tokens: 0}`.