NameSearch
Search items by their name or title: document name, email subject, agent session title, channel name, project name, call-record name, or calendar event title.
Starter documentation. Features and account details may differ from this deployment.
NameSearch
Search items by their name or title: document name, email subject, agent session title, channel name, project name, call-record name, or calendar event title. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type, and keep that scope on follow-ups and retries. Results for documents, emails, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist). A calendar event result is one copy of the event on a calendar the user can see, not all of them theirs: calendarName names that calendar, contributesToAvailability says whether it is on the user's schedule, and role says whether they organize it or are a guest. A result without contributesToAvailability carries none of this, as on an event shared with them, so say you cannot tell rather than infer anything from the missing fields. Otherwise only role says the user organizes an event: organizer is whoever the provider names, which on a read-only calendar can be the user's own mailbox, so without a role tell them they do not organize it. Say "your calendar" only when contributesToAvailability is true or there is a role. Any other result is what that calendar shows, not where the user is or what they are doing, even when they ask about "my" event: never call it their appointment, trip or meeting. Say "user@example.com's calendar has..." when calendarName shows whose it is; if it does not, say you cannot tell rather than guess.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name or title to search. Pass 1-3 keywords drawn from words that would literally appear in the title, not the user's natural-language description. Whitespace-separated terms are ANDed. For non-email types the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. For emails each term is matched against the subject. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token matching instead of prefix. |
matchType | "partial" | "exact" | No | How search tools match query terms. Restricted to partial/exact — the backend also supports regexp and an internal query mode, but those are not offered to the model. |
entityTypes | ("agent_sessions" | "documents" | "emails" | "channels" | "projects" | "call_records" | "calendar_events")[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. |
inbox | string | No | Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results. |
tags | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, projects, call records, calendar events) can match, so channels are dropped while a tag filter is active. |
tagsMatch | "any" | "all" | No | How multiple tag filters combine when filtering items. |