Bluwing returns a deterministic response object with a high-level status discriminator. Your application handles one of three well-defined cases on every turn:
Status field indicates resolution outcome
Array of executable functions with grounded arguments
Clarifying question when required parameter is absent
Fast deadband routing (<20ms) for general conversational prompts
1. tool_calls: Ready for Execution
When one or more tools match with high confidence and all required parameters are present, status is "tool_calls".
{
"id": "res_01jc8w4n6f2q7v9k3d5t",
"status": "tool_calls",
"tool_calls": [
{
"id": "call_8f2k1q",
"name": "book_table",
"arguments": {
"restaurant": "Nok",
"party_size": 4,
"date": "2026-11-15",
"time": "19:00"
},
"confidence": 0.9842,
"side_effect": "write",
"requires_confirmation": false,
"grounding": {
"restaurant": "Nok",
"party_size": "four people",
"date": "tomorrow",
"time": "7pm"
}
}
],
"needs_input": [],
"message": null,
"timing_us": {
"total": 21850
},
"token_usage": {
"prompt_tokens": 14,
"completion_tokens": 42,
"metered_input_tokens": 14
}
}Tool Call Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique call identifier (e.g. call_8f2k1q). |
name | string | The exact function name from your toolset schema. |
arguments | object | Parsed and validated typed arguments matching your JSON Schema. |
confidence | number | Calibrated model probability (0.0 to 1.0). Typical matches score > 0.85. |
side_effect | string | "read" (safe idempotent read), "write" (state-mutating database write), or "irreversible" (financial transfers, deletions). |
requires_confirmation | boolean | true if the tool definition flags this action as needing explicit user approval before execution. |
grounding | object | Substrings from the user prompt or facts that substantiate each parameter value. |
2. needs_input: Clarifying Missing Arguments
If an ideal tool matches the user's intent, but one or more required parameters are missing from both the user prompt and facts, Bluwing will never make up a guess. Instead, it returns status: "needs_input":
{
"id": "res_01jc8w5p1a3x7e2k4m9v",
"status": "needs_input",
"tool_calls": [],
"needs_input": [
{
"parameter": "party_size",
"question": "For how many people should I reserve the table?"
}
],
"message": "For how many people should I reserve the table?",
"timing_us": { "total": 19400 }
}Your frontend can directly present message to the user. When the user responds with "For 4 people", re-invoke resolve with the original context or facts.
3. no_tool: Deadband & Conversational Prompts
When the prompt is general conversation ("Good morning", "Tell me a joke") or completely unrelated to your tools, the engine avoids false positives and answers status: "no_tool" in under 20 ms:
{
"id": "res_01jc8w6z9d8c2m1v4k5t",
"status": "no_tool",
"tool_calls": [],
"needs_input": [],
"message": null,
"timing_us": { "total": 16200 }
}When receiving no_tool, pass the prompt to your general LLM to reply directly to the user.
Complete TypeScript Handling Pattern
import OpenAI from "openai";
import { executeTool } from "./services/tools";
import { streamChatReply } from "./services/llm";
const openai = new OpenAI({
baseURL: "https://api.bluwing.si/v1",
apiKey: process.env.BLUWING_API_KEY,
});
async function handleUserTurn(userId: string, userText: string, tools: any[]) {
const completion = await openai.chat.completions.create({
model: "bluwing",
messages: [{ role: "user", content: userText }],
tools,
});
const choice = completion.choices[0];
if (choice.finish_reason === "tool_calls" && choice.message.tool_calls) {
for (const toolCall of choice.message.tool_calls) {
const args = JSON.parse(toolCall.function.arguments);
await executeTool(toolCall.function.name, args);
}
return { ok: true, executed: choice.message.tool_calls.map((c) => c.function.name) };
} else if (choice.message.content) {
// Missing required parameters: ask the clarifying question
return { reply: choice.message.content };
} else {
// Conversational fallback
return { stream: streamChatReply(userText) };
}
}