Notes on a tool call that needs a second turn

A function call is a request from a model to your application. The model proposes a tool and its arguments; your code decides whether to execute it, runs the operation, and returns the result. The model can then use that result in its next response. Most production problems appear at these boundaries, even when the initial demonstration works perfectly.

For experienced API users, the useful starting point is to treat function calling as a small execution protocol. The schema, conversation history, authorization checks, and retry policy all participate in its behavior.

Make each tool describe one operational decision. A tool named manage_customer with an action field leaves substantial interpretation to the model and your dispatcher. Separate operations such as get_customer and update_customer_email make permissions, validation, and failure handling easier to reason about. Describe when each tool should be used, which identifiers it expects, and whether it changes persistent state.

Keep arguments narrow. Require a customer ID when the operation needs one. Use an enum for a closed set of statuses. Distinguish an omitted field from an explicit null wherever that difference changes behavior. Avoid asking the model to supply values your application already knows, such as the authenticated account ID.

Separate valid arguments from authorized actions. Schema validation can establish that an amount is a number. It cannot establish that the caller may issue a refund. Validate arguments on the server, resolve resources within the authenticated user's scope, and apply business rules before execution. Where a provider supports strict schema enforcement, enable it only with a supported schema; keep application validation in place.

Tool descriptions also form part of the model's decision context. Give them the same review attention as prompts. A description that says “always use this tool” can cause unnecessary calls, while an unclear description can make the model request information already present in the conversation.

Preserve the complete call-and-result sequence. In an OpenAI-style chat workflow, retain the assistant message containing tool calls, execute the permitted calls, and append a tool result for each call using its matching identifier. Then request the next model response. Do not replace the assistant message with a paraphrase or detach results from their call IDs.

Vana API exposes an OpenAI-compatible endpoint and also accepts Anthropic Messages and Gemini native protocols. That gives an application several integration paths, but each path still has its own message structure. Preserve the tool-use blocks, result associations, and any additional continuation data required by the protocol you selected. Confirm model-specific tool support before moving an existing workflow.

Assume a turn may contain several calls. Independent read operations can often run concurrently. Calls that depend on earlier results need sequencing. Two writes against the same resource may need serialization even when the model emits them together. Your application should determine execution order from dependencies and consistency requirements.

• Set a maximum number of tool rounds per user request.
• Apply timeouts and response-size limits to each tool.
• Return structured errors with stable error codes and a clear indication of whether retrying could help.
• Record call IDs, latency, validation failures, and execution outcomes.

Design retries around the operation. Retrying a failed lookup is usually straightforward. Retrying a payment after a connection timeout requires knowing whether the first attempt succeeded. Use application-controlled idempotency keys for operations that support them, and reconcile uncertain outcomes before issuing another write. A model-generated call identifier is useful for conversation correlation, but it is not automatically a durable business-operation identifier.

Keep tool results concise and untrusted. Return the fields needed for the next decision. Large payloads increase context usage and can bury relevant facts. Treat retrieved text as data, including text that appears to instruct the assistant. Tool output should never grant permissions or override application policy.

Create a Vana API account to test this loop with your existing OpenAI SDK. Billing is per real token with no monthly fee, so measure the complete exchange: tool definitions, arguments, returned data, and the final answer. A useful test includes malformed arguments, partial failures, duplicate execution attempts, and a successful response after recovery.