<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreSpotlight",
  "identifier" : "/documentation/CoreSpotlight/SpotlightSearchTool",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Core Spotlight",
      "FoundationModels"
    ],
    "preciseIdentifier" : "s:31_CoreSpotlight_FoundationModels0B10SearchToolV"
  },
  "title" : "SpotlightSearchTool"
}
-->

# SpotlightSearchTool

A tool you use to make your app’s custom data available to Foundation Models.

```
struct SpotlightSearchTool
```

## Overview

The `SpotlightSearchTool` type implements the protocol that Foundation Models use to run
custom tools when resolving prompts. If you implement intelligent features using the
Foundation Models framework, you can use this tool to provide your app’s data to the
model as additional contextual information. The model can use this additional data to
answer questions specific to your app’s content. For example, a note-taking app that runs
the prompt “Find my meeting notes from last Tuesday” can use this tool to make its notes
available to the model.

Create an instance of `SpotlightSearchTool` before configuring a
<doc://com.apple.documentation/documentation/FoundationModels/LanguageModelSession> object to
run prompts. Configure the tool with the sources and options you want to use to search your
particular content. For example, you can direct the tool to search your app’s Spotlight index,
files and directories your app created, or both. Use the tool options to offer guidance on
how to perform searches efficiently on your content. The following example shows you how to
create and configure this tool with a custom source.

```swift
import CoreSpotlight
import FoundationModels

// Search the app’s Spotlight index and fetch specific attributes for each result.
var csSource = CoreSpotlightSource(fetchAttributes: [.subject, .authorNames, .contentDescription])
csSource.sourceOptions = [.allowMail]
csSource.maximumResultCount = 20

// Create and configure the search tool.
let configuration = SpotlightSearchTool.Configuration(sources: [coreSpotlight(csSource)])
let tool = SpotlightSearchTool(configuration: configuration)

// Set up the Foundation Models session and run a prompt.
let session = LanguageModelSession(tools: [tool])
let response = try await session.respond(to: "Find my notes about the project deadline")
```

## Topics

### Creating the search tool

[`init(configuration:)`](/documentation/CoreSpotlight/SpotlightSearchTool/init(configuration:))

### Configuring the tool behavior

[`configuration`](/documentation/CoreSpotlight/SpotlightSearchTool/configuration-swift.property)

The configuration details for the search tool.

[`SpotlightSearchTool.Configuration`](/documentation/CoreSpotlight/SpotlightSearchTool/Configuration-swift.struct)

The configuration data to use when creating a Spotlight search tool.

[`SpotlightSearchTool.Guide`](/documentation/CoreSpotlight/SpotlightSearchTool/Guide)

A type you use to offer guidance about what search capabillities to employ during a session.

[`SpotlightSearchTool.GuidanceProfile`](/documentation/CoreSpotlight/SpotlightSearchTool/GuidanceProfile)

Options for which techniques to use to determine a match.

[`SpotlightSearchTool.GuidanceLevel`](/documentation/CoreSpotlight/SpotlightSearchTool/GuidanceLevel)

Options for how to search your app’s content.

[`SpotlightSearchTool.ContentDomain`](/documentation/CoreSpotlight/SpotlightSearchTool/ContentDomain)

A content domain that defines which fields and attribute mappings are
presented to the model during a focused search session.

[`SpotlightSearchTool.FormatLevel`](/documentation/CoreSpotlight/SpotlightSearchTool/FormatLevel)

Controls how tool responses are serialized for the model’s context window.

### Getting the search results

[`searchResults`](/documentation/CoreSpotlight/SpotlightSearchTool/searchResults)

An asynchronous stream that delivers the results of a search to your app for processing.

[`SpotlightSearchTool.SearchReply`](/documentation/CoreSpotlight/SpotlightSearchTool/SearchReply)

A set of search results with routing metadata for host app consumption.

### Getting tool-specific properties

[`parameters`](/documentation/CoreSpotlight/SpotlightSearchTool/parameters)

The schema for the parameters this tool accepts.

[`includesSchemaInInstructions`](/documentation/CoreSpotlight/SpotlightSearchTool/includesSchemaInInstructions)

A Boolean value that indicates whether to inject the model’s name, description, and parameters schema into
the instructions of sessions.


---

Copyright &copy; 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)