Start here
Tool Calling in plain language
For application-defined tools, the developer describes the available operation and its inputs. The model can request a call, but application code must check and execute it. Some platforms also offer provider-hosted tools whose execution is managed by the provider.
The useful separation is between a request, an authorised execution and a confirmed result. A well-formed request may still contain a wrong identifier, ask for another customer’s data or fail when the service is unavailable.
How it works
A tool request is not yet an action
An application-defined tool
- Model requests
Selects a tool and supplies structured arguments.
- Application checks
Validates arguments, user permissions and any required approval.
- Tool executes
Runs the permitted operation and returns a result or error.
Return the result to the model, which can answer or request a further permitted step.
Describe the contract
Use an unambiguous name, input types and a narrow purpose. A lookup tool should not silently update a record.
Validate and execute
Check the requested operation against the authenticated user. Do not let the model invent the identity on whose behalf a request runs.
Handle the actual result
Pass useful data or a clear error back. Distinguish “not found”, “not allowed” and “service unavailable” in application handling.
Illustrative example · Fictional data
Looking up a fictional order
- Input
- A signed-in customer asks about order TV-104. The application offers get_order_status with an order_id argument.
- Process
- The model requests TV-104. The application checks ownership, then reads the order service. It returns status: dispatched, with no confirmed arrival date.
- Expected output
- “Your order has been dispatched. A confirmed delivery date is not available in this result.”
- How to check it
- Try another customer’s order ID and a service timeout. Neither should produce leaked order details or an invented delivery date.
Where it helps
- Reading a current order or account status.
- Running deterministic calculations instead of guessing arithmetic.
- Preparing a calendar change and executing it only after the required confirmation.
Tool call, API and agent
- API
- An interface for software to request an operation. It need not involve an AI model.
- Tool call
- A model’s structured request that a runtime maps to an operation, which may use an API.
- Agent
- A system that can use tool results to choose subsequent actions towards a goal.
Related reading and learning pathways
Common pitfalls
- Valid JSON does not mean a valid business action.
- Blind retries can repeat a write; use an operation identifier or another duplicate-prevention mechanism.
- Tool descriptions help selection but do not replace authorisation enforced by code.
Put the idea to work
Try it yourself
Define a read-only stock-check tool with three outcomes: available, unavailable and lookup failed. Write the expected assistant reply for each, including what it must not claim.
Common questions
Is function calling different from tool calling?
The terms often overlap. Function calling commonly describes structured requests to application functions; tool use can also cover provider-managed capabilities. Check the platform’s terminology. In both cases the model returns a structured request, such as a function name with arguments, and your application decides whether and how to run it.
What is the difference between tool calling and plugins?
Tool calling is the model-API capability: the model returns a structured request naming an operation and its arguments, and your application decides whether to run it. “Plugins” described a product-level packaging built on top of that idea, so that end users of a chat product could enable a third-party capability without writing code; the packaging has since been superseded by other extension mechanisms, and the underlying mechanism is still tool calling. The practical difference is who holds responsibility. With a plugin-style extension, the product vendor defines how the capability is surfaced, approved and limited. When you implement tool calling yourself, your code owns the tool contract, the authorisation check, the execution and the error handling — which is why developer documentation uses tool calling or function calling rather than the product term.
Can tools run in parallel?
Where the model and runtime support it, independent calls can run together. Calls that depend on earlier results must still respect that dependency. Parallel calls can cut waiting time when, for example, an assistant fetches weather and calendar data at once. Your code should still handle partial failures and combine results in a defined order.
Does a successful tool call guarantee a correct answer?
No. The operation may return incomplete information, and the model may misread it. Check both execution and the final answer. Log the tool inputs and outputs so you can tell whether a wrong answer came from the tool, the data it returned or the model’s interpretation of that data.
Your next step
Continue learning
Connected concepts
Sources and further reading
Examples on this page are teaching exercises using fictional information. They are not client case studies or measured outcomes.