# OpenAI `tool_call` schema & how a harness emits/processes it
## 1. The schema (Chat Completions / Responses API)
OpenAI's function calling (a.k.a. tool calling) is a multi-step loop between your app and the model. The official guide defines three related objects ([OpenAI Function calling guide](https://developers.openai.com/api/docs/guides/function-calling)):
**Tool definition** — what you send *to* the model (a function tool is defined by a JSON schema):
```json
{
"type": "function",
"function": {
"name": "get_horoscope",
"description": "Get today's horoscope for an astrological sign.",
"parameters": {
"type": "object",
"properties": {
"sign": { "type": "string", "description": "An astrological sign like Taurus or Aquarius" }
},
"required": ["sign"],
"additionalProperties": false
},
"strict": true
}
}
```
**Tool call** — what the model returns *to you* when it decides it needs a tool. It lives on the assistant message as `message.tool_calls[]`, and each entry has this shape:
```json
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_horoscope",
"arguments": "{\"sign\":\"Aquarius\"}" // JSON-encoded string, NOT an object
}
}
```
Key points: `arguments` is a **JSON string** you must parse; `id` is the unique `call_id` you echo back.
**Tool output** — what you send back to the model, as a `role: "tool"` message that references the original call by id:
```json
{ "role": "tool", "tool_call_id": "call_abc123", "content": "{\"horoscope\":\"...\"}" }
```
The official 5-step flow is: (1) request with tools → (2) receive tool call → (3) execute code with the call's input → (4) second request with the tool output → (5) final response (or more tool calls) ([OpenAI Function calling guide](https://developers.openai.com/api/docs/guides/function-calling)).
## 2. How a harness emits and processes tool calls
A "harness" is the agent loop that owns this orchestration. The [Agent-Harness repo](https://github.com/michaellaret7/Agent-Harness) is a concrete example — it "streams tokens from a chat-completions endpoint, parses tool calls, executes them, and feeds the results back — until the model stops asking for tools and returns a final answer." Here's how it works:
### Emitting (sending tool definitions + the request)
The harness builds the `tools` list (the schema above) and passes it with `messages` to `client.chat.completions.create(...)`. Its `messages.py` constructors produce plain dicts in the exact wire shape the SDK expects — including `assistant_msg(content, tool_calls)` which attaches `tool_calls` to an assistant message, and `tool_msg(tool_call_id, content)` which builds the `role: "tool"` result message ([messages.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/messages.py)).
### Processing (the loop)
The load-bearing file is `loop.py`. Because streaming responses arrive in fragments, the loop:
1. **Streams** the completion, surfacing content/reasoning deltas to a Sink.
2. **Reassembles fragmented `tool_calls`** — tool-call fragments arrive keyed by index, with the function name on the first fragment and `arguments` dribbling in across many chunks; the loop does an index-keyed merge, concatenating argument fragments into one complete dict ([loop.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/loop.py)).
3. **Classifies** the iteration outcome (`answer_ready`, `tool_calls`, `cancelled`, `partial_cancelled`).
4. **Dispatches** each complete tool call to `ToolHandler.execute()`, which unpacks `tc['id']`, `tc['function']['name']`, and `tc['function']['arguments']`, parses the JSON args, runs the matching Python callable, and returns `tool_msg(tc['id'], result)` messages ([tool_handler.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py)).
5. **Appends** the assistant message (with its `tool_calls`) and the `role: "tool"` results to `messages`, then calls the model again — repeating until the model returns plain content.
The handler also supports **parallel dispatch** (tools marked `safe_parallel` run concurrently via a `ThreadPoolExecutor`, while non-parallel tools act as barriers) and **cancellation** (interrupted tool calls are synthesized as `[interrupted]` results so the `tool_call`/`tool_result` pairing stays well-formed in history) ([tool_handler.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py)).
## TL;DR
- **Schema**: `tools[]` (definitions you send) → `message.tool_calls[]` (calls the model returns, with `id`, `type`, `function.name`, and JSON-string `function.arguments`) → `role:"tool"` messages (results you send back, keyed by `tool_call_id`).
- **Harness emit**: builds the `tools` list + messages, calls the API, and attaches any returned `tool_calls` to the assistant message in history.
- **Harness process**: reassembles streamed fragments into complete calls, parses `arguments`, executes the matching function, and feeds results back as `role:"tool"` messages — looping until the model answers.
Sources:
- [OpenAI Function calling guide](https://developers.openai.com/api/docs/guides/function-calling)
- [Agent-Harness README](https://github.com/michaellaret7/Agent-Harness)
- [loop.py (streaming loop + tool-call reassembly)](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/loop.py)
- [tool_handler.py (dispatch/execution)](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py)
- [messages.py (message constructors)](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/messages.py)
Cited source trail
help me understand openai tool_call schema, how does harness emit it and process it
Next step
Research any question with live sources, then publish the cited answer as a free shareable link.
Sources visited
1searchOpenAI tool_call schema function calling API documentation
2searchOpenAI tool calling harness emit process tool_calls response
3navigatehttps://developers.openai.com/api/docs/guides/function-calling
4navigatehttps://github.com/michaellaret7/Agent-Harness
5get_text
6navigatehttps://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/loop.py
7get_text
8navigatehttps://developers.openai.com/api/docs/guides/function-calling
9ddm--text --find tool_calls
10get_text
11navigatehttps://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/messages.py
12navigatehttps://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py
Ask your own question
Search live sources for a question you choose. You can publish the cited answer as a free link.