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 it is Anthropic's (see Messages API below). Both reach the same models and the same tool parsers. The Responses API translates its function tools onto the same path (see Responses API below).
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:
{
"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.
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:
{
"model": "<tool-capable-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 returns. Sending tools to a model that doesn't support them returns a 400.
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.
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="<model-id>", 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="<model-id>", 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. inputis already parsed JSON, unlike theargumentsstring on chat completions. Validate it all the same.- Several calls in one turn come as several
tool_useblocks. Return onetool_resultpertool_use_id, all in the same user turn. - A failed tool is reported with
"is_error": trueon itstool_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.
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="<model-id>", 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="<model-id>", tools=tools, input=history)
print(answer.output_text)argumentsis a JSON string, as on chat completions. Parse and validate it.- Several calls in one turn come as several
function_callitems. Return onefunction_call_outputpercall_id. - Send the output items back unchanged, reasoning items included, so the model keeps its reasoning across the tool call.
- Tools in a
namespacecome back with thenamespaceas well as thename.
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 for namespaces, limits and every tool_choice form.
Where next
- Chat completions for the request that carries
tools. - Messages API for the Anthropic-shape request.
- Responses API for the Responses-shape request.
- Streaming for how
tool_callsarrive in SSE chunks. - Models to feature-detect which models accept
tools. - Shared responsibility for what your code owns when it runs a tool.