Tool calling
Moth DocsTutorials
Let a model ask your code for facts it doesn't have, run the function yourself, and hand the result back for the final answer.
You describe each function with a name and a JSON schema. When the model wants one, its reply holds tool_calls instead of an answer. You run the function, send the result back as a tool message, and ask again, until the model answers in words.
import json, os from openai import OpenAI client = OpenAI(base_url="https://api.runmoth.si/v1", api_key=os.environ["MOTH_API_KEY"]) # Your own code, which the model can ask you to run. ORDERS = {"A-1042": "shipped on 12 November", "A-1043": "waiting for payment"} def order_status(order_id: str) -> str: return ORDERS.get(order_id, "no such order") tools = [{ "type": "function", "function": { "name": "order_status", "description": "Look up where an order is.", "parameters": { "type": "object", "properties": {"order_id": {"type": "string", "description": "Such as A-1042"}}, "required": ["order_id"], }, }, }] messages = [{"role": "user", "content": "Where are my orders A-1042 and A-1043?"}] while True: reply = client.chat.completions.create(model="deepseek-v4.1-flash", messages=messages, tools=tools) message = reply.choices[0].message if not message.tool_calls: print(message.content) break messages.append(message.model_dump(exclude_none=True)) for call in message.tool_calls: args = json.loads(call.function.arguments) messages.append({"role": "tool", "tool_call_id": call.id, "content": order_status(**args)})
Run it with python tools.py. The model asks for both orders, the loop answers each call from ORDERS, and the last reply says where each order is.
Which models can call tools
Every chat model whose capabilities.tools is true in the catalog, which today is all of them except claude-fable-5. Asking a model without tools to use them is refused with 400.
To make the model call a tool, send tool_choice as required or as one named function. Models whose capabilities.forced_tool_choice is false refuse that, so send auto to those.
Good to know
- Tools work the same way on the Anthropic format, with
tool_useandtool_resultblocks. - Each loop is a separate paid call, and every call sends the whole conversation again, so keep tool results short.
- The model chooses the arguments, so check them before your function acts on them, the same as any input from outside.
- Web search can't be combined with your own tools in one request.