People and companies
People operations (contacts.*) and company operations (organizations.*) work with the people and companies TalkBar knows. In talkbar_find, these are the person and company kinds. To name or link a speaker in a session, see the sessions.speakers.* operations on Sessions. Every operation also takes an optional workspaceId. See How to read this reference for the conventions.
| Operation | Kind | Tool | On | Group |
|---|---|---|---|---|
contacts.list | Read | talkbar_read | On | content |
contacts.get | Read | talkbar_read | On | content |
contacts.sessions | Read | talkbar_read | On | content |
contacts.create | Write | talkbar_change | Off | contentChanges |
contacts.update | Write | talkbar_change | Off | contentChanges |
contacts.archive | Write | talkbar_delete | Off | contentChanges |
contacts.unarchive | Write | talkbar_change | Off | contentChanges |
organizations.list | Read | talkbar_read | On | content |
organizations.get | Read | talkbar_read | On | content |
organizations.create | Write | talkbar_change | Off | contentChanges |
organizations.update | Write | talkbar_change | Off | contentChanges |
organizations.archive | Write | talkbar_delete | Off | contentChanges |
organizations.unarchive | Write | talkbar_change | Off | contentChanges |
contacts.list
Lists the people in a workspace, with how many sessions each spoke in and when the latest started.
Read · runs with talkbar_read · MCP switch On by default · policy group content
Arguments
Only people of this project.
Text to find in names and emails.
Also list archived people. Default false.
How many to return. From 1 to 500. Default 100.
Returns: {contacts: [{contactId, name, email, role, organizationId, archived, sessionCount, lastMetAtMs}]}.
sessionCountandlastMetAtMscount the sessionscontacts.sessionslists (the person spoke; sessions in the Trash left out). A person never heard has0andnull.
{"tool": "contacts.list", "args": {"query": "dana"}}
contacts.get
Reads one person's details.
Read · runs with talkbar_read · MCP switch On by default · policy group content
Arguments
The person, from contacts.list.
Returns: {contactId, name, email, phone, role, organizationId, relationshipTag, sentiment, notes, confirmed, lastContactAtMs, archived, createdAt, updatedAt}.
contacts.sessions
Lists the sessions a person spoke in, newest first, with the name they had in each, their talk time and their share of all talk.
Read · runs with talkbar_read · MCP switch On by default · policy group content
Arguments
The person, from contacts.list.
How many to return. From 1 to 200. Default 100.
nextOffset from the previous page.
Returns: {contactId, sessions: [{sessionId, title, startedAtMs, endedAtMs, speaker, talkTimeMs, share, excludedFromAi, private}], hasMore, nextOffset}. share is 0 to 1 of everyone's talk time.
- Pass
speakeras thespeakerfilter ofsessions.transcriptto read what the person said.
{"tool": "contacts.sessions", "args": {"contactId": "ct_77", "limit": 10}}
contacts.create
Adds a person.
Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges
Arguments
The person's name. Must not be empty.
Email address. It must have text before and after a single @ and no spaces; the domain is not checked.
Phone number.
Role or job title.
A short tag for how you know them.
Plain-text notes.
Returns: The person, as contacts.get returns it.
{"tool": "contacts.create", "args": {"name": "Dana Lee", "email": "dana@example.com", "role": "CFO"}}
contacts.update
Changes a person's name, email, phone, role, relationship tag or notes.
Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges
Arguments
The person, from contacts.list.
The new name. Must not be empty.
Email address, with the same check as contacts.create. null or an empty string clears it.
Phone number. null clears it.
Role or job title. null clears it.
A short tag for how you know them. null clears it.
Plain-text notes; they replace any formatted notes. null clears them.
Returns: The person, as contacts.get returns it.
- Give at least one field.
contacts.archive
Archives a person. Their history stays, and they stay editable.
Write · runs with talkbar_delete · MCP switch Off by default · policy group contentChanges
Arguments
The person, from contacts.list.
Returns: The person's list row (contactId, name, email, role, organizationId, archived).
- Undo with
contacts.unarchive. - Runs with
talkbar_delete: confirmed with you when your AI app can ask; apps that cannot ask are refused unless Allow deletes without confirmation is on.
contacts.unarchive
Brings an archived person back.
Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges
Arguments
The person, from contacts.list.
Returns: The person's list row, as contacts.archive returns it.
organizations.list
Lists the companies in a workspace.
Read · runs with talkbar_read · MCP switch On by default · policy group content
Arguments
Only companies of this project.
Text to find in names and websites.
Also list archived companies. Default false.
How many to return. From 1 to 500. Default 100.
Returns: {organizations: [{organizationId, name, relationship, website, pinned, archived}]}.
organizations.get
Reads one company's details, archived companies included.
Read · runs with talkbar_read · MCP switch On by default · policy group content
Arguments
The company, from organizations.list.
Returns: The list row plus notes, createdAt and updatedAt.
organizations.create
Adds a company.
Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges
Arguments
The company name. Must not be empty.
One of client, vendor, partner, prospect, internal, investor, advisor, candidate_company, other. Default other.
Free text, as in the app (northwind.example is fine). Blank means none. javascript:, vbscript: and data: links are refused.
Plain-text notes.
Returns: The company, as organizations.get returns it.
{"tool": "organizations.create", "args": {"name": "Northwind", "relationship": "client", "website": "northwind.example"}}
organizations.update
Changes a company's name, relationship, website or notes.
Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges
Arguments
The company, from organizations.list.
The new name. Must not be empty.
One of client, vendor, partner, prospect, internal, investor, advisor, candidate_company, other.
Same rules as organizations.create. null clears it.
Plain-text notes. null clears them.
Returns: The company, as organizations.get returns it.
- Give at least one field.
organizations.archive
Archives a company. Its history stays.
Write · runs with talkbar_delete · MCP switch Off by default · policy group contentChanges
Arguments
The company, from organizations.list.
Returns: The company's list row.
- Undo with
organizations.unarchive. - Runs with
talkbar_delete: confirmed with you when your AI app can ask; apps that cannot ask are refused unless Allow deletes without confirmation is on.
organizations.unarchive
Brings an archived company back.
Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges
Arguments
The company, from organizations.list.
Returns: The company's list row.