# ToolIntent A protocol that identifies an app intent that Siri can call while handling a person’s request. ``` protocol ToolIntent : AppIntent ``` ## Overview A *tool* is an [`AppIntent`](/documentation/AppIntents/AppIntent) that Siri can create, configure, and invoke to better respond to a person’s request. Siri can call a tool from a specific app when one or more situations apply to that app, such as: - A person mentions the app by its name - The app is in the foreground - A relevant entity from that app appears in a search result Think through which app intents are appropriate to promote to a tool. The best candidates are typically actions that a person can request in a single sentence, with parameters that Siri can fill in from that request. For example, an intent that adds a product to a shopping cart works well as a tool, because a person can say “Add two packs of AA batteries to my cart,” and Siri can fill in both the product and the quantity. However, some intents don’t make good tools because they serve a different purpose or context. For example, the following app intents don’t apply to a person interacting with Siri: - Widget configuration intents, which don’t invoke an action - Intents that serve as a single step among others within a shortcut - Intents with side effects that a person needs to start explicitly, such as placing an order and paying for it Create a tool from one of your app’s existing intent types by passing the [`tool`](/documentation/AppIntents/AppIntentTraits/tool) trait to its `@AppIntent` macro: ```swift @AppIntent(.tool) struct AddToCart: AppIntent { static let title: LocalizedStringResource = "Add to Cart" static let description = IntentDescription("Adds a product to the shopping cart.") @Parameter(title: "Item", description: "The product to add") var item: ProductEntity @Parameter(title: "Quantity", description: "How many to add", default: 1) var quantity: Int func perform() async throws -> some IntentResult { try await Cart.shared.add(item, quantity: quantity) return .result() } } ``` For each app intent you promote to a tool, help Siri’s model understand what the tool is and how it works by adding the following metadata: - A `title` property that explains what the action is - A `description` property that explains what the action does - A title and description in each parameter’s `@Parameter` attribute that explain the parameter’s role in the action Write each description for someone who doesn’t know your app, and include helpful or important details about a parameter’s value, such as: - The format of a string - The range of a floating-point number - The units of an integer > Note: Some of your app’s intents may already have this metadata if they appear in App Shortcuts, Spotlight, or the Shortcuts app. A tool parameter can be a plain value type or a more complex type, such as one of your app’s [`AppEntity`](/documentation/AppIntents/AppEntity) types. For example, the `item` parameter of `AddToCart` is a `ProductEntity`, which is a type the app defines and implements. Siri finds a product for that parameter by running the entity’s query. Consider making a [`TransientAppEntity`](/documentation/AppIntents/TransientAppEntity) type generable by conforming it to [`GenerableEntity`](/documentation/AppIntents/GenerableEntity) when: - The type is a parameter type for a tool - The model can configure all of the entity’s properties directly from the context of a person’s request, without looking anything up An app intent that conforms to a schema can also be a tool. Add the [`tool`](/documentation/AppIntents/AppIntentTraits/tool) trait to the intent’s existing macro: ```swift @AppIntent(.tool, schema: .books.openBook) struct OpenBookIntent: OpenIntent { // A book the action navigates to in the reading app. var target: BookEntity func perform() async throws -> some IntentResult { // ... } } ``` This combination works only for a schema that’s available exclusively in the Shortcuts app, such as `openBook`. > Important: Adding the trait to an intent that conforms to a schema Siri already supports, such as ``doc://com.apple.AppIntents/documentation/AppIntents/AppSchema/MessagesIntent/sendMessage``, is a build error. For more information about schemas and the domains Siri supports, see [App schema domains](/documentation/AppIntents/app-schema-domains). ## Relationships ### Inherits From [`Sendable`](/documentation/Swift/Sendable) [`AppIntent`](/documentation/AppIntents/AppIntent) [`PersistentlyIdentifiable`](/documentation/AppIntents/PersistentlyIdentifiable) [`SendableMetatype`](/documentation/Swift/SendableMetatype) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)