Get API key

Tool use

View as Markdown

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 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
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": "<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.

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="<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.
  • 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="<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)
  • 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 for namespaces, limits and every tool_choice form.

Where next