Tool
A tool that a model can call to gather information at runtime or perform side effects.
Declaration
protocol Tool<Arguments, Output> : SendableMentioned in
Overview
Tool calling gives the model the ability to call your code to incorporate up-to-date information like recent events and data from your app. A tool includes a name and a description that the framework puts in the prompt to let the model decide when and how often to call your tool.
A Tool defines a call(arguments:) method that takes arguments that conforms to ConvertibleFromGeneratedContent, and returns an output of any type that conforms to PromptRepresentable, allowing the model to understand and reason about in subsequent interactions. Typically, Output is a String or any Generable types.
struct FindContacts: Tool {
let name = "findContacts"
let description = "Find a specific number of contacts"
@Generable
struct Arguments {
@Guide(description: "The number of contacts to get", .range(1...10))
let count: Int
}
func call(arguments: Arguments) async throws -> [String] {
var contacts: [CNContact] = []
// Fetch a number of contacts using the arguments.
let formattedContacts = contacts.map {
"\($0.givenName) \($0.familyName)"
}
return formattedContacts
}
}Tools must conform to Sendable so the framework can run them concurrently. If the model needs to pass the output of one tool as the input to another, it executes back-to-back tool calls.
You control the life cycle of your tool, so you can track the state of it between calls to the model. For example, you might store a list of database records that you don’t want to reuse between tool calls.
Prompting the model with tools contributes to the available context window size. When you provide a tool in your generation request, the framework puts the tool definitions — name, description, parameter information — in the prompt so the model can decide when and how often to call the tool. After calling your tool, the framework returns the tool’s output back to the model for further processing.
To efficiently use tool calling:
Reduce Guide(description:) descriptions to a short phrase each.
Limit the number of tools you use to three to five.
Include a tool only when its necessary for the task you want to perform.
Run an essential tool before calling the model and integrate the tool’s output in the prompt directly.
If your session exceeds the available context size, it throws LanguageModelSession.GenerationError.exceededContextWindowSize(_:). When you encounter the context window limit, consider breaking up tool calls across new LanguageModelSession instances. For more information on managing the context window size, see TN3193: Managing the on-device foundation model’s context window.