Common Room

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), "objectAssocType" (e.g. "default" or a smart account link type), and an optional "description" explaining when to use that association (e.g. current vs. previous employment) — pass the chosen objectAssocType in a filter's targetAssocPaths to direct the link.

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, surgingTopics), "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). Set targetAssocPaths to null by default — the system auto-resolves the path. Only when directing a specific advertised association (the catalog "assocs" list more than one association to that target, each with a "description"), set targetAssocPaths to a single one-segment path carrying that segment's "assocType" — e.g. [[{ "target": "Object", "objectConfigId": "cot_5", "assocType": "account_contact_direct_salesforce_prev_employment_link" }]]. 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 } Member roles: to filter contacts by job role, first call commonroom_list_objects with objectType "MemberRole" (set limit, e.g. 100) to discover the community's most common role values ranked by contact count, then pass those values to the memberRole filter (operators any, none). Bombora surging topics: first call commonroom_list_objects with objectType "BomboraTopic" to discover the exact topic names the community is subscribed to, then pass those names to the surgingTopics filter (operators any, none). 16. Organizations surging on specific Bombora topics: { "objectType": "Organization", "filter": { "type": "and", "clauses": [{ "type": "stringListFilter", "field": "surgingTopics", "params": { "op": "any", "value": ["Customer Data Platform", "Marketing Automation"] } }] }, "properties": ["name", "surgingTopics"], "limit": 25 } 17. Contacts whose company is surging on a Bombora topic (cross-object — surgingTopics is an Organization field, so wrap it in a target "Organization" clause): { "objectType": "Contact", "filter": { "type": "and", "clauses": [{ "type": "and", "target": "Organization", "objectConfigId": null, "targetAssocPaths": null, "clauses": [{ "type": "stringListFilter", "field": "surgingTopics", "params": { "op": "any", "value": ["Customer Data Platform"] } }] }] }, "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

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 or organization. Requires "note" and exactly one of "contactId" or "organizationId". - 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).

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).