Tool reference · Search and retrieve
search_crm_objects EngageBay MCP tool
Find the records that match a specific condition — contacts, companies, deals, products, tasks, or appointments — using precise filters rather than a free-text guess. This is the tool your assistant reaches for on almost any “which records…” question.
- Category
- Search and retrieve
- Permission needed
- One per object type — see Permissions below
- Access type
- Read-only
What this tool does
search_crm_objects is the main way your assistant finds records in your EngageBay account. Rather than searching loosely by keyword, it builds a structured filter — for example, “contacts tagged webinar-2026, created in the last 30 days” — and returns exactly the records that match.
It works across every supported record type from a single tool: contacts, companies, deals, products, tasks, and appointments. You tell it which type you want with object_type, and give it the conditions to match with filter_groups.
If you leave the filter out entirely, it doesn't return everything — it returns your most recently updated records for that type, which is a sensible default for a quick “what's new” check.
This is for finding records, not counting them. Each page returns at most 50 records and carries no total. If the question is “how many,” use count_crm_objects instead — it takes the same filters and answers precisely, without pulling back the records themselves.
What you can ask
“Which deals in the Sales pipeline are still at Negotiation?”
“Show me contacts tagged webinar-2026 with a score above 50.”
“What contacts were created in the last 30 days?”
“List tasks assigned to Priya that are overdue.”
“Which companies have no website on file?”
Filter syntax
A filter is a list of groups, and each group is a list of conditions. Conditions inside a group combine with that group’s own condition, which is AND unless you set it to OR. The groups themselves are always combined with OR.
So two groups reading (tagged webinar AND created in the last 30 days) and (score above 50) return every record that satisfies either one. You can send up to 5 groups, each holding up to 10 conditions.
Each condition names a field, an operator, and usually a value. Field names come from get_properties — use the key it returns, never the display label, and note that a field marked filterable: false can be read on a record but cannot be filtered on.
Operators
| Operator | What it does |
|---|---|
EQUALS / NOT_EQUALS | Exact match. On text this is the whole value, not a substring. |
CONTAINS / NOT_CONTAINS | Substring match on text. Rejected on a number. |
IS_EMPTY / IS_NOT_EMPTY | Whether the field has any value. Takes no value at all. |
IS_GREATER_THAN / IS_LESS_THAN | Numeric comparison, exclusive. |
GREATER_THAN_EQUALS / LESS_THAN_EQUALS | Numeric comparison, inclusive. |
ON / BEFORE / AFTER | Date comparison against an ISO-8601 value. |
BETWEEN | Needs value and value_to. Inclusive of both ends, for dates and numbers alike. |
LAST / NEXT | Relative dates. Needs unit — days, weeks or months — alongside a count in value. A month counts as 30 days. |
IN_ARRAY / NOT_IN_ARRAY | Matches any of several values, given in values rather than value. |
Every value is written plainly as a string and the server converts it from the field’s own type — you never declare one. Text is the text itself, numbers are digits, dates are ISO-8601 (2026-03-14 or 2026-03-14T09:21:00Z, the same format dates come back in), and true/false fields take "true" or "false".
A misspelled value is not an error. An unknown field is rejected outright, but a valid field with a value that matches nothing simply returns an empty page — which reads as “no records” rather than “wrong value”. Tag spellings are the usual culprit; confirm them with list_tags first.
Results are sorted by updated_at newest-first unless you pass sort, which takes any filterable field and a direction. A page holds up to 50 records and never carries a total, so use count_crm_objects to answer “how many”, and pass meta.next_cursor back as cursor for the next page.
Permissions
Access is checked per object type, using the same read scopes your connection was granted:
| object_type | Permission required | Returned under |
|---|---|---|
contact | crm.contacts.read | contacts |
company | crm.companies.read | companies |
deal | crm.deals.read | deals |
product | crm.deals.read | products |
task | crm.tasks.read | tasks |
calendar_event | crm.appointments.read | calendar_events |
Less access is handled gracefully. If your connection wasn't granted the permission for a given object type, a search against it returns a clear refusal naming the missing permission — not an empty result that looks like a real answer.
Related tools
get_properties— confirms a field's exact key, type, and accepted values before you filter on it.count_crm_objects— takes the samefilter_groupsand returns a precise count instead of records.get_crm_objects— fetches full detail for specific record ids, always current, once you have them.list_pipelines,list_tags, andlist_users— resolve a pipeline stage, a tag spelling, or a person's name into the exact value a filter needs.
More tools
Use search_crm_objects from your AI tool
Connect your AI tool to the EngageBay MCP server and ask in plain language — it calls the right tool for you.
