Common Room

commonroom_get_catalog

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

commonroom_list_objects

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), or "Activity" for Activity fields (e.g. activityTime, activityType, activityProviderId) on Contact queries only. 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 }

commonroom_submit_feedback

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