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.

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

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}.