People

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Person`person`

Someone in the user's life: contact details, relationship, dates, and notes.

people_getPersonFindthrough vritto_find

Fetch one person by ID.

Field	Type	Description
personId*	string	Person ID.

people_queryPeopleFindthrough vritto_find

Search people by free text, optionally scoped. Listing without a query defaults to "touched" (people the user actually knows) rather than their whole address book. Rows are compact summaries; people_getPerson for one full record.

Field	Type	Description
query	string	Search query.
view	one of all, circle, favorites, archived, touched, imported	View. Defaults to "touched" when listing with no query, and to "all" when searching. "touched" = people the user has actually done something with (stated a relationship, pinned, edited, or named in a meal/gift/watch/trip). "imported" = the complement, untouched contacts from a provider import. "circ
detail	one of summary, full	Row shape: "summary" (default, name/relationship/org/city/tags) or "full" (complete person records, prefer people_getPerson instead).
limit	integer	Max records to return (default 50 in summary mode).

people_queryPeopleStatsFindthrough vritto_find

Count people: total, archived, pinned, favorites. Prefer this over people_queryPeople for how-many questions.

No input.

people_resolvePersonFindthrough vritto_find

Resolve a person by name, email, or phone before any write. Returns ranked candidates with confidence.

Field	Type	Description
query	string	Name or search query.
email	string	Exact email address.
phone	string	Exact phone number.
detail	one of summary, full	Candidate shape: "summary" (default, name/relationship/org) or "full" (complete person records).
limit	integer	Maximum candidates (defaults to 8).

people_createPersonCreatethrough vritto_create

Create one person. Only displayName is required; add contact points, addresses, tags, dates, and notes when known. Set relationshipToMe only if the user has said what this person is to them.

Note: Resolve first with people_resolvePerson so the same person is not added twice.

Field	Type	Description
person*	object	Person fields. Only displayName is required at the top level; entries inside emails, phones, addresses, importantDates, relationships, and notes have their own required fields.
person.displayName*	string	Full display name.
person.givenName	string	Given name.
person.middleName	string	Middle name.
person.familyName	string	Family name.
person.nickname	string	Nickname.
person.pronouns	string	Pronouns.
person.photoUrl	string	Photo URL. Must be https:// - http:// and other schemes are rejected. Pass "" to clear it.
person.birthday	string	Annual birthday in MM-DD format, e.g. "03-14"; must be a real calendar date. Pass "" to clear it.
person.birthYear	integer	Birth year, when known. Pass null to clear it.
person.organization	object	Workplace details. Merged one level deep by people_patchPerson.
person.emails	list of object	Email addresses.
person.phones	list of object	Phone numbers.
person.addresses	list of object	Places this person is tied to, home, work, hometown.
person.tags	list of string	User-authored tags (unique, case-insensitive).
person.importedTags	list of string	Provider labels from an import, never author these. Include them UNCHANGED on people_updatePerson (omitting clears them); manage via people_resolveImportedTags.
person.relationshipToMe	object	Who this person is to the user, only as they stated it; prefer people_setPersonRelationshipToMe.
person.pinned	boolean	User's pin into their Circle, a placement preference, not a closeness claim; prefer people_setPersonPinned.
person.importantDates	list of object	Dates worth remembering; recurring by default.
person.relationships	list of object	Links to other saved people. Each personId must already exist and cannot be this person.
person.notes	list of object	Relationship notes.
person.favorite	boolean	Whether this person is a favorite.

Example input

{
  "person": {
    "displayName": "Priya Shah",
    "givenName": "Priya",
    "familyName": "Shah",
    "emails": [
      {
        "id": "email1",
        "label": "Personal",
        "value": "priya.shah@example.com"
      }
    ],
    "birthday": "03-12",
    "birthYear": 1994
  }
}

people_applyPeopleTagGroupUpdatethrough vritto_update

Apply a tag as a group across people: members get the tag, everyone else loses it. Pass currentTag when renaming an existing group.

Field	Type	Description
tag*	string	Group (tag) name to apply.
currentTag	string	Existing group name being renamed, if any.
memberIds*	list of string	Person IDs that should carry the tag; others lose it.

people_patchPersonUpdatethrough vritto_update

Patch one person: omitted fields keep their values; organization/relationshipToMe merge one level deep. ARRAYS replace wholesale: read the person first and send each array complete.

Note: Omitted fields keep their values; arrays replace wholesale, so send the full list when changing one.

Field	Type	Description
personId*	string	Person ID.
patch*	object	Person fields to change; omitted fields keep their current value. Family facts (documents, medical, nationalities) are settable ONLY here.
patch.displayName	string	Full display name.
patch.givenName	string	Given name.
patch.middleName	string	Middle name.
patch.familyName	string	Family name.
patch.nickname	string	Nickname.
patch.pronouns	string	Pronouns.
patch.photoUrl	string	Photo URL. Must be https:// - http:// and other schemes are rejected. Pass "" to clear it.
patch.birthday	string	Annual birthday in MM-DD format, e.g. "03-14"; must be a real calendar date. Pass "" to clear it.
patch.birthYear	integer	Birth year, when known. Pass null to clear it.
patch.organization	object	Workplace details. Merged one level deep by people_patchPerson.
patch.emails	list of object	Email addresses.
patch.phones	list of object	Phone numbers.
patch.addresses	list of object	Places this person is tied to, home, work, hometown.
patch.tags	list of string	User-authored tags (unique, case-insensitive).
patch.importedTags	list of string	Provider labels from an import, never author these. Include them UNCHANGED on people_updatePerson (omitting clears them); manage via people_resolveImportedTags.
patch.relationshipToMe	object	Who this person is to the user, only as they stated it; prefer people_setPersonRelationshipToMe.
patch.pinned	boolean	User's pin into their Circle, a placement preference, not a closeness claim; prefer people_setPersonPinned.
patch.importantDates	list of object	Dates worth remembering; recurring by default.
patch.relationships	list of object	Links to other saved people. Each personId must already exist and cannot be this person.
patch.notes	list of object	Relationship notes.
patch.favorite	boolean	Whether this person is a favorite.
patch.nationalities	list of string
patch.documents	list of object	ID/travel documents; array replaces wholesale. Reads never return numbers.
patch.medical	object	Medical basics (allergies, blood type).
expectedRevision	integer	Current record revision; the write aborts if it changed elsewhere.

Example input

{
  "personId": "person_priya",
  "patch": {
    "nickname": "Pri"
  }
}

people_resolveImportedTagsUpdatethrough vritto_update

Promote imported provider labels to real tags and/or dismiss them, across everyone at once (case-insensitive). Only labels the user asked for, dismissing is not undoable.

Field	Type	Description
promote	list of string	Imported labels to turn into real user tags (unique, case-insensitive).
dismiss	list of string	Imported labels to drop (unique, case-insensitive).

people_setPersonArchivedUpdatethrough vritto_update

Archive or unarchive a person without deleting their data.

Field	Type	Description
personId*	string	Person ID.
archived*	boolean	True to archive, false to restore.
expectedRevision*	integer	Current record revision; the write aborts if it changed elsewhere.

people_setPersonPinnedUpdatethrough vritto_update

Pin or unpin a person into the Circle, a placement preference, not a relationship claim (that is people_setPersonRelationshipToMe).

Field	Type	Description
personId*	string	Person ID.
pinned*	boolean	True to pin into the Circle, false to unpin.

people_setPersonRelationshipToMeUpdatethrough vritto_update

State who a person is to the user, ONLY as the user said it, never inferred. Replaces the whole edge (include everything to keep); kind "none" removes it.

Note: Replaces the whole relationship; include everything to keep.

Field	Type	Description
personId*	string	Person ID.
relationshipToMe*	object	The relationship this person has to the user, as the user stated it.
relationshipToMe.kind*	one of none, partner, spouse, engaged, ex_partner, parent, child, sibling, grandparent, grandchild, family, friend, colleague, mentor	What this person is to the user, a stated fact, never inferred. "none" = not stated. (No closeness ranks, by design, see the module guide.)
relationshipToMe.start	object	When the relationship began, if the user said.
relationshipToMe.end	object	When it ended, if the user said.
relationshipToMe.current	boolean	Whether the relationship is ongoing. Defaults to true.
relationshipToMe.note	string	The user's own words about this relationship.
expectedRevision	integer	Current record revision; the write aborts if it changed elsewhere.

people_deletePersonDeletethrough vritto_delete

Permanently delete a person, remove them from moments, and drop relationship references from other people. This cannot be undone.

Field	Type	Description
personId*	string	Person ID.
expectedRevision*	integer	Current record revision; the write aborts if it changed elsewhere.

Person Moment`person_moment`

A dated moment with people, from before Memories existed.

people_queryPeopleMomentsFindthrough vritto_find

List relationship moments, most recent first, optionally filtered to one person.

Field	Type	Description
personId	string	Only moments involving this person.
limit	integer	Max records to return (defaults to 200).

people_updatePeopleMomentUpdatethrough vritto_update

Replace a relationship moment's fields by moment ID.

Note: Replaces the moment's fields; send every field to keep.

Field	Type	Description
moment*	object	Complete replacement moment, including its id.
moment.id*	string	Moment ID.
moment.personIds*	list of string	IDs of the people this moment involves.
moment.kind*	one of memory, meetup, gift, follow_up, milestone	Moment kind.
moment.title*	string	Moment title.
moment.details	string	Details.
moment.occurredOn*	string	Date the moment occurred or is planned (YYYY-MM-DD).
moment.reminderAt	string	Optional reminder time as an ISO 8601 datetime.
moment.status	one of open, completed	Moment status; anything other than "open" is stored as completed.
expectedRevision*	integer	Current record revision; the write aborts if it changed elsewhere.

people_deletePeopleMomentDeletethrough vritto_delete

Permanently delete a relationship moment and cancel its reminder.

Field	Type	Description
momentId*	string	Moment ID.
expectedRevision*	integer	Current record revision; the write aborts if it changed elsewhere.

Person Date`person_date`

Birthdays and important dates on the calendar; read-only.

people_getPeopleCalendarOccurrencesFindthrough vritto_find

Read people-derived calendar occurrences (birthdays, important dates, and dated moments) inside a window of at most 93 days.

Field	Type	Description
start*	string	Window start as an ISO 8601 datetime (inclusive).
end*	string	Window end as an ISO 8601 datetime (exclusive; at most 93 days after start).

Kept in the Vritto app

people_googlePeopleAuth: Connects, syncs, or disconnects another account.
people_listGooglePeopleConnections: Connects, syncs, or disconnects another account.
people_syncGooglePeople: Connects, syncs, or disconnects another account.
people_disconnectGooglePeople: Connects, syncs, or disconnects another account.
people_createPersonGift: Superseded by a newer operation that is on MCP.
people_queryPersonGifts: Superseded by a newer operation that is on MCP.
people_updatePersonGift: Superseded by a newer operation that is on MCP.
people_deletePersonGift: Superseded by a newer operation that is on MCP.
people_createPeopleMoment: Superseded by a newer operation that is on MCP.
people_updatePerson: Replaces a whole record and clears omitted fields; the merge operation is on MCP instead.

People

Personperson

Person Momentperson_moment

Person Dateperson_date

Kept in the Vritto app

Person`person`

Person Moment`person_moment`

Person Date`person_date`