# Tool use Function calling: declare tools, dispatch calls, feed results back. On chat completions, the Messages API and the Responses API. Tool use, or function calling, lets the model ask your code to run a function and then use the result. PrivateMind forwards `tools` and `tool_choice` directly to the model's engine. On chat completions the format is OpenAI's, and on the [Messages API](https://docs.privatemind.com/messages-api.html) it is Anthropic's (see [Messages API](https://docs.privatemind.com/tool-use.html#messages-api) below). Both reach the same models and the same tool parsers. The [Responses API](https://docs.privatemind.com/responses-api.html) translates its function tools onto the same path (see [Responses API](https://docs.privatemind.com/tool-use.html#responses-api) below). ```bash curl -s "https://api.privatemind.com/v1/chat/completions" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "fast", "messages": [{"role": "user", "content": "What is the weather in Paris?"}], "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a city", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } } }], "tool_choice": "auto" }' ``` ## Response when the model calls a tool `finish_reason` is `tool_calls`, and `message.tool_calls` holds one or more calls: ```json { "choices": [{ "index": 0, "message": { "role": "assistant", "content": null, "tool_calls": [{ "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" } }] }, "finish_reason": "tool_calls" }] } ``` `arguments` is a **string** of JSON. Parse it before use. > [!WARNING] > Validate every argument before you act on it. The model can invent values, types, or fields that aren't in your schema, and the API doesn't check the call against your JSON Schema. Treat `arguments` like any other untrusted input: parse it, validate it, then run the call. ## Sending the tool result back Append the assistant's tool-call message and a `role: "tool"` message with the result, then call the API again: ```json { "model": "", "messages": [ {"role": "user", "content": "What is the weather in Paris?"}, {"role": "assistant", "content": null, "tool_calls": [ {"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}} ]}, {"role": "tool", "tool_call_id": "call_abc123", "content": "{\"temp_c\": 18, \"conditions\": \"overcast\"}"} ] } ``` The model then continues its answer. ## Tool choice | Value | Behaviour | | --- | --- | | `"auto"` (default) | Model decides whether to call a tool | | `"none"` | Model never calls a tool | | `"required"` | Model must call at least one tool | | `{"type": "function", "function": {"name": "..."}}` | Model must call this specific tool | ## Which models support tools? Models that support tools include `"tools"` in their `supported_parameters` array, which [`GET /v1/models`](https://docs.privatemind.com/models.html) returns. Sending `tools` to a model that doesn't support them returns a `400`. > [!TIP] > A model can return several tool calls in one turn. Loop over `tool_calls[]`, run the calls in parallel where that's safe, and send each result back as its own `role: "tool"` message, one per `tool_call_id`. ## Messages API On `POST /v1/messages`, tools carry an `input_schema`, calls arrive as `tool_use` content blocks, and results go back as `tool_result` blocks in the next user turn. ```python import anthropic client = anthropic.Anthropic(base_url="https://api.privatemind.com", api_key="PMIND...:...") tools = [{ "name": "get_weather", "description": "Get current weather for a city", "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, }] messages = [{"role": "user", "content": "What is the weather in Paris?"}] first = client.messages.create(model="", max_tokens=1024, tools=tools, messages=messages) # first.stop_reason == "tool_use" call = next(b for b in first.content if b.type == "tool_use") # call.input is a dict messages += [ {"role": "assistant", "content": first.content}, {"role": "user", "content": [ {"type": "tool_result", "tool_use_id": call.id, "content": "18C, overcast"}, ]}, ] answer = client.messages.create(model="", max_tokens=1024, tools=tools, messages=messages) ``` - **A turn that calls a tool ends with `stop_reason: "tool_use"`**, even when the model also wrote text. - **`input` is already parsed JSON**, unlike the `arguments` string on chat completions. Validate it all the same. - **Several calls in one turn** come as several `tool_use` blocks. Return one `tool_result` per `tool_use_id`, all in the same user turn. - **A failed tool** is reported with `"is_error": true` on its `tool_result`. - **Send the assistant turn back unchanged**, thinking blocks included, so the model keeps its reasoning across the tool call. `tool_choice` takes these values: | Value | Behaviour | | --- | --- | | `{"type": "auto"}` (default) | Model decides whether to call a tool | | `{"type": "any"}` | Model must call at least one tool | | `{"type": "tool", "name": "..."}` | Model must call this specific tool | | `{"type": "none"}` | Model never calls a tool | Add `"disable_parallel_tool_use": true` to allow at most one call per turn. Only client tools, the ones your code runs, are supported. PrivateMind doesn't run server tools (`web_search`, `web_fetch`, `code_execution`, the MCP connector): it ignores them, and the model answers without them. ## Responses API On `POST /v1/responses`, a function tool carries `name`, `description` and `parameters` at its top level. Calls arrive as `function_call` items in `output`, and results go back as `function_call_output` items. PrivateMind stores no responses, so the next request carries the whole conversation: the earlier input, every output item as it came back, then the results. ```python import json from openai import OpenAI client = OpenAI(base_url="https://api.privatemind.com/v1", api_key="PMIND...:...") tools = [{ "type": "function", "name": "get_weather", "description": "Get current weather for a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, }] history = [{"role": "user", "content": "What is the weather in Paris?"}] first = client.responses.create(model="", tools=tools, input=history) call = next(item for item in first.output if item.type == "function_call") args = json.loads(call.arguments) # {"city": "Paris"} history += first.output history.append({"type": "function_call_output", "call_id": call.call_id, "output": "18C, overcast"}) answer = client.responses.create(model="", tools=tools, input=history) print(answer.output_text) ``` - **`arguments` is a JSON string**, as on chat completions. Parse and validate it. - **Several calls in one turn** come as several `function_call` items. Return one `function_call_output` per `call_id`. - **Send the output items back unchanged**, reasoning items included, so the model keeps its reasoning across the tool call. - **Tools in a `namespace`** come back with the `namespace` as well as the `name`. `tool_choice` takes `"auto"`, `"none"`, `"required"`, `{"type": "function", "name": "..."}`, or `{"type": "allowed_tools", ...}` to offer a subset of the declared tools. Hosted tools such as `web_search` are dropped, and custom tools return `400`. See [Responses API → Tools](https://docs.privatemind.com/responses-api.html#tools) for namespaces, limits and every `tool_choice` form. ## Where next - [Chat completions](https://docs.privatemind.com/chat-completions.html) for the request that carries `tools`. - [Messages API](https://docs.privatemind.com/messages-api.html) for the Anthropic-shape request. - [Responses API](https://docs.privatemind.com/responses-api.html) for the Responses-shape request. - [Streaming](https://docs.privatemind.com/streaming.html) for how `tool_calls` arrive in SSE chunks. - [Models](https://docs.privatemind.com/models.html) to feature-detect which models accept `tools`. - [Shared responsibility](https://docs.privatemind.com/shared-responsibility.html) for what your code owns when it runs a tool.