Tool calling lets a model request a named operation with structured arguments. The application, not the model, validates those arguments, decides whether execution is allowed, runs the tool, and returns the result for the next model response. A tool call is proposed data, not trusted code or automatic permission to act.
Who this is for: Developers and technical product owners connecting language models to APIs, databases, search, or business actions.
- Describe narrow tools with explicit input schemas and unambiguous outcomes.
- Validate authorization and arguments in application code before every execution.
- Return concise, structured observations and preserve the full call trail for review.
The model proposes an operation
A developer provides tool definitions alongside the conversation. Each definition usually includes a name, a purpose, and a schema for arguments. When a request requires outside information or an action, the model can produce a structured request such as get_order_status with an order identifier instead of inventing the status in prose.
The exact API fields and supported schema features can change. Check the current platform documentation rather than copying an old request body. The durable design principle is to make tools distinct enough that the model can select correctly. A vague do_business_task tool hides authority and makes both testing and review difficult.
The application remains the executor
Receiving a tool call does not perform the operation. Application code parses the proposed arguments, validates them against a schema, checks the current user's identity and permission, and applies business rules. Only then does it invoke the underlying service. This boundary prevents a model response from bypassing controls already required by the product.
Authorization must be checked at execution time, not encoded only in the prompt. A model may be manipulated by untrusted content or may simply choose the wrong tool. High-impact or irreversible calls should create a pending action for human approval. Read tools should also enforce tenant and field boundaries because disclosure can be harmful without a write.
Results become observations
After execution, the application sends a tool result back into the conversation with the matching call identifier. The result should contain what the model needs for the next decision, such as status, relevant fields, and a clear error. Dumping an entire internal record increases exposure and makes it harder for the model to find the important signal.
Tool errors are observations too. Distinguish not found, forbidden, temporary failure, and invalid arguments so the workflow can respond appropriately. Do not let the model retry indefinitely. A bounded policy might permit one corrected read request, then stop and tell the user what could not be completed.
Design calls for evaluation
Test the complete loop, not only whether the final answer sounds right. Record whether the correct tool was selected, whether arguments matched the user request, whether forbidden calls were blocked, and whether the response represented the returned data faithfully. Include cases where no tool should be called and where tool output contains misleading instructions.
Logs should connect the user request, model output, validated call, execution result, and final response while minimizing sensitive content. Assign stable tool and schema versions so a regression can be traced to a definition change. If current provider behavior affects parallel calls or call formatting, verify it against official documentation during quarterly maintenance.
Look up a shipment without exposing other orders
A customer asks an assistant for the status of order 4821 in an authenticated support portal.
- Expose a get_order_status tool whose input accepts one order identifier and whose description says it only reads status and estimated delivery data.
- When the model proposes order 4821, validate the identifier and confirm that the signed-in customer owns that order before querying the service.
- Return a compact result containing delivery state, last scan time, and an explicit unavailable field rather than the full order record.
- Have the model explain the status without inventing a delivery promise, and log the call identifiers and authorization outcome.
Tool definition review sheet
Review each exposed operation with these fields before deployment.
- Purpose and non-purpose: one clear job plus actions the tool never performs.
- Arguments: required fields, allowed values, size limits, and rejection behavior.
- Authorization: user, tenant, resource, and approval checks applied by code.
- Observation: minimum result fields, error categories, and sensitive-data handling.
- Operations: timeout, retry, idempotency, logging, and schema version.
Common mistakes
- Treating a model-generated function name and argument object as already authorized application input.
- Returning broad database rows when the next reasoning step needs only two approved fields.
- Describing overlapping tools so loosely that selection errors cannot be diagnosed or evaluated.
Try one
Design the execution checks for a tool that schedules a meeting from a user's request and calendar availability.
A strong answer validates attendees, time zone, duration, available slot, and the signed-in user's calendar permission. It previews the exact event and requires confirmation before creating it, then uses an idempotency key to avoid duplicates. It returns a structured success or conflict result and limits retries. Evaluation should reject an answer that relies on the prompt alone for authorization or silently invites external attendees.
Sources
- OpenAI function calling guideOfficial guidance for defining tools, receiving tool calls, and returning tool results.
- OpenAI tools guideOfficial overview of currently supported tools and tool-use patterns.