create_calendar_event or before drafting mail whenever only a name is known.
A query is required: this tool searches, it does not enumerate the address book. When several plausible people match, present the candidates rather than picking one.
Contacts with no email address at all — the kind create_contact writes from a name and a postal address — are found by name like any other.
Parameters
string
required
Name, partial name, email address, or organization. 1–200 characters. Matched against display names, organization names, addresses, and address domains — so
acme.example finds everyone at that domain.string
default:"any"
Biases which address is reported as the best one when a person has addresses in several contexts.
work prefers organization-domain addresses, private prefers personal-domain addresses, and any applies no bias. This never filters a person out of the results.string
default:"concise"
concise returns the name, contact id, best address, confidence, relationship, and the last three interactions. detailed adds every known address with its own confidence and last-seen date, the phone numbers, structured postal addresses and note kept on the record, where the record came from, the full interaction log with record ids for chaining into get_email or list_calendar_events, and any excluded relay addresses.integer
default:"5"
Maximum number of matching people, 1–25.
Ratings
Every match carries two independent ratings. They are separate because a person you have frequent contact with may still have no usable address — someone reachable only through a platform’s notification relay, for example.address_confidence says how reliable the name-to-address pairing is:
relationship says how much interaction exists, regardless of address quality:
Raw interaction counts are deliberately not exposed. The label answers “how much”; the
last_interactions lines answer “which person is this” and give the agent something concrete to cite.
Example
Call
Result
detailed format each person additionally lists every known address and the record ids behind the interactions:
Result
contact_id addresses the record in update_contact and delete_contact; it is in the concise format too, so editing a contact never costs an extra detailed round-trip. The [p0] and [a0] handles address one phone number or one postal address within the record — update_contact takes them directly.
source says where the record came from: derived (built by collection from mail headers and calendar attendees), authored (written with create_contact), or imported (already in an address book on the account and never observed here). It is reported because address_confidence means different things across them — an inference in the first case, the user’s own assertion in the second.
Phone numbers, postal addresses and the note appear only in detailed: an agent resolving a name before drafting mail has no use for a street address, and concise is what that call reads.
Interaction lines are hydrated at query time — subjects and event titles are never stored on the contact card, so a message or event that has since been deleted renders as (message no longer available) or (event no longer available). When any shown person has excluded relays, the response ends with a note pointing at the detailed format. When more people matched than limit allows, it ends with a truncation note naming the total and asking for a narrower query; if the candidate window was full, the total is reported as “at least”.
Errors
query must not be empty.— thequeryvalue was only whitespace.No contact matched "<query>" in the collected address book ...— not an error but an empty result. It names what was searched and suggests searching for part of the address or the organization instead, and points out that a person you only know through a platform relay has no email address in the account’s data.
Where the data comes from
The collected address book is populated by two writers, and a third source sits alongside it: contacts written withcreate_contact, which cover the people derivation structurally cannot reach. The email-agent adds senders and recipients as mail is ingested, skipping junk, drafts, and Langmail’s own daily brief. The calendar tools add attendees and organizers whenever an event is created, updated, or responded to — which is how an address that only ever appeared in an invitation you sent becomes findable.
Relay and machine addresses (no-reply senders, bounce plumbing, platform digest addresses) never become contacts. When one is seen alongside a person you do know, it is remembered on that person’s card and reported as excluded, so “you only have platform contact with this person” is distinguishable from “this person is unknown”.
Cards carry no mail content — no subjects, no event titles — because the address book syncs to every device you connect over CardDAV. Only record identifiers are stored, and the readable lines are fetched under your own credentials when you call the tool.