Search contacts
search_contactsResolve names, partial names, email addresses, organizations, or roles like “my lawyer” to known contacts, ranked by role and interaction recency, before drafting mail or creating events.
Instructions
Resolve a person's name, partial name, email address, organization, or what they are to the user ("my lawyer", "my landlord") to known contacts. People holding that role come first, the rest are ranked by interaction recency and frequency. Sources include the collected address book maintained from mail headers (both directions, including Sent) and calendar attendees and organizers, plus the user's personal address books, and contacts written with create_contact. Use this before creating events or drafting mail when only a name is known, and before create_contact or update_contact to get the contact_id. Returns for each contact its roles, one or more addresses with a confidence level, the birthday when one is stored, and recent interactions; the detailed format adds phone numbers, postal addresses and the note. Do not use it to enumerate all contacts; a query is required, and for "whose birthday is coming up" use list_upcoming_birthdays instead. If several plausible people match, present the candidates to the user rather than guessing; when two of them are the same person or organization, merge_contacts folds them into one.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_contacts"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of matching people. | |
| query | Yes | Name, partial name, email address, organization, or what the person is to the user ("lawyer", "my landlord"). Matched against display names, organizations, addresses, address domains, and the roles stored on contacts. | |
| context | No | Biases address ranking when a person has addresses in several contexts. `work` prefers organization-domain addresses; `private` prefers personal-domain addresses. Never filters a person out entirely. | any |
| response_format | No | `concise` returns name, contact id, roles, best address, confidence, relationship, the birthday when stored, and the last interactions. `detailed` adds all known addresses with their own confidence, phone numbers, postal addresses, the note, where the record came from, and interaction record ids (for chaining into get_email or list_calendar_events), plus excluded relay addresses. | concise |