Common Room

Creates a new object in Common Room.

Supported object types:

• Contact: Creates or updates a contact. Provide "email" and "fullName", or pass a "prospectorContactId" to create from a ProspectorContact (the API will resolve prospect data automatically). Optionally set custom fields via "customFields" array.
• Segment: Creates a new static segment. Requires "name". Optional "entityType" ("contact" or "organization", defaults to "contact").
• Activity: Creates a timestamped activity on a contact. Requires "contactId", "activityType" (see schema enum), "activityBody". Use commonroom_list_objects with objectType "ActivityType" to discover valid activityType values.
• Note: Creates a text note on a contact profile. Requires "contactId", "note".
• Organization: Creates or updates an organization. Provide "domain", or pass a "prospectorCompanyId" to create from a ProspectorCompany (the API will resolve prospect data automatically). Optional "name".

Use commonroom_list_objects to look up contact emails, segment IDs (s_-prefixed), and custom field IDs (cf_-prefixed).

Returns available object types, their properties, allowed sort fields, and association metadata for Common Room API queries. Each object may include an "assocs" array with partial metadata about connected objects. Each assoc has "targetEntity" (display name), "targetObjectTypeId" (null for Contact/Organization, "cot_X" for custom objects), and "objectAssocType" (e.g. "default" or a smart account link type).

Retrieves Common Room objects (contacts, organizations, segments, etc.) with pagination, filtering, and sorting. Call commonroom_get_catalog first to discover available objects, their filter fields, allowed properties, and sort options.

Full tool-call examples: 1. Contacts by name in a segment: { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "stringFilter", "field": "fullName", "params": { "op": "like", "value": "Tracy" } }, { "type": "stringListFilter", "field": "memberSegmentId", "params": { "op": "any", "value": ["s_1"] } }] }, "properties": ["primaryEmail", "title", "companyName"], "limit": 20 }

2. Recent conversation threads sorted by time: { "objectType": "Activity", "filter": { "type": "and", "clauses": [{ "type": "dateRangeFilter", "field": "activityTime", "params": { "op": "in", "value": "P7D", "min": null, "max": null } }, { "type": "booleanFilter", "field": "activityIsParent", "params": { "op": "eq", "value": true } }] }, "properties": ["content", "url"], "sort": "activityTime", "direction": "desc", "limit": 50 }

3. Large organizations sorted by member count: { "objectType": "Organization", "filter": { "type": "and", "clauses": [{ "type": "numberFilter", "field": "groupCompanySize", "params": { "op": "gte", "value": 100 } }] }, "sort": "member_count", "direction": "desc", "limit": 25 }

4. Contacts with email who are engineers or managers (AND+OR): { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "booleanFilter", "field": "memberHasEmail", "params": { "op": "eq", "value": true } }, { "type": "or", "clauses": [{ "type": "stringFilter", "field": "title", "params": { "op": "like", "value": "Engineer" } }, { "type": "stringFilter", "field": "title", "params": { "op": "like", "value": "Manager" } }] }] }, "properties": ["primaryEmail", "title", "companyName"] }

5. Activities between two dates: { "objectType": "Activity", "filter": { "type": "and", "clauses": [{ "type": "dateRangeFilter", "field": "activityTime", "params": { "op": "between", "value": null, "min": "2025-01-01T00:00:00Z", "max": "2025-03-01T00:00:00Z" } }] }, "limit": 100 }

Use "properties" to select specific fields (e.g., ["primaryEmail", "title"]). Use "sort" + "direction" for ordering (e.g., sort: "member_count", direction: "desc").

Cross-object filtering: Use "target" on a nested group clause to filter by fields from a related object type. Use target "Organization" for Organization fields (e.g. groupRevenue, groupSubIndustry), "Contact" for Contact fields (e.g. title, memberHasEmail), "Activity" for Activity fields (e.g. activityTime, activityType, activityProviderId) on Contact queries only, "ProspectorCompany" for ProspectorCompany fields (e.g. groupRevenue, groupCompanySize, groupTechStackId) on ProspectorContact queries, or "ProspectorContact" for ProspectorContact fields (e.g. title, fullName) on ProspectorCompany queries. Set objectConfigId and targetAssocPaths to null.

6. Contacts at high-revenue organizations (cross-object): { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "Organization", "objectConfigId": null, "targetAssocPaths": null, "clauses": [{ "type": "numberFilter", "field": "groupRevenue", "params": { "op": "gte", "value": 1000000 } }] }] }, "properties": ["primaryEmail", "title", "companyName"], "limit": 50 }

7. Organizations with contacts titled CEO (cross-object): { "objectType": "Organization", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "Contact", "objectConfigId": null, "targetAssocPaths": null, "clauses": [{ "type": "stringFilter", "field": "title", "params": { "op": "like", "value": "CEO" } }] }] }, "limit": 25 }

8. Contacts with recent activity (cross-object): { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "Activity", "objectConfigId": null, "targetAssocPaths": null, "clauses": [{ "type": "dateRangeFilter", "field": "activityTime", "params": { "op": "in", "value": "P7D", "min": null, "max": null } }] }] }, "properties": ["primaryEmail", "title", "companyName"], "limit": 50 }

Custom object cross-object filtering: Use target "Object" with objectConfigId to filter by custom object fields. Use the "assocs" array from the catalog to find junction objects for multi-hop filtering (see examples 9–10). Always set targetAssocPaths to null — the system auto-resolves the path.

When a user says "account", check the catalog for a custom object type named "Account" and prefer it over the Organization entity type.

9. Contacts linked to an Account through a junction object (Account Contact): { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "Object", "objectConfigId": "cot_10", "targetAssocPaths": null, "clauses": [{ "type": "and", "target": "Object", "objectConfigId": "cot_5", "targetAssocPaths": null, "clauses": [{ "type": "stringFilter", "field": "objectName", "params": { "op": "like", "value": "Acme" } }] }] }] }, "properties": ["primaryEmail", "title"], "limit": 50 }

10. Contacts linked to an Account with open Opportunities (multi-hop): { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "Object", "objectConfigId": "cot_5", "targetAssocPaths": null, "clauses": [{ "type": "and", "target": "Object", "objectConfigId": "cot_8", "targetAssocPaths": null, "clauses": [{ "type": "stringFilter", "field": "objectName", "params": { "op": "like", "value": "Open" } }] }] }] }, "properties": ["primaryEmail", "title"], "limit": 50 }

11. ProspectorContacts who are Engineers at companies with revenue >= $1M (cross-prospector): { "objectType": "ProspectorContact", "filter": { "type": "and", "clauses": [{ "type": "stringFilter", "field": "title", "params": { "op": "like", "value": "Engineer" } }, { "type": "and", "target": "ProspectorCompany", "objectConfigId": null, "targetAssocPaths": null, "clauses": [{ "type": "numberFilter", "field": "groupRevenue", "params": { "op": "gte", "value": 1000000 } }] }] }, "properties": ["fullName", "title", "companyName"], "limit": 50 }

12. ProspectorCompanies with contacts titled CEO (cross-prospector): { "objectType": "ProspectorCompany", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "ProspectorContact", "objectConfigId": null, "targetAssocPaths": null, "clauses": [{ "type": "stringFilter", "field": "title", "params": { "op": "like", "value": "CEO" } }] }] }, "limit": 25 }

13. ProspectorContacts in specific locations (use commonroom_list_objects with objectType "Location" to discover Location IDs): { "objectType": "ProspectorContact", "filter": { "type": "and", "clauses": [{ "type": "stringListFilter", "field": "locationId", "params": { "op": "any", "value": ["196644", "196537"] } }] }, "properties": ["fullName", "title", "companyName"], "limit": 50 }

14. Activities excluding teammates (recommended for sentiment, engagement, and other community-facing metrics): { "objectType": "Activity", "filter": { "type": "and", "clauses": [{ "type": "booleanFilter", "field": "activityIsTeamMember", "params": { "op": "eq", "value": false } }] }, "limit": 100 }

15. Contacts excluding teammates: { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "booleanFilter", "field": "isTeamMember", "params": { "op": "eq", "value": false } }] }, "properties": ["primaryEmail", "title", "companyName"], "limit": 50 }

Submit feedback about query results. Use after presenting data to the user.

When to use:

• User indicates the results were helpful/useful
• User says the data was not what they were looking for
• User provides specific feedback about data quality

Updates an existing Common Room object by ID. Supports the same fields as commonroom_create_object.

Supported object types:

• Contact: Updates a contact by ID. Requires "contactId" (c_-prefixed). Supports all contact fields: "fullName", "email", "title", "companyName", "companyDomain", "githubUsername", "twitterHandle", "linkedInUrl", "segmentId", "customFields".
• Organization: Updates an organization by ID. Requires "organizationId" (o_-prefixed). Supports "segmentId", "customFields".

Use commonroom_list_objects to look up object IDs, segment IDs (s_-prefixed), and custom field IDs (cf_-prefixed).