Clarify

Add a comment to a supported entity.

Important notes

After adding a comment: 1. Tell the user what was commented on in a friendly, conversational way 2. Provide a clickable markdown link to open the entity (the tool response will include this) 3. Encourage the user to click the link to view the comment 4. Keep your response concise - the tool will provide the formatted link

Create a new list (saved view) based on a SQL query. Use this after running a SQL query to save the results as a reusable list that the user can access later. The SQL query should already be validated and working.

When to use this tool

Use this after running a SQL query to save the results as a reusable list that the user can access later.

Important notes

• SQL queries must use explicit column names (e.g., "SELECT name, email FROM person")
• SELECT * queries are not supported and will fail validation
• Column names must be table-qualified (e.g., "person.name" not just "name")
• The tool validates both the main query and count query to ensure the list will work when opened
• Aggregate functions in ORDER BY or HAVING must also be in the SELECT clause

After creating a list: 1. Tell the user what was created in a friendly, conversational way 2. Provide a clickable markdown link to open the list (the tool response will include this) 3. Encourage the user to click the link to view the list 4. Keep your response concise - the tool will provide the formatted link

Create a record in Clarify.

Get information about the current authenticated user, including their timezone and current local time.

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"):

• Use the approximate current time from this tool's output as the reference point
• Times are rounded to the nearest 10 minutes for cache coherency, so they are approximate
• Calculate dates in the user's timezone
• Convert to UTC and ISO format for database queries

Get list metadata (saved views) for an entity type. Lists are reusable SQL queries that users have saved.

Supports case-insensitive substring search - if a search query is provided, it will match against list titles and descriptions using case-insensitive substring matching.

When to use this tool

• Discover existing lists that might be useful for a user's query
• Understand what SQL queries users have already created
• Find lists by name or description

Returns

• List name (title)
• Description
• SQL query (if available)
• List type (dynamic, static, default)
• 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 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 create-record or update-record tools.

Formats

• read: To get full database schema for reading data via SQL queries with the query-data tool.

Returns all columns, types (including JSONB structure), relationships, join tables, and custom fields.

• write: To get writable fields for create-record or update-record tools.

Returns fields that can be set when creating or updating records.

Execute PostgreSQL queries to retrieve data from Clarify.

When to use this tool

Analytics mode

• Default
• 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")
• Historical analysis (stage transitions, field changes over time)
• Searching/filtering large datasets (e.g., "Show all deals from Q4" or "Find records updated this week")

Rich context mode

• Understanding context about a FEW specific records
• Answering questions that need full record details and relationships
• Reading meeting recording transcripts with full speaker attribution
• Example: "Tell me about deal XYZ" or "Show me details of the top 5 deals"

Working with JSONB Columns

Many columns store data as JSONB objects. Check the "Available Tables and Columns" section to identify JSONB columns.

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

Important notes

• Only use JSONB operators (->, ->>) on columns explicitly marked as "JSONB with format" in the schema. Regular string columns use standard SQL operators (ILIKE, =, etc.)
• 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

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

Before Writing SQL

• Review the "Available Tables and Columns" section for exact column names and types
• Call get-current-user if the query involves "me", "my", or "I", if the tool is available

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>'

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.

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

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.

Update a record by its ID in Clarify. This should be used only if you already have the ID for the record.