Tools — Data

Eight tools for searching, aggregating, charting, exporting/importing, and managing CRM data at scale.

crm_global_search

Search across ALL objects in one call. Returns matching records grouped by object type, each with its real match total.

Parameters

Behavior

• Runs the SAME search path as the in-app global search (unaccent + trigram ILIKE over fields flagged searchable, plus compound EMAILS/PHONES). Results match the UI.
• Searches every object readable through the generic boundary; metadata-hidden internals (interactions, threads, etc.) are excluded, and RBAC view-level is enforced per object.
• Results are grouped by object type. Each group carries objectName, objectLabel, the real total, and the page of records.
• When object_name is provided, only that object is searched.

Examples

"Find everything related to Acme"

{
  "query": "acme"
}

Returns matches across contacts, companies, opportunities, and any custom objects:

{
  "query": "acme",
  "results": [
    { "objectName": "companies", "objectLabel": "Companies", "total": 1, "records": [/* … */] },
    { "objectName": "contacts", "objectLabel": "Contacts", "total": 3, "records": [/* … */] }
  ],
  "total": 4
}

"Search only contacts named Martin, newest first"

{
  "query": "martin",
  "object_name": "contacts",
  "sort": "[{\"field\":\"created_at\",\"direction\":\"desc\"}]"
}

crm_aggregate_records

Calculate aggregations on a CRM object, optionally grouped by one field.

Parameters

Behavior

• The function is re-validated against the field's real type. SUM/AVG/MIN/MAX/MEDIAN/RANGE/STDDEV/VARIANCE require a numeric field (NUMBER, INTEGER, DECIMAL, PERCENT, RATING, CURRENCY, or a numeric CALCULATED/ROLLUP). COUNT/COUNT_DISTINCT/PERCENT_FILLED/PERCENT_EMPTY/COUNT_NULL work on any field.
• An invalid function/field combination returns INVALID_OPERATION with the allowed list.
• CURRENCY fields can be passed directly — their amount is summed (multi-currency amounts are summed without conversion).
• Composite parents (CURRENCY, DATE_RANGE, …) resolve to their canonical child (amount, start) automatically.
• RBAC is enforced — no view access returns PERMISSION_DENIED.
• Limitations: single group_by only (no second axis / top-N), single simple filter (use filters for richer slices), no date bucketing.

Examples

"How many contacts do I have per status?"

{
  "object_name": "contacts",
  "field": "id",
  "function": "COUNT",
  "group_by": "status"
}

Grouped responses return one row per distinct value:

{
  "object_name": "contacts",
  "field": "id",
  "function": "COUNT",
  "group_by": "status",
  "results": [
    { "group": "prospect", "value": 42 },
    { "group": "customer", "value": 18 },
    { "group": null, "value": 3 }
  ]
}

"Sum deal amount for open deals"

{
  "object_name": "opportunities",
  "field": "amount",
  "function": "SUM",
  "filters": "{\"type\":\"AND\",\"conditions\":[{\"field\":\"stage\",\"operator\":\"not_equals\",\"value\":\"closed\"}]}"
}

Scalar responses return a single value:

{
  "object_name": "opportunities",
  "field": "amount",
  "function": "SUM",
  "value": 184500
}

crm_manage_dashboards

List dashboards, or pin a chart — typically one just built with crm_aggregate_records — onto one. The MCP App attached to crm_aggregate_records calls this tool from its "add to dashboard" button, but you can also call it directly.

Parameters

For add_chart / create, pass the same params you used for crm_aggregate_records (object_name, metric_field, aggregation, group_by, filters) plus chart_type and title.

Example

"Pin this 'contacts by source' chart to my Sales dashboard"

{
  "action": "add_chart",
  "dashboard_id": "d1a2b3c4-…",
  "object_name": "contacts",
  "metric_field": "id",
  "aggregation": "COUNT",
  "group_by": "source",
  "chart_type": "doughnut",
  "title": "Contacts by source"
}

crm_export_records

Export CRM data as JSON or CSV. UUID references are resolved to display values — never raw UUIDs.

Parameters

Behavior

• Admin-only — non-admin tokens return PERMISSION_DENIED.
• RBAC and object visibility are enforced; reference fields (relations, rollups) are resolved from UUID to the target's display value.
• When fields is omitted, all main fields are exported and internal/noise columns (full-text vector, raw enrichment blobs) are stripped. An explicit fields list is honoured verbatim.
• The hard limit is 10000 records per call.

Examples

"Export all contacts as CSV"

{
  "object_name": "contacts",
  "format": "csv"
}

"Export the 200 newest open opportunities, name and amount only"

{
  "object_name": "opportunities",
  "format": "csv",
  "fields": ["name", "amount"],
  "filter_field": "stage",
  "filter_operator": "not_equals",
  "filter_value": "closed",
  "sort_by": "created_at",
  "sort_dir": "desc",
  "limit": 200
}

crm_import_records

Multi-step import that mirrors the Kasar platform import flow: the AI proposes a column→field mapping, the user validates it, then it runs through the same engine the platform uses (relations, dedup, field/enum creation).

The action sequence

1. analyze — pass object_name + data. Returns an import_job_id and a proposed mapping per column (each column has its suggestion, sample_values, and confidence), plus the object's target fields.
2. Review/adjust the mapping, then present it to the user.
3. preview (optional) — pass import_job_id (+ any mapping overrides). Returns transformed sample rows, the effective_mapping, column diagnostics, and duplicate detection so the user can validate.
4. execute — only after the user confirms. Imports ≤2000 rows immediately and returns counts; larger imports are queued on the worker (poll with status).
5. status — pass import_job_id to get progress/result of a queued import.

Parameters

Each mapping entry:

import_options:

Behavior

• Admin-only across every step.
• analyze stages the data and produces a deterministic gold-standard mapping; pass only the columns you change in mapping.
• execute re-checks create permission. Imports of 2000 rows or fewer run synchronously and return inline counts (created, updated, skipped, failed, plus new-field / enum / M2M details). Larger imports are queued on the BullMQ worker and return mode: "queued" — poll with status.
• add_to_list_ids / create_list_name apply only to synchronous (≤2000) imports; for queued imports a lists_note explains they were not applied.

Examples

Step 1 — analyze

{
  "action": "analyze",
  "object_name": "contacts",
  "format": "json",
  "data": "[{\"first_name\":\"Alice\",\"last_name\":\"Martin\",\"email\":\"alice@example.com\"},{\"first_name\":\"Bob\",\"last_name\":\"Dupont\",\"email\":\"bob@example.com\"}]"
}

Step 3 — preview with one override (deduplicate on email)

{
  "action": "preview",
  "import_job_id": "job-uuid",
  "mapping": [
    { "column": "email", "action": "map", "field": "email" }
  ],
  "import_options": { "duplicate_strategy": "skip", "duplicate_fields": ["email"] }
}

Step 4 — execute (after user confirms)

{
  "action": "execute",
  "import_job_id": "job-uuid",
  "import_options": { "duplicate_strategy": "skip", "duplicate_fields": ["email"] }
}

Step 5 — poll a queued import

{
  "action": "status",
  "import_job_id": "job-uuid"
}

crm_find_activity

Consolidated activity for ONE record — interactions (every channel), tasks, and notes — in a single call. Prefer this over separate queries, and use it to show a contact/company's interactions (it never mixes contacts). Requires a specific record: pass object_name (plural, e.g. contacts/companies) and record_id — resolve the record first with crm_global_search if you don't have its id. For your own recent messages not tied to one record, use crm_inbox instead.

This tool has an attached MCP App: it renders a record-scoped Activity widget (interactions grouped by thread + tasks + notes, with channel filters, inline thread reading, and "new email" / "LinkedIn reply" compose) in clients that support MCP Apps — for any view (view only changes the text shape, never whether it displays).

Parameters

Behavior

• The record is resolved once (existence + RBAC visibility) and augmented with a display label.
• sections view returns each requested section as { items, total, has_more, next_cursor }, paginated independently via its own cursor.
• timeline view merges interactions, tasks, and notes into one chronological feed (newest first); each item carries a kind of interaction, task, or note, plus per-section counts.
• Items are normalized: interaction {id, channel, date, direction, subject, preview, participants, thread_id}, task {id, title, status, due_date, assignee, priority}, note {id, title, preview, author, date}.
• Interactions are only tracked on contacts and companies. On any other object the interactions section is returned as { available: false, reason }.
• Interaction preview follows the app visibility model: the thread owner sees their content; a non-owner is gated by the thread's content_visibility, so preview may be a masking placeholder. Non-owned private threads (LinkedIn/WhatsApp) are dropped entirely.

Examples

"Show me everything on this contact"

{
  "object_name": "contacts",
  "record_id": "uuid-contact"
}

"Give me one merged timeline for this company, emails only"

{
  "object_name": "companies",
  "record_id": "uuid-company",
  "view": "timeline",
  "channel": "email"
}

Paginate the tasks section

{
  "object_name": "contacts",
  "record_id": "uuid-contact",
  "include": ["tasks"],
  "tasks_cursor": "<next_cursor from a previous call>"
}

crm_find_events

List meeting events recorded in the CRM (meeting recorder + synced calendar meetings) within a date range. Read-only.

Parameters

Behavior

• Returns { events, total }, ordered by start time ascending.
• Row-level OBJECT_VISIBILITY is enforced.
• Heavy meeting columns (transcript text/segments, raw metadata, audio, content blocks) are omitted — you get titles, times, and status, not full transcripts.
• Invalid dates return INVALID_ARGUMENT. If the workspace has no meetings/calendar data, returns NOT_SUPPORTED.

Example

"List my meetings for June 2026"

{
  "start_date": "2026-06-01",
  "end_date": "2026-06-30"
}

crm_manage_lists

Manage multi-object lists (custom collections). Lists can contain records from different objects (contacts, companies, etc.).

Parameters

Behavior

• list returns all available lists for the current user (paginated).
• get returns a single list's record.
• get_entries returns the members of a list, ENRICHED: each entry carries { entry_id, record_id, object_type, record, entry_fields } where record is the target's display (name + image) and entry_fields are the per-entry custom field values — no need to chain crm_find_records.
• add accepts a single record_id or a batch via record_ids, validated against the list's allowed object types. Reports added, skipped_already_in_list, and any failed.
• remove accepts a single record_id or batch record_ids. Reports removed and not_in_list.
• update (rename / recolor / re-icon) and delete (drop the list — destructive and irreversible) both require an organization admin token.

Examples

"Add this contact to my priority list"

{
  "action": "add",
  "list_id": "uuid-priority-list",
  "object_type": "contacts",
  "record_id": "uuid-contact"
}

Batch-add several contacts

{
  "action": "add",
  "list_id": "uuid-priority-list",
  "object_type": "contacts",
  "record_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

List the enriched entries

{
  "action": "get_entries",
  "list_id": "uuid-priority-list",
  "limit": 50
}

Rename a list (admin)

{
  "action": "update",
  "list_id": "uuid-priority-list",
  "name": "Q3 Priority Accounts"
}