Clarify

Delete one or more custom fields from an existing object (built-in entities like person, company, deal, or custom objects like c_my_object). ## When to use this tool - When a user wants to remove custom fields they no longer need - When cleaning up unused or obsolete fields from any object ## Important - This is a destructive operation: deleted fields and their data cannot be recovered - Always confirm the deletion plan with the user before calling this tool - Protected (system) fields cannot be deleted - Relationship fields are deleted on both sides automatically

delete-fields

Delete a list (saved view) by its ID. ## When to use this tool - When the user asks to delete or remove a list they created ## Important notes - This action is permanent and cannot be undone - Default lists cannot be deleted - The last remaining list for an entity cannot be deleted

delete-list

Delete one or more records by their IDs. Supports bulk deletion of up to 25 records per call. ## When to use this tool - When the user asks to delete or remove specific records ## Important notes - This action is permanent and cannot be undone - All relationships involving the deleted records are also removed - Use only if you already have the IDs for the records - If you need to delete more than 25 records, call this tool multiple times with batches of up to 25.

delete-records

Search Clarify's built-in prospect database of companies and people to find new leads matching criteria like industry, location, headcount, job title, seniority, and funding stage, and save (publish) a search the user wants to keep. Use this for prospecting and lead discovery on any page where leads, prospects, or outbound targets are discussed. Under the hood, a search is created as a draft (or draft version) from a custom-dialect SQL query - follow the rules and examples below exactly. ## Modes: draft vs publish This tool has two modes, set by the `mode` parameter (default `draft`): - `draft`: run a SQL query to create a new draft search, or a draft refinement of an existing one, and preview the matches. This is the default and covers all prospecting and refinement. - `publish`: save an existing draft search so it appears under the user's "My saved searches". Call with `mode: "publish"`, the search's `search_id`, and (when the search has an unapplied refinement) its `version_id`. No `sql` is needed to publish. ## Draft vs saved searches A `draft` result is **not** a saved search: it doesn't appear under the user's "My saved searches" until it's published. Never tell the user a search you just created is "saved"; describe it as a draft. If the user asks whether it's saved, say it's a draft and offer to save it. When the user asks to save (or "publish") a search, call this tool again with `mode: "publish"` and the search's `search_id`. ## Interpreting the result count The number returned is an upper bound on matching rows in the prospect database. Some of those rows may already exist in the user's CRM and some may overlap with each other. The actual number of net-new importable records can be lower and is only known at import time. Never present the match count as "unique importable leads" or use it to estimate credit spend — use it only to describe how many rows match the filters. ## Important Rules - Parameters like version_id and search_id should preferably come from the document context, which is the source of truth for identifiers. If the document context does not include a version_id, you may use the most recent version_id from the conversation if it is contextually relevant. ## When to use this tool Use this tool when a user wants to find leads matching specific criteria and preview them as a draft search: - Construct a SQL query following the rules below - Provide a `search_label` parameter (e.g., "SF Companies with 50+ employees") - The tool creates a draft search or draft version that the user can see and interact with (see "Draft vs saved searches" above) ## When not to use this tool Do not call this tool when the user's intent is ambiguous between existing CRM data and new leads. When the user searches for companies or people without using the word "lead" or "prospect", and the conversation does not already establish context, you must ask the user to clarify before calling any tool. Ask whether they want to find new leads/prospects to add to the CRM, or look up existing companies/people already in the CRM. Only call this tool after the user confirms they want new leads. ## Versioning vs Creating Searches When the user wants to update/modify a search: 1. Always use the SQL from the referenced version as the base query and only modify what the user explicitly asks to change. 2. Keep the same entity type and update the SQL query and search_label Update (provide search_id) when user says: "no", "actually", "refine", "filter", "change", "update", "modify" or refers to "it"/"that search"/"the search" Create (omit search_id) when user explicitly asks for a "new search" or different entity type (company vs person) ## SQL Rules 1. Use ILIKE, all matching is case-insensitive. 2. Database may convert ILIKE `'%foo%'` into `'foo%'` pattern (prefix-only pattern matching) depending on field type (full text search vs keyword matching). Names are processed with prefix matching only. 3. No SELECT * — explicitly list all columns. 4. Always have the first column be the primary object field with the alias `table_name:__object__`. 5. Never select _id or id fields — they are not queryable. 6. Always prefix columns with table names: `tam_company.name`, not `name`. 7. Only select top-level columns — nested JSONB fields are not allowed in SELECT clauses. 8. All selected columns require aliases in the format "table_name:column_name". 9. For JSONB array fields (industries, domains, etc.), use this exact syntax to filter: `(table.field -> 'items') ?| ARRAY['Value1', 'Value2']` Do not use CONTAINS, the `@>` containment operator, or standard SQL array syntax - only the exact pattern above works. 10. Before applying filters to enum fields, review the allowed values listed in "Available Tables and Columns" and include all relevant matches in a single WHERE clause. 11. When filtering by role or title, prefer `job_title ILIKE '%keyword%'`; it matches the person's actual title and covers most queries (e.g., "founders", "CTOs", "account executives", "sales managers", "engineers"). The `seniority` and `function` fields are coarse categorical enums with very few values; only use them when the user's query maps exactly to an enum value and a broad categorical filter is clearly intended. 12. Never use `ILIKE ANY(ARRAY[...])` or `= ANY(ARRAY[...])` — ARRAY/ANY is not valid here. To match any of several title keywords, OR together separate `job_title ILIKE '%keyword%'` conditions; to match any of several exact enum values, use `IN (...)` on that column. 13. Never include `ORDER BY` in find-leads SQL. The TAM database returns errors when ORDER BY is present, even on sortable fields. If the user uses words like "recently", "latest", or "top", interpret them as filters (e.g. `latest_role_change_at >= '2026-01-01'`), not as a sort instruction. Never write `ORDER BY`, regardless of which column the user mentions. 14. If the user asks to sort or rank explicitly, explain that find-leads cannot sort results and offer to filter by date or another field instead. 15. NOT with JSONB array operators (?|) is unreliable and returns zero results. Use positive filters instead of negation (e.g., filter for the industries you want rather than excluding ones you don't). 16. Never use OR to group multiple `->>'key'` conditions — it corrupts parentheses around JSONB access. Instead, use `IN` on a single key. Correct: `WHERE table.primary_location->>'city' IN ('San Francisco', 'New York', 'Boston')` Incorrect: `WHERE (table.primary_location->>'city' = 'San Francisco' AND ...) OR (table.primary_location->>'city' = 'New York' AND ...)` This applies to all JSONB object fields (primary_location, company_location, name), not just locations. 17. Tech-stack / tooling criteria (e.g. "uses Kubernetes", "on PostgreSQL") are a COMPANY attribute: filter `tam_company.tech_stack_products` with the JSONB-array syntax `(tam_company.tech_stack_products -> 'items') ?| ARRAY['Kubernetes']`. Never filter tech stack via a person's `skills` field. Because queries are single-table (no JOINs), a tech-stack criterion means the query must target tam_company; you cannot filter tam_person by a company's tech stack. 18. Never filter on `smart_tags` — it is not a reliable structured filter. Map every criterion to a structured column (job_title, seniority, function, employee_range / company_employee_range, tech_stack_products, industries, primary_location). 19. Single-table queries only — JOINs are not supported. 20. When creating a new search, use the default query for the entity as the base and only add a WHERE clause. When refining an existing search, preserve the existing SELECT columns unless the user explicitly asks to add or remove columns. 21. Never filter by tam_person email fields (email_addresses, personal_email_addresses) in WHERE clauses — these fields are masked until leads are imported into the CRM, so filtering by them would produce unreliable results. You may still SELECT them for display. ## Company Name Matching The TAM database stores **parent company names**, not subsidiary or regional office names. When users provide subsidiary names (e.g., "Globex France S.A.R.L.", "Initech Solutions Japan K.K."), extract the core company name and use prefix matching: Correct: `tam_person.company_name LIKE 'Globex%'`: matches "Globex", "Globex Inc.", "Globex France S.A.R.L." Incorrect: `tam_person.company_name = 'Globex France S.A.R.L.'` — exact match will likely miss the record Incorrect: `tam_person.company_name IN ('Globex France S.A.R.L.', ...)` — exact subsidiary names rarely exist in the database When matching multiple companies, use OR with LIKE prefix patterns on the core name: ```sql WHERE ( tam_person.company_name LIKE 'Globex%' OR tam_person.company_name LIKE 'Initech%' OR tam_person.company_name LIKE 'Stark Industries%' ) ``` **Important**: Because only prefix matching is available, short company names (e.g., "Nova") may produce false positives (e.g., matching "Novartis"). Use the most distinctive prefix possible. If the user provides both a short name and a more specific variant, prefer the longer one (e.g., `'Nova Dynamics%'` over `'Nova%'`). ## Examples Follow the SQL patterns in these examples exactly. The lead finder database uses custom JSONB syntax that differs from standard SQL. Example: Find me companies in SF with > 50 people ```sql SELECT tam_company.name AS "tam_company:__object__", tam_company.domains AS "tam_company:domains", tam_company.employee_range AS "tam_company:employee_range", tam_company.industries AS "tam_company:industries", tam_company.description AS "tam_company:description", tam_company.primary_location AS "tam_company:primary_location" FROM tam_company WHERE tam_company.primary_location->>'city' = 'San Francisco' AND tam_company.primary_location->>'state' = 'California' AND tam_company.employee_range IN ('51-250', '251-1K', '1K-5K', '5K-10K', '10K-50K', '50K-100K', '100K+') ``` Example: Find me SaaS company leads in New York ```sql SELECT tam_company.name AS "tam_company:__object__", tam_company.domains AS "tam_company:domains", tam_company.employee_range AS "tam_company:employee_range", tam_company.industries AS "tam_company:industries", tam_company.description AS "tam_company:description", tam_company.primary_location AS "tam_company:primary_location", tam_company.website AS "tam_company:website" FROM tam_company WHERE tam_company.primary_location->>'city' = 'New York' AND tam_company.primary_location->>'state' = 'New York' AND (tam_company.industries -> 'items') ?| ARRAY['SaaS'] ``` Example: Find me people who work in sales at tech companies ```sql SELECT tam_person.name AS "tam_person:__object__", tam_person.email_addresses AS "tam_person:email_addresses", tam_person.job_title AS "tam_person:job_title", tam_person.company_name AS "tam_person:company_name", tam_person.company_industries AS "tam_person:company_industries", tam_person.primary_location AS "tam_person:primary_location", tam_person.seniority AS "tam_person:seniority" FROM tam_person WHERE tam_person.function = 'Sales & Business Development' AND (tam_person.company_industries -> 'items') ?| ARRAY['Software Development', 'Information Technology & Services'] ``` Example: Find me founders in San Francisco Note: "founder" is a specific title — use `job_title ILIKE`, not seniority. ```sql SELECT tam_person.name AS "tam_person:__object__", tam_person.email_addresses AS "tam_person:email_addresses", tam_person.job_title AS "tam_person:job_title", tam_person.company_name AS "tam_person:company_name", tam_person.primary_location AS "tam_person:primary_location", tam_person.seniority AS "tam_person:seniority" FROM tam_person WHERE tam_person.job_title ILIKE '%founder%' AND tam_person.primary_location->>'city' = 'San Francisco' AND tam_person.primary_location->>'state' = 'California' ``` Example: Find me companies in San Francisco, New York, and Boston ```sql SELECT tam_company.name AS "tam_company:__object__", tam_company.domains AS "tam_company:domains", tam_company.employee_range AS "tam_company:employee_range", tam_company.industries AS "tam_company:industries", tam_company.description AS "tam_company:description", tam_company.primary_location AS "tam_company:primary_location" FROM tam_company WHERE tam_company.primary_location->>'city' IN ('San Francisco', 'New York', 'Boston') ``` Example of filtering by `tam_person.company_employee_range`: ```sql SELECT tam_person.name AS "tam_person:__object__", tam_person.email_addresses AS "tam_person:email_addresses", tam_person.company_employee_range AS "tam_person:company_employee_range", tam_person.company_location AS "tam_person:company_location" FROM tam_person WHERE tam_person.company_employee_range IN ('51-250', '251-1K') ``` ## Importing or adding leads to the CRM If user asks to add or import leads to the CRM, use the `import-leads` tool and not the create-or-update-records tool.

find-leads

List an agent's runs, executions, invocations, and past run history, or fetch one run with its full transcript. Use this tool for any question about what an agent has done, when it ran, or how often it has fired. ## When to use this tool - "List runs for this agent" / "show me the agent's runs" - "Agent history" / "past runs" / "recent runs" / "last run" - "How many times has this agent run" / "count runs for an agent" - Debugging why an agent behaved a certain way: fetch the run to see the messages, tool calls, and responses that happened - The user provides an agent id and asks "show me what it did" ## Not the same as get-workflow-runs Agents and workflows both have runs but they live in different tables. Use this tool (not `get-workflow-runs`) whenever the subject is an agent or an agent id. Passing an agent id to `get-workflow-runs` silently returns nothing. ## How it works - Without `run_id`: returns a paginated list of recent runs for the agent - With `run_id`: returns the full run including its message transcript - A "run" is the chat session an agent produced when one of its triggers fired — user and assistant messages, tool calls, results, and errors ## Pagination - When the user asks for "more" runs / next page / older runs, call this tool again with the same agent_id and a larger `offset` ## Proactive debugging When the user reports that an agent isn't working as expected, proactively use this tool to fetch the most recent run transcript before suggesting changes. Compare what happened in the run against the agent's instructions to diagnose the root cause. After diagnosing, explain what you found with specifics from the transcript. Suggest targeted fixes via `create-or-update-agent`, then offer to rerun.

get-agent-runs

List agents visible to the current user, or fetch a single agent by ID. ## When to use this tool - When the user asks to see their agents or list available agents - When you need to look up an agent's instructions or configuration - When the user asks about a specific agent by name or ID ## How it works - Without agentId: returns all visible agents with description only - With agentId: returns the full agent details including complete instructions and configured triggers

get-agents

List the individual people enrolled in a campaign, with their per-person engagement — who opened, who clicked, who replied, and when. ## When to use this tool - Answer "who clicked", "who opened", "who replied", "who hasn't responded" - Build a follow-up or retarget audience from the people who engaged with a campaign - Check where a specific person is in a campaign, or why their run stopped Use `get-campaigns` instead when you need campaign-level totals and rates rather than the people behind them. Get the `campaign_id` from that tool first. 📖 **For campaign rules and examples**: Use read-context with context: "campaign-docs" ## Returns One entry per recipient: person name, email, person ID, delivery status, opened/clicked/replied flags, and the timestamp of their most recent open, click, and reply. ## Pagination - When the user asks for "more" results, use the EXACT same inputs and only change the offset parameter - The tool will tell you the next offset value to use ## Examples <example> { "campaign_id": "0195f2c1-...", "event": ["clicked"] } </example> <example> { "campaign_id": "0195f2c1-...", "status": "completed", "limit": 25 } </example>

get-campaign-recipients

List campaigns in the workspace, or fetch a single campaign by ID with full details. ## When to use this tool - Without campaign_id: discover existing campaigns, search by name, get campaign IDs - With campaign_id: read a campaign's full email content, inspect subjects/bodies/timing, check performance metrics, get details before duplicating with `create-campaign` 📖 **For comprehensive campaign rules and examples**: Use `read-context` with context: "campaign-docs" ## Returns **List mode** (no campaign_id): - Campaign name, ID, description, status, email step count, target list, created/updated info **Detail mode** (with campaign_id): - Full campaign details including all email steps with subjects, bodies (HTML with variables), and timing - Campaign-level performance: open rate, click-through rate, response rate, bounce rate - Per-email-step engagement: sent, opened, clicked, replied, bounced counts All engagement here is aggregate counts only. To find out *which people* opened, clicked, or replied — and when — use `get-campaign-recipients`. ## Pagination (list mode only) - When user asks for "more" results, use the EXACT same search inputs and only change the offset parameter - The tool will tell you the next offset value to use ## Duplicating a campaign To duplicate a campaign, call this tool with campaign_id first, then pass the returned email steps and settings to `create-campaign` with a new name like "Copy of <original>". Copy the `list_id` so the duplicate targets the same audience. Do NOT copy from_name. Let the new campaign use the current user's sender identity. If the original sender differs from the current user, also remove the original sender's personal sign-off from email bodies.

get-campaigns

Get information about the current authenticated user, including their timezone. ## When to use this tool Use this to understand who "me", "my", and "I" refer to in user queries. ## Important notes When interpreting relative dates (e.g., "last 2 weeks", "yesterday"): - Calculate dates in the user's timezone returned by this tool - Convert to UTC and ISO format for database queries

get-current-user

Get list metadata (saved views) for an entity type, or fetch a single list by ID. Only dynamic lists (membership driven by a SQL query) are returned. Legacy static and default lists are filtered out. ## When to use this tool - Without list_id: discover existing lists, search by name or description - With list_id: fetch full details for a specific list Supports case-insensitive substring search when no list_id is provided. ## Returns - List name (title) - Description - SQL query - Layout (table, board) ## Pagination - When user asks for "more" results, use the EXACT same search inputs and only change the offset parameter - The tool will tell you the next offset value to use (e.g., "Call this tool again with offset=25 to continue")

get-lists

Retrieve detailed information about specific records by their IDs. This tool provides comprehensive context about records, including relationships, AI summaries, and other details. Use this tool when you need to: - Understand the current state of specific records before answering questions or taking actions - Read meeting recording transcripts with full speaker attribution - Read email content, subject, body, and participants - Get rich context about records found via query-data Typical workflow: Use query-data to find record IDs, then pass them here for full details. Meeting-specific guidance: - For meeting: returns metadata, summary (AI-generated), notes (user-written), and associated recordings. If summary is null, check notes before concluding no content exists - For meeting_recording: returns the full transcript with speaker names and timestamps - When the user asks for exact quotes, verbatim wording, or "what exactly was said", fetch the meeting_recording transcript via get-records. The meeting summary is paraphrased and does not preserve the original words.

get-records

Get the schema for Clarify entities. ## When to use this tool Use the read format when working with SQL queries and the query-data tool. Use the write format when creating or updating records with the create-or-update-records tool. Pass the specific entities you need. Read defaults to the CRM database, and omitting entities returns every CRM entity, a large result that is re-sent on every later turn, so only omit it when you genuinely need the whole model. For lead columns (funding stage, employee range, industries, location), request the tam_company or tam_person entities to get the schema for the find-leads tool. The analytics event log schema comes with the query-analytics tool directly, so you do not need this tool for it. ## Databases Clarify has three databases: - CRM database (company, person, deal, meeting, user, task): your workspace data. Use with the query-data tool. Read returns these by default. - Leads database (tam_company, tam_person): prospecting data for finding new leads. Request these entities explicitly. Use with the find-leads tool. - Analytics database (ClickHouse, single `analytics.event` table): historical event log of every CRM change: point-in-time and change-history questions. Its schema comes with the query-analytics tool. ## Formats - read: schema for reading data via SQL queries with the query-data tool, or lead columns for the find-leads tool. Returns all columns, types (including JSONB structure), relationships, join tables, and custom fields. Defaults to CRM entities. - write: writable fields for the create-or-update-records tool. Returns fields that can be set when creating or updating records.

get-schema

Import leads from a tam_company or tam_person search into Clarify. ## Important Rules - Parameters like versionId and searchId should preferably come from the document context, which is the source of truth for identifiers. If the document context does not include a versionId, you may use the most recent versionId from the conversation if it is contextually relevant. - When a versionId is provided, the version will be applied to the search and the search will be published before starting the import - Always provide a descriptive searchTitle that reflects the current filters/query of the search (e.g., "SF Companies with 50+ employees") - Always provide a searchEmoji — a single emoji that represents the theme of the search (e.g., "🏢" for companies, "🌉" for SF-related searches) When the user asks to import leads without specifying a count: - For tam_company searches, import all leads without asking — company imports never consume credits regardless of size. - For tam_person searches with fewer than 100 leads, import them all without asking. - For tam_person searches with 100 or more leads, ask whether they want to import a small sample (e.g. 10) to test first or all leads from the search. Inform the user that importing people costs 1 credit(s) per net-new person, so importing all N people will cost up to N × 1 credits total. ## How charges work Credits are charged only for net-new tam_person records that get inserted. Records that already exist in the CRM are skipped by the system and never charged. tam_company imports are always free. When a batch returns 0 net-new records (all matches already exist in the CRM), nothing is charged. Never tell the user they have "burned credits on duplicates" or suggest a refund in that case; there is nothing to refund. Never explain internal decision logic, thresholds, or tool behavior to the user. For example, do not say things like "Since there are fewer than 100, I'll import them all." Just perform the action and describe what you did in user-friendly terms. ## Extra fields This tool can import any field from the TAM database — not just the core fields. When the user asks for additional data (e.g., "import with industries and tech stack", "I want ownership status too", "add seniority"), use the extraFields parameter. The import automatically creates CRM fields that don't exist yet and populates them with TAM data. Do not create fields manually — this tool handles it. This also works for records that already exist in the CRM. If the user wants to backfill a field (e.g., "add industries to my existing companies"), re-run the import with extraFields and the existing records will be updated with the new field values. Available extra fields for companies: alternative_names (Alternative names), website (Website), type (Type), industries (Industries), specialities (Specialities), workforce_headcount (Workforce headcount), summary (Summary), funding_last_round_type (Last funding round type), funding_last_round_amount_usd (Last funding round amount (USD)), funding_last_round_date (Last funding round date), investments (Investments), financing_profile_status (Financing status), financing_profile_ipo_date (IPO date), financing_profile_market_cap (Market cap), ownership_status (Ownership status), ownership_status_detailed (Ownership status (detailed)), stock_exchange (Stock exchange), customer_types (Customer types), tech_stack_products (Tech stack products), patent_count (Patent count), contact_info_email (Contact email), contact_info_phone (Contact phone), contact_info_url (Contact URL), identifiers_stock_ticker (Stock ticker), identifiers_naics_code (NAICS code), identifiers_duns_code (DUNS code), identifiers_cage_code (CAGE code), is_acquired (Is acquired), is_exited (Is exited), is_government (Is government), is_non_profit (Is non-profit), is_shut_down (Is shut down), is_stealth (Is stealth). Available extra fields for people: personal_email_addresses (Personal email addresses), headline (Headline), function (Function), seniority (Seniority), hiring (Hiring), open_to_work (Open to work), skills (Skills), smart_tags (Smart tags), investor_data_type (Investor type), investor_data_geo_focus (Investor geo focus), investor_data_industry_focus (Investor industry focus). If the user says "import all fields" or "include everything", pass all available field names for the entity type. If the user doesn't mention extra fields, omit the parameter.

import-leads

Merge two or more records into a single primary record in Clarify. All data from the source records (fields, relationships, list memberships, notes) will be merged into the primary record. Source records are deleted after merging.

merge-records

Execute read-only ClickHouse SQL against the analytics event log. ## When to use this tool Use `query-analytics` for **historical / point-in-time** questions about CRM records: anything that requires looking at the sequence of changes over time, not just the current state. Examples: - "What was the sequence of stage changes for this deal?" - "How long did this deal sit in 'In progress'?" - "What was the total amount of all deals in each stage on a specific date?" - "How many deals were created per day last week?" - "Who last edited this record, and when?" ## When NOT to use this tool For **current state** questions ("which deals are open?", "what's this company's domain?"), use the `query-data` tool: it queries PostgreSQL directly and is faster for live values. Only fall back to `query-analytics` when you need history. ## How it works - The query runs against ClickHouse, not PostgreSQL. Use ClickHouse SQL syntax (`JSONExtractString`, `toDate`, `argMax`, etc.). - When the user hasn't asked for a specific time frame, scope the query to the last 30 days with `AND timestamp >= now() - INTERVAL 30 DAY` to keep it fast and the results relevant. - Statements are read-only: INSERT / UPDATE / DELETE / DDL are rejected by ClickHouse. - Results are capped to the `maxResultRows` parameter (default 1024). Rows beyond the cap are dropped server-side, even if your SQL omits a `LIMIT`. # Analytics database (ClickHouse) Historical event log of every change to the CRM. **Read-only.** Use this with the `query-analytics` tool to answer point-in-time and change-history questions like: - "What was the sequence of events that led to the current stage of this deal?" - "How long did this deal sit in the 'In progress' stage?" - "How many deals were created per day last week?" ## Table: `analytics.event` Schema is inspired by PostHog: a single wide event table with a JSON-stringified `properties` payload column plus a structured `actor` column. Hot keys are promoted to materialized columns (see below); everything else is read with `JSONExtract*` against `properties`. - `_id` (String) — Event id - `workspace_slug` (String) — Workspace (tenant) slug - `entity_type` (String) — Subject type: `deal`, `company`, `person` - `entity_id` (String) — Subject record id - `type` (String) — Event type (see enum) - `timestamp` (DateTime64(6,'UTC')) — Event time; use `toDate(timestamp)` for day grouping - `properties` (String/JSON) — Object state at event time; read via `JSONExtract*` - `actor` (Tuple) — `actor._id`, `actor.anonymous_id`, `actor.entity`, `actor.source_id` (all String); usable in `GROUP BY`/`ORDER BY` - `m_stage` (String) — Materialized `JSONExtractString(properties,'stage')`; empty if absent - `m_amount` (Float64) — Materialized `JSONExtractFloat(properties,'amount')`; `0` if absent ## Sort key (write fast queries) The table is a `ReplacingMergeTree` ordered by `(workspace_slug, entity_type, entity_id, timestamp, _id)`. Queries are fastest when their `WHERE` clause matches this key from the left, so filter in that order — `workspace_slug` first, then `entity_type`, then `entity_id`, then `timestamp`: - Always include `workspace_slug = '<your workspace>'` — it's the leading sort-key column. Use the **Workspace** value from the current user context; if your context doesn't include it, call the `get-current-user` tool to get it before querying. - Always filter by `entity_type` when you can — it lets ClickHouse skip almost the entire table. Add `entity_id` too for single-record questions. - Add a `timestamp` range to narrow further (and bound open-ended history scans). - Filtering only by columns outside the sort key (`type`, `m_stage`, `m_amount`, or any `JSONExtract*` value) forces a full scan — pair them with the sort-key columns above whenever possible. ## Allowed `type` values - `CdcEventType` — `clarify:create`, `clarify:update`, `clarify:merge`, `clarify:delete`, `clarify:add-to-list`, `clarify:remove-from-list`, `clarify:set-relationship`, `clarify:unset-relationship`, `clarify:grant-access`, `clarify:update-access`, `clarify:revoke-access`, `clarify:meeting` ## Materialized columns A small set of frequently-used keys from `properties` are promoted to typed, indexed columns. **Prefer them over `JSONExtract*` when the key matches** — they're faster and skip a JSON parse per row. - `m_stage` (`String`) — `properties.stage` - `m_amount` (`Float64`) — `properties.amount` These are populated from whatever `properties.stage` / `properties.amount` happens to be on each row, regardless of `entity_type`. If a custom object also stores a `stage` or `amount` field, the materialized columns work for it too. Empty / `0` means the event simply didn't carry that key. For any other property key, fall back to `JSONExtractString(properties, '<key>')` / `JSONExtractFloat(properties, '<key>')` etc. ## Common patterns - **Single-record history is cheapest**: when the question is about one specific record, filter by `entity_type` AND `entity_id` together — this hits the sort key prefix and reads a tiny slice of the table. - **Read JSON fields**: prefer materialized columns when the key matches (`m_stage`, `m_amount` — see above). Otherwise use `JSONExtractString(properties, 'priority')`, `JSONExtractFloat(properties, 'mrr')`, etc. - **Latest properties per entity**: `argMax(properties, timestamp)` over a window grouped by `entity_id`. - **Time-in-stage queries**: take consecutive `clarify:update` rows ordered by `timestamp`, group by `entity_id`, then diff timestamps where the extracted stage transitions. - **Day grouping**: `SELECT toDate(timestamp) AS day, count() ... GROUP BY day`. - **Date literals**: prefer relative helpers — `now() - INTERVAL 1 MONTH`, `toStartOfMonth(now())`, `today() - 7` — over hardcoded literals, since you have no reliable wall clock and a hardcoded "this month" boundary will silently drift. When you must use an absolute literal, note that ClickHouse's implicit cast in comparisons like `timestamp >= '2026-04-01T00:00:00Z'` rejects ISO 8601 with `T`/`Z`. Three patterns work: (1) space-separated `'2026-04-01 00:00:00'`, (2) wrap explicitly `parseDateTime64BestEffort('2026-04-01T00:00:00Z')`, (3) explicit `CAST('2026-04-01T00:00:00Z' AS DateTime64(6, 'UTC'))`. - **Actor filter**: `actor._id`, `actor.entity`. Native JSON paths, no `JSONExtract` needed. ## Examples <example> -- Deals created per day in the last 7 days SELECT toDate(timestamp) AS day, count() AS created FROM analytics.event WHERE workspace_slug = '<your workspace>' AND entity_type = 'deal' AND type = 'clarify:create' AND timestamp >= now() - INTERVAL 7 DAY GROUP BY day ORDER BY day </example> <example> -- Sequence of stage changes for a single deal SELECT timestamp, m_stage AS stage, actor._id AS actor_id FROM analytics.event WHERE workspace_slug = '<your workspace>' AND entity_type = 'deal' AND entity_id = '<deal-id>' AND type IN ('clarify:create', 'clarify:update') ORDER BY timestamp </example> <example> -- Stage-change events grouped by day across all deals SELECT toDate(timestamp) AS day, count() AS stage_changes FROM analytics.event WHERE workspace_slug = '<your workspace>' AND entity_type = 'deal' AND type = 'clarify:update' AND m_stage != '' GROUP BY day ORDER BY day </example>

query-analytics

Execute PostgreSQL queries to retrieve data from Clarify. ## When to use this tool - Counting records (e.g., "How many deals are open?") - Aggregations (SUM, AVG, COUNT, MAX, MIN, GROUP BY) - List queries (e.g., "Show me 50 recent meetings") - Filtering by timestamps (e.g., deals created in Q4, meetings last week) - Searching/filtering large datasets (e.g., "Show all deals from Q4" or "Find records updated this week") ## For detailed record context, use get-records After finding record IDs with this tool, use get-records for: - Full record details, relationships, and AI summaries - Meeting recording transcripts with speaker attribution - Email content, subject, body, and participants - Example: query-data to find IDs, then get-records to read details ## When not to use this tool This tool queries existing CRM records. When users want to find new companies or people to add to the CRM (leads/prospects), search for the lead finder tools instead. - Do not use this tool when the user mentions "leads" or "prospects" and wants to source new contacts (e.g., by industry, location, employee count, job title). Search for the lead finder tools that query the lead database instead. - Still use this tool when the user mentions "leads" or "prospects" but the context clearly refers to existing CRM records (e.g., "leads in my pipeline", "prospects with last product activity in last 30 days"). Activity history, emails, meetings, and pipeline stages only exist for CRM records, not in the lead database. But the user is still asking about leads/prospects, so we still use this tool. - Ask the user to clarify when they search for companies or people without using the word "lead" or "prospect", and the conversation does not already establish a CRM context. Ask whether they want to find new leads/prospects to add to the CRM, or look up existing companies/people already in the CRM. If the conversation already establishes CRM context, use this tool without asking. ## Before writing SQL - This tool does not include any schema. Workspaces have custom fields and JSONB columns that vary per workspace, so you cannot know the column names without loading the schema first. Always call get-schema with format "read" and the entities you need before writing SQL, unless the schema for those entities was already returned by get-schema earlier in this conversation. - Call get-current-user if the query involves "me", "my", or "I", if the tool is available - Always prefix columns with table names (e.g., `person.name`, not `name`) - Use ILIKE for case-insensitive matching (not LIKE) - Query timestamps using UTC/ISO 8601 format (e.g., '2025-12-22T00:00:00Z') - Results will have timestamps formatted in the user's timezone for readability - For many-to-many relationships, use INNER JOIN with join tables ## Working with JSONB Columns Many columns store data as JSONB objects. Check the schema returned by get-schema to identify JSONB columns. Only use JSONB operators (->, ->>) on columns explicitly marked as "JSONB with format" in the schema. ### JSONB Access Operators - `->` - Extract JSON object (returns JSONB): `column->'key'` - `->>` - Extract text value (returns TEXT): `column->>'key'` - `jsonb_array_elements(column->'items')` - Iterate over JSONB arrays ### JSONB Column Patterns Object with nested fields (e.g., `JSONB with format {first_name: string, last_name: string}`): - Access nested field: `column->>'first_name'` - Concatenate fields: `CONCAT(column->>'first_name', ' ', column->>'last_name')` - Filter: `column->>'first_name' ILIKE '%john%'` Array of items (e.g., `JSONB with format {items: string[]}`): - Get first item: `column->'items'->>0` - Iterate items: `jsonb_array_elements(column->'items') as item` - Access nested in item: `(item->>'email')` ### Filtering multi-select and label arrays For columns with format `{items: string[]}` (multi-select enums, the built-in `labels` field, etc.), filter membership with the array-overlap operator `?|`: - Has any of: `(person.labels -> 'items') ?| ARRAY['BDR Prospect', 'ICP']` Do not use the `@>` containment operator or `CONTAINS`. `@>` works in the database, but a list built with it cannot be rendered or edited in the list UI; always use the `?|` pattern above. ### Checking if JSONB collection fields are empty For columns with format `{items: string[]}` (multi-select enums, email addresses, etc.), an empty field can be either NULL or `{"items": []}`. Always check for both: - Is empty: `(column IS NULL OR (column->'items') = '[]'::JSONB)` - Is not empty: `(column IS NOT NULL AND (column->'items') <> '[]'::JSONB)` Do not use only `IS NULL` or `IS NOT NULL` for these fields; that misses records with empty arrays. ## Time-Based Queries Use the current time from `get-current-user` tool or system context as reference. ### "Last" vs "Next" Terminology - "last meeting" = Most recent past meeting: `WHERE meeting.start < NOW() ORDER BY meeting.start DESC LIMIT 1` - "next meeting" = Soonest future meeting: `WHERE meeting.start > NOW() ORDER BY meeting.start ASC LIMIT 1` - "recent meetings" = Meetings in the past, not upcoming ones - "upcoming meetings" = Meetings in the future ### Time Period Interpretation When user mentions "Q4 2025", "last quarter", or similar: - Activity in that period: Filter by date: `WHERE meeting.start >= '2025-10-01' AND meeting.start < '2026-01-01'` - Content mentioning that period (e.g., "meetings where Q4 was discussed"): Search transcripts/summaries, not date filter ## User-Scoped Queries When querying data related to "me", "my", or "I": - Use the current user's ID to filter records - Remember: `user` and `person` are different tables - `user` = internal workspace members, `person` = external contacts - For meetings: `INNER JOIN user_meeting ON meeting._id = user_meeting.meeting_id WHERE user_meeting.user_id = '<user-id>'` - External meetings have attendees who are not workspace users. Check `person_meeting` but exclude persons whose email matches a user: `EXISTS (SELECT 1 FROM person_meeting pm JOIN person p ON p._id = pm.person_id WHERE pm.meeting_id = meeting._id AND NOT EXISTS (SELECT 1 FROM "user" u WHERE u.email IN (SELECT jsonb_array_elements_text(p.email_addresses->'items'))))` - Internal meetings have no truly external attendees (inverse of above) - For tasks: Filter by `assignee_id`: `WHERE task.assignee_id = '<user-id>'` - For deals: Filter by `owner_id`: `WHERE deal.owner_id = '<user-id>'` ## Deal Analytics ### Comparison operators for thresholds When users reference a threshold amount: - "above $300", "over $300", "at least $300": `deal.amount >= 300` - "below $500", "under $500": `deal.amount < 500` - "more than $300", "fewer than 5": use strict comparison (`>` / `<`) ### Time-bounded deal metrics When users ask about deals in a specific time period (e.g., "January deals", "Q4 closed deals", "deals closed this month"), always filter by `close_date` within that period in addition to any stage filter. Do not filter only by stage -- that returns all historically closed deals, not deals closed in the requested period. Only add a closed stage filter when the user is asking about closed or won deals specifically. Do not add a closed stage filter for queries about open or in-progress deals. - Example: "deals closed in January 2026" requires `deal.stage IN (<closed stages from schema>) AND deal.close_date >= '2026-01-01' AND deal.close_date < '2026-02-01'` - Example: "deals expected to close in Q1" should only filter by `close_date` without a closed stage constraint ## Association Queries When finding emails or meetings "related to" a company or entity, join through the relationship graph instead of searching message body text. - Emails related to a company: JOIN person_message with person WHERE person.company_id = <company_id>. Do not use raw_body ILIKE '%company name%' -- body text matching picks up incidental mentions and links unrelated contacts. - Meetings related to a company: JOIN person_meeting with person WHERE person.company_id = <company_id>. - Emails for a specific person: JOIN person_message WHERE person_message.person_id = <person_id>. - Only use body/subject text search when the user explicitly asks to search email content (e.g., "find emails mentioning Project X"). ## Activity Counting Activity includes: meetings, messages, tasks, and comments. To count activity: - Comments: Query `comment` table with `entity = '<entity-type>'` and `owner_id = <entity>._id`. Use `_created_at` as timestamp. - Meetings: Join through `person_meeting` join table. If entity relates to `person` via join table (e.g., `person_deal`) or foreign key (e.g., `person.company_id`), join: entity → person → `person_meeting` → `meeting`. Use `meeting.start` as timestamp. - Messages: Join through `person_message` join table. Same pattern as meetings: entity → person → `person_message` → `message`. Use `message.received_at` as timestamp. - Tasks: Join via foreign key `task.deal_id`. For deals: direct join. For companies: join `deal` first (via `deal.company_id`), then `task`. Use `task._created_at` as timestamp. Pattern: Create CTEs for each activity type, UNION ALL them, then LEFT JOIN to your entity table. Use COUNT() and MAX() for totals and last activity date. ## Comments Comments are notes left on records. The comment table has no schema in get-schema: use these columns directly: - `_id`: UUID primary key - `entity`: parent entity type (e.g., 'company', 'deal', 'person', 'meeting', 'task') - `owner_id`: parent record ID - `message`: JSONB rich text; use `message::text` for raw content - `_created_by`: user ID of the comment author. JOIN with `"user"` on `_created_by = "user"._id` for author name - `_created_at`: timestamp ## Existence Checking Before creating a record, search broadly by name to check if it already exists. Duplicate records with the same name but different IDs are common. - Use ILIKE name matching: WHERE deal.name ILIKE '%Snowplow%' or WHERE company.name ILIKE '%Snowplow%'. Do not rely solely on a single foreign key (e.g., WHERE deal.company_id = '<id>') -- this misses records linked to duplicate/variant company records. - When checking for existing deals, search by both the deal name and the related company name. ## Name search strategies When a name search returns no results, try variations before asking the user to clarify. Records are often stored differently than expected (e.g., "BrightLoop" vs "Bright Loop"): - Remove spaces: `ILIKE '%brightloop%'` - Search individual keywords: `name ILIKE '%bright%' OR name ILIKE '%loop%'` - If a broad search returns many results, pick the closest match rather than asking the user to choose Before matching a name column with ILIKE, check its type in the get-schema output. A name stored as a JSONB object (shown as `JSONB with format {...}`) is not text: a bare `name ILIKE` on it fails with `operator does not exist: jsonb ~~*`. This is common for the display name on people-type entities (for example a person or workspace user whose name is `{first_name, last_name}`). Extract the text first, e.g. `name->>'first_name' ILIKE '%...%'` or `CONCAT(name->>'first_name', ' ', name->>'last_name') ILIKE '%...%'` (see "Working with JSONB Columns" above). Only columns the schema marks scalar (e.g. a plain `string` email) work with a direct ILIKE. ## Meeting Recordings & Transcripts Meeting recordings are linked to meetings via meeting_recording.meeting_id. The meeting_recording table is queryable via SQL (use entity=meeting for the query): - Find recordings: SELECT meeting_recording._id FROM meeting_recording WHERE meeting_recording.meeting_id = '<meeting-id>' - Read transcript: use get-records with entity=meeting_recording and the recording IDs A meeting can have multiple recordings. To avoid duplicate rows, filter with an EXISTS subquery instead of JOINing meeting_recording directly: SELECT meeting._id, meeting.title FROM meeting WHERE EXISTS (SELECT 1 FROM meeting_recording WHERE meeting_recording.meeting_id = meeting._id) When listing or showing meetings (e.g., "show me my last 5 recorded meetings"): - Always include summary and/or notes in the SELECT columns, not just metadata (title, date, status) - Present the summary content inline so the user sees what each meeting was about - If summaries are available, offer to show full transcripts for any specific meeting When answering questions about a single meeting (summary, follow-up email, action items): - Check for recordings and read the transcript via get-records before responding When answering questions across multiple meetings: - Prefer using the summary and notes fields first (available on the meeting record) - Only read individual transcripts if the user explicitly asks or summaries are insufficient Meeting content fields: - "summary": AI-generated meeting summary (on meeting record) - "notes": User-written meeting notes (on meeting record, separate from summary) - If summary is null, check notes before concluding the meeting has no content A substring match inside a summary is not evidence that a topic was requested or discussed. Summaries often enumerate ABSENT topics ("No mention of dialers, enrichment, or reporting tools"), so an ILIKE '%dialer%' hit can be a negation. Before attributing a request or interest to a person or meeting from a summary match, read the matching summary text and confirm the term appears in an affirmative context. Do not count a negated mention as a positive signal, and do not report a corrected count as fact until you have re-read the source. ## Emails & Messages The message table contains sent and received emails. Use entity=message to query directly. Sensitive columns (raw_body, subject) are protected by database-level RLS; only messages the current user has access to will return content. Use get-records with entity=message for full formatted email content with participant details. Filter by user_id for the current user's emails, received_at for time ranges, and person_message join for specific contacts. Never claim you cannot access emails -- sent and received emails are queryable. Unsent drafts are not. ## Pagination - When user asks for "more" results, use the EXACT same SQL query and only change the offset parameter - The tool will tell you the next offset value to use (e.g., "Call this tool again with offset=25 to continue") ## Data Limitations Tables contain current field values only. You cannot determine what a field's value was at a past date with this tool. What you can answer: - Deals currently in stage X: `WHERE deal.stage = 'In progress'` - Deals created/updated in a period: `WHERE deal._created_at >= '2025-10-01'` - Deals closed in a period: `WHERE deal.stage IN (<closed stages from schema>) AND deal.close_date >= '2025-10-01' AND deal.close_date < '2025-11-01'` (see "Time-bounded deal metrics" above) What requires the query-analytics tool instead: - "How many deals were in stage X on December 1st?" (requires historical snapshots) - "What was the pipeline value entering Q4?" (requires reconstructing past state) - "Which deals changed stage last month?" (requires stage transition history) For historical or point-in-time questions like these (past field values, stage transitions, change history, trends over time), use the query-analytics tool. It queries the analytics event log of every CRM change and can reconstruct past state.

query-data

Read Clarify product knowledge and documentation. Use this whenever you need to understand a feature, apply best practices, or reference detailed technical documentation. Available contexts: - field-docs: Field type guidelines, AI prompt writing instructions, available relationship data, and examples for creating or updating custom fields - campaign-docs: Complete guide to email campaigns including structure, variables, enrollment, exit conditions, and best practices

read-context

Submit concise feature requests or feedback about MCP tools. Use when: - Missing functionality prevents completing a user's request - User requests a new feature or reports a limitation - User suggests improvements Keep feedback brief and focused on what's needed or what could be improved.

submit-feedback

Update an existing email campaign: rename it, change its target list, adjust the sender, edit its email steps, or configure send time windows. To create a new campaign, use the create-campaign tool instead. Requires a `campaign_id` (get it from the `get-campaigns` tool). 📖 **For comprehensive campaign rules and examples**: Use `read-context` with context: "campaign-docs" ## When to use this tool - When the user asks to rename a campaign, change its target list, adjust the sender, or edit email steps (subjects, bodies, timing) - When the user asks to configure when a campaign's emails can be sent (send time windows) ## Editing email steps Each email_step must specify an operation: - **update**: Modify an existing step (requires step_number, optional: subject, body) - **remove**: Delete a step (requires step_number) - **insert**: Add a new step (requires step_number, subject, body, delay_after_days) To append at the end, use step_number equal to the current number of steps + 1. ## Essential rules 1. **Email/Delay Pattern**: Emails and delays MUST alternate. When inserting an email, always specify `delay_after_days` 2. **First email**: `delay_after_days: 0`. Subsequent emails: minimum 1 day 3. **Campaigns are Workflows**: Use this tool for campaigns, not generic workflow tools 4. Campaign emails are templates sent to multiple people 5. Use variable placeholders: {{path||fallback}} with fallback, or {{path}} without fallback 6. Only use the variables listed below (do not invent variables) 7. Campaigns that have already been sent cannot be modified ## Threading: send_as_reply Set `send_as_reply: true` on a step to thread it as a reply under the previous step (uses the prior message id and "Re: <previous subject>"). Use it when a follow-up bumps the prior email and the recipient should see it inline: - **Use** `send_as_reply: true` for content like "circling back", "just bumping this", "wanted to follow up", or any step that explicitly references the prior email's call to action without a new pitch. - **Leave it off (default)** when the step introduces a new angle, case study, or call to action; recipients triage by subject, and a fresh subject signals fresh content. Rules: - Step 1 always starts a new thread (`send_as_reply` must be false / omitted). - When `send_as_reply: true`, the step's `subject` is ignored at send time (the previous step's subject is reused with "Re: " prepended), but you must still provide a sensible `subject` for storage. Fallback rules (fallbacks make emails feel natural when data is missing): - ALWAYS include fallbacks for human-identifiable information: → Person names (first_name, last_name, full_name) → use "there", "Friend", etc. → Company/organization names → use "your company", "your organization", "your team" → Job titles and roles → use "your role", etc. → Location/city names → use "your area", "your region", etc. - Skip fallbacks ONLY for technical/structured data: → URLs, email addresses, phone numbers → Dates, timestamps, IDs → Numerical values and metrics ## Examples <example> Update a campaign step: { "campaign_id": "abc-123-def", "email_steps": [ { "operation": "update", "step_number": 2, "subject": "Quick follow-up, {{person.name.first_name||there}}" } ] } </example> <example> Insert a new step: { "campaign_id": "abc-123-def", "email_steps": [ { "operation": "insert", "step_number": 2, "subject": "Quick check-in", "body": "<p>Hi {{person.name.first_name||there}},</p><p>Just wanted to follow up...</p>", "delay_after_days": 3 } ] } </example> ## Send Time Windows Use `send_windows` to control when campaign emails can be sent. Emails scheduled outside the configured windows are held until the next open window in the creator's timezone. - Pass `null` to disable windows (emails can be sent at any time). - Pass a `{ windows: { <day>: { start, end } | null } }` object to set windows. Days map to lowercase names: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. A `null` value for a day means no sending that day. `start` and `end` are 24-hour `"HH:mm"` strings with `start < end` (same-day windows only). - Omit `send_windows` entirely to leave existing windows unchanged. <example> Set business-hours-only send windows: { "campaign_id": "abc-123-def", "send_windows": { "windows": { "sunday": null, "monday": { "start": "09:00", "end": "17:00" }, "tuesday": { "start": "09:00", "end": "17:00" }, "wednesday": { "start": "09:00", "end": "17:00" }, "thursday": { "start": "09:00", "end": "17:00" }, "friday": { "start": "09:00", "end": "17:00" }, "saturday": null } } } </example> ## Important notes - delay_after_days: 0 = immediate, 3 = day 3, 7 = day 7 - Minimum 1 day enforced between consecutive emails automatically - Body should be formatted as HTML. Put each paragraph in its own <p> tag; paragraphs render with a blank line between them. Use <br/> only for a hard line break within a paragraph (e.g. between signature lines) - When describing timing to users, say "immediately" for delay_after_days = 0, "on day 3" for delay_after_days = 3 - Use get-campaigns tool to find campaign IDs for updates

update-campaign