Clay

Add data points to companies in an existing search. Supports enriching ALL companies or specific companies via entityIds.

Quick Reference

• This tool: Enrich COMPANIES with funding, tech stack, headcount, etc.
• add-contact-data-points: Enrich CONTACTS with emails, phone numbers, work history, etc.
• Requires a taskId from a previous find-and-enrich-* tool call
• Use entityIds to enrich specific companies — do NOT create a new search to enrich one company from an existing search
• ANY research question about companies = call this tool with a Custom data point

IMPORTANT: When to Call This Tool

Call this tool whenever the user asks for ANY information about companies, including:

• Standard data points (tech stack, funding, headcount, etc.)
• Any open-ended research question — use Custom type for these

Do NOT try to answer company research questions from your own knowledge. ALWAYS call this tool to fetch the data.

Examples that MUST trigger this tool:

• "What's their tech stack?" → Standard type
• "Find recent product announcements" → Custom type
• "Get me their latest news" → Custom type
• "What's their revenue model?" → Custom type
• "Find their competitors" → Custom type
• "Any recent acquisitions?" → Custom type

Parameters

taskId (required)

The task ID returned from find-and-enrich-contacts-at-company or find-and-enrich-list-of-contacts.

• Do NOT fabricate a taskId—use the one from the prior search
• If no search exists yet, prompt the user to search first

dataPoints (required)

Array of data points to add.

• Standard: { type: "<DataPointType>" }
• Custom: { type: "Custom", customDataPoint: "<brief description>" }

Available standard types: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding

Custom type: Use for ANY research question not covered by standard types. Examples:

• "recent product announcements" → { type: "Custom", customDataPoint: "recent product announcements" }
• "B2B vs B2C classification" → { type: "Custom", customDataPoint: "B2B vs B2C classification" }
• "company founders" → { type: "Custom", customDataPoint: "company founders" }

entityIds (optional)

Array of entityIds to enrich. When omitted, enriches all companies in the search.

• Use the entityId values from the company data returned by a previous search tool call
• Useful when the user wants to enrich specific companies

Examples

| User request | dataPoints | |--------------|------------| | "What's their tech stack?" | [{ type: "Tech Stack" }] | | "Get funding info and headcount" | [{ type: "Latest Funding" }, { type: "Headcount" }] | | "Find recent product announcements" | [{ type: "Custom", customDataPoint: "recent product announcements" }] | | "Are they B2B or B2C?" | [{ type: "Custom", customDataPoint: "B2B vs B2C classification" }] | | "What's in the news about them?" | [{ type: "Custom", customDataPoint: "recent news and headlines" }] |

Response Behavior

• Confirm briefly: "Fetching [data point] for [company/companies]."
• For single-company requests, name the company instead of saying "all companies."

Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Add data points to contacts in an existing search. Supports enriching ALL contacts or specific contacts via entityIds.

Quick Reference

• This tool: Enrich CONTACTS with emails, phone numbers, work history, etc.
• add-company-data-points: Enrich COMPANIES with funding, tech stack, headcount, etc.
• Requires a taskId from a previous find-and-enrich-* tool call
• Use entityIds to enrich specific contacts — do NOT create a new search to enrich one person from an existing search
• ANY research question about contacts = call this tool with a Custom data point

IMPORTANT: When to Call This Tool

Call this tool whenever the user asks for ANY information about contacts, including:

• Standard data points (email, phone, work history, etc.)
• Any open-ended research question — use Custom type for these

Do NOT try to answer contact research questions from your own knowledge. ALWAYS call this tool to fetch the data.

Examples that MUST trigger this tool:

• "Get their emails" → Standard type
• "Find their recent publications" → Custom type
• "What have they posted on LinkedIn?" → Custom type
• "Summarize their career trajectory" → Custom type
• "Any recent job changes?" → Custom type
• "Score them against my ICP" → Custom type

Parameters

taskId (required)

The task ID returned from find-and-enrich-contacts-at-company or find-and-enrich-list-of-contacts.

• Do NOT fabricate a taskId—use the one from the prior search
• If no search exists yet, prompt the user to search first

dataPoints (required)

Array of data points to add.

• Standard: { type: "<DataPointType>" }
• Custom: { type: "Custom", customDataPoint: "<brief description>" }

Available standard types: Email, Summarize Work History, Find Thought Leadership

Custom type: Use for ANY research question not covered by standard types. Examples:

• "recent publications" → { type: "Custom", customDataPoint: "recent publications" }
• "LinkedIn activity" → { type: "Custom", customDataPoint: "recent LinkedIn posts" }
• "ICP fit score" → { type: "Custom", customDataPoint: "ICP fit score based on seniority and tenure" }

entityIds (optional)

Array of entityIds to enrich. When omitted, enriches all contacts in the search.

• Use the entityId values from the contact data returned by a previous search tool call
• Useful when the user wants to enrich specific contacts (e.g., "get John's email")

Examples

| User request | dataPoints | |--------------|------------| | "Get their emails" | [{ type: "Email" }] | | "Add phone numbers and work history" | [{ type: "Phone" }, { type: "Summarize Work History" }] | | "Find their recent publications" | [{ type: "Custom", customDataPoint: "recent publications" }] | | "What's their LinkedIn activity?" | [{ type: "Custom", customDataPoint: "recent LinkedIn posts" }] | | "Score them for senior leaders in NYC" | [{ type: "Custom", customDataPoint: "ICP fit: senior leader in NYC" }] | | "Get John's email" (single contact) | [{ type: "Email" }] + entityIds: ["<john's entityId>"] |

Response Behavior

• Confirm briefly: "Fetching [data point] for all contacts."
• For single-contact requests, name the contact instead of saying "all contacts."

Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Ask a natural language question about one or more accounts available in Clay Audiences. Depending on your workspace settings and whether Salesforce owner data is available, this may be limited to accounts you own in Salesforce. An AI agent analyzes account data including contacts, opportunities, Gong calls, and emails to answer your question.

IMPORTANT: Both "accountIds" and "question" parameters are REQUIRED — you must always provide both when calling this tool.

Quick Reference

• This tool: Ask questions or get analysis about specific accounts (e.g., "What's the status of this deal?", "Who are the key stakeholders?")
• get-my-accounts: Call this first to get account IDs before calling this tool, unless you already have account IDs. Find and list accessible accounts by name, industry, location, etc.
• find-and-enrich-company: Only for prospecting publicly available company info. Do NOT use find-and-enrich-company when the user is asking about their own accounts or deals—use this tool instead.
• For ambiguous queries (e.g., "Tell me about Acme"), call get-my-accounts first. If the account exists, use this tool. If not, fall back to find-and-enrich-company.

Prerequisites

You need the accountId (numeric) for each account you want to ask about. If you don't have it: 1. Call get-my-accounts to find accounts by name or other filters. Use onlyMine: true when the user asks about "my" accounts or accounts they personally own; omit it when they ask about accounts in general. 2. Use the accountId field from the results

Access to specific accounts depends on your workspace settings. Some workspaces allow questions about any account in the audience, while others restrict questions to accounts you own in Salesforce when Salesforce owner data is available.

Parameters

accountIds (required — MUST be provided)

Array of numeric account IDs from the get-my-accounts tool response. Supports 1-10 accounts.

• For single-account questions: provide one ID (e.g., [12345])
• For multi-account questions (e.g., comparisons): provide multiple IDs (e.g., [12345, 67890]). The tool returns individual analyses for each account — you should synthesize and compare the results yourself.

question (required — MUST be provided)

A natural language question about the account(s). Be specific for best results.

Correct Usage

You MUST always call this tool with BOTH parameters like this: { "accountIds": [12345], "question": "What is the deal status?" }

Examples

| User says | How to handle | |-----------|---------------| | "What's happening with the Acme deal?" | 1. Call get-my-accounts with filters: { companyName: "Acme" } to get accountId. 2. Call this tool with that accountId and the question. | | "What's happening with my Acme deal?" | 1. Call get-my-accounts with { onlyMine: true, filters: { companyName: "Acme" } } to get accountId. 2. If Clay says Salesforce owner data is unavailable, explain that "my accounts" filtering is not possible in this workspace and ask whether to search all audience accounts instead. 3. Otherwise call this tool with that accountId and the question. | | "Compare my top two accounts" | 1. Call get-my-accounts with { onlyMine: true } to find the accounts. 2. If owner-scoped filtering is unavailable, explain that Clay can still analyze audience accounts but cannot determine ownership in this workspace. 3. Otherwise call this tool with both accountIds and the question. The tool returns individual analyses per account — synthesize and compare the results yourself. | | "Who are the key contacts at account 12345?" | Call this tool directly with accountIds: [12345] and question: "Who are the key contacts?" (ID already known). |

Response Behavior

• Returns a detailed text answer from the AI agent based on each account's data
• The agent analyzes contacts, opportunities, Gong call transcripts, and emails
• For multi-account requests, individual analyses are returned per account — you are responsible for comparing or synthesizing the results
• This tool may take longer than other tools due to the depth of analysis

Find and enrich a single company by domain or LinkedIn URL.

Quick Reference

• This tool: Prospect and research PUBLICLY AVAILABLE company info (e.g., "Tell me about Stripe", "What's OpenAI's funding?"). This is for prospecting external data, NOT for querying the user's own account data.
• find-and-enrich-contacts-at-company: Find TYPES of people (e.g., "engineers at Stripe")
• find-and-enrich-list-of-contacts: Find SPECIFIC named people (e.g., "John Smith at Stripe")
• get-my-accounts + ask-question-about-accounts: Ask about the user's OWN accounts, deals, CRM data, or relationships (e.g., "What's happening with my Acme deal?", "How's our relationship with Stripe?")
• Do NOT use if user wants to find people—use the contact tools instead
• Do NOT use if user is asking about their own accounts, deals, opportunities, or CRM data—use get-my-accounts and ask-question-about-accounts instead
• For ambiguous queries about a company (e.g., "Tell me about Acme"), prefer checking get-my-accounts first. Only use this tool if the account is not found or the user is explicitly prospecting.

Parameters

companyIdentifier (required)

Domain (e.g., "stripe.com") or LinkedIn company URL. Company names alone will fail.

• Convert known companies: "Stripe" → "stripe.com"
• If ambiguous (e.g., "Delta"), ask the user to clarify

companyDataPoints (optional)

Enrich the company when creating a NEW search. For existing searches, use add-company-data-points instead.

⚠️ CRITICAL: NEVER add data points unless the user EXPLICITLY asks for them. Enrichments cost credits. Only include data points when the user's message specifically requests that data.

• "Tell me about Stripe" → NO data points
• "What's Stripe's funding?" → add Latest Funding (user explicitly asked)
• Do NOT add Headcount Growth, Recent News, or any other data point "to be helpful" — only what the user asked for

DataPoint format:

• Standard: { type: "<DataPointType>" }
• Custom: { type: "Custom", customDataPoint: "<brief description>" }

Important: Only include customDataPoint field when type is "Custom"

Available companyDataPoints: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding

Examples

| User request | Parameters | |--------------|------------| | "Tell me about Stripe" | companyIdentifier: "stripe.com" (NO companyDataPoints — user did not ask for enrichments) | | "What's OpenAI's funding?" | companyIdentifier: "openai.com", companyDataPoints: [{ type: "Latest Funding" }] | | "Canva's competitors and tech stack" | companyIdentifier: "canva.com", companyDataPoints: [{ type: "Company Competitors" }, { type: "Tech Stack" }] | | "Notion's product roadmap" | companyIdentifier: "notion.so", companyDataPoints: [{ type: "Custom", customDataPoint: "product roadmap" }] |

Response Behavior

• Summarize the company result briefly (e.g., "Found Stripe").
• The tool returns a taskId for use with add-company-data-points, custom functions, or get-task-context.

Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Search for contacts at a company by role, title, or department.

Quick Reference

• This tool: Find TYPES of people (e.g., "engineers at Stripe", "VPs at OpenAI")
• find-and-enrich-list-of-contacts: Find SPECIFIC named people (e.g., "John Smith at Stripe")
• Follow-ups: ALWAYS re-call this tool—never filter results in chat. When ambiguous, ask the user.

Parameters

companyIdentifier (required)

Domain (e.g., "stripe.com") or LinkedIn company URL. Company names alone will fail.

• Convert known companies: "Stripe" → "stripe.com"
• If ambiguous (e.g., "Delta"), ask the user to clarify

contactFilters (optional)

Narrow results. Only add filters the user explicitly requests.

Rules:

• Filters combine with AND; values within arrays combine with OR
• Keep compound titles as ONE string: "VP Finance" → ["VP Finance"], NOT ["VP", "Finance"]
• Use specific terms to avoid false matches:
• ✓ "Software Engineer" not "Engineer" (matches Sales Engineer, etc.)
• ✓ "Product Manager" not "Manager" (matches Account Manager, etc.)

Available filters: | Filter | Type | Description | |--------|------|-------------| | job_title_keywords | string[] | Titles to include | | job_title_exclude_keywords | string[] | Titles to exclude (e.g., ["Intern"]) | | profile_keywords | string[] | Keywords anywhere in the LinkedIn profile (headline, about, experience, etc.). Use for broad keyword searches, e.g. ["AI", "machine learning"] or ["founder", "co-founder"] | | certification_keywords | string[] | Certifications (e.g., ["AWS", "CPA"]) | | languages | string[] | Profile languages | | school_names | string[] | Schools attended | | current_role_min_months_since_start_date | number | Min months in role (tenured) | | current_role_max_months_since_start_date | number | Max months in role (new hires) | | locations | string[] | Locations to include (use formal names: "United States", "California") | | locations_exclude | string[] | Locations to exclude |

dataPoints (optional)

Enrich contacts/companies when creating a NEW search. For existing searches, use add-contact-data-points or add-company-data-points instead.

⚠️ CRITICAL: NEVER add data points unless the user EXPLICITLY asks for them. Enrichments cost credits. Only include data points when the user's message specifically requests that data.

• "Find engineers at Stripe" → NO data points
• "Find engineers at Stripe and get their emails" → add Email (user explicitly asked)
• "Tell me about OpenAI" → NO data points
• Do NOT add Headcount Growth, Recent News, or any other data point "to be helpful" — only what the user asked for

Structure: { contactDataPoints?: DataPoint[], companyDataPoints?: DataPoint[] }

DataPoint format:

• Standard: { type: "<DataPointType>" }
• Custom: { type: "Custom", customDataPoint: "<brief description>" }

Important: Only include customDataPoint field when type is "Custom"

Available contactDataPoints: Email, Summarize Work History, Find Thought Leadership

Available companyDataPoints: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding

Examples: | User request | dataPoints | |--------------|------------| | "engineers at Stripe" | NONE — user did not ask for enrichments | | "engineers at Stripe with emails" | { contactDataPoints: [{type: "Email"}] } | | "Canva's competitors and funding" | { companyDataPoints: [{type: "Company Competitors"}, {type: "Latest Funding"}] } | | "VPs at Figma with emails + company tech stack" | { contactDataPoints: [{type: "Email"}], companyDataPoints: [{type: "Tech Stack"}] } | | "Notion's product roadmap" (custom) | { companyDataPoints: [{type: "Custom", customDataPoint: "product roadmap"}] } |

Examples

| User says | Parameters | |-----------|------------| | "Find people at OpenAI" | companyIdentifier: "openai.com" | | "VP Finance at HubSpot" | companyIdentifier: "hubspot.com", contactFilters: { job_title_keywords: ["VP Finance"] } | | "VPs and Directors in California at HubSpot" | companyIdentifier: "hubspot.com", contactFilters: { job_title_keywords: ["VP", "Director"], locations: ["California"] } | | "Marketing managers outside the US at Salesforce" | companyIdentifier: "salesforce.com", contactFilters: { job_title_keywords: ["Marketing Manager"], locations_exclude: ["United States"] } | | "New hires at Stripe (last 3 months)" | companyIdentifier: "stripe.com", contactFilters: { current_role_max_months_since_start_date: 3 } | | "Find people mentioning AI at OpenAI" | companyIdentifier: "openai.com", contactFilters: { profile_keywords: ["AI", "artificial intelligence", "machine learning"] } | | "Find founders at YC companies" | companyIdentifier: "ycombinator.com", contactFilters: { profile_keywords: ["founder", "co-founder"] } |

Handling Follow-ups

ANY search modification requires re-calling this tool. Never filter in chat.

Interpret user intent:

• "also/too/as well" → ADD to existing filters
• "only/just" → NARROW within current context (e.g., "VPs only" after Finance search → "VP Finance")
• "actually/instead/switch" → REPLACE filters entirely
• When ambiguous, ask the user rather than guessing

Examples: 1. User: "Find SDRs at Verkada" → { job_title_keywords: ["SDR", "Sales Development"] } User: "Get AEs too" → ADD: { job_title_keywords: ["SDR", "Sales Development", "Account Executive"] }

2. User: "Find Finance people at Ramp" → { job_title_keywords: ["Finance"] } User: "Make it VPs only" → NARROW: { job_title_keywords: ["VP Finance"] }

3. User: "Find Finance people at Ramp" → { job_title_keywords: ["Finance"] } User: "Actually show me all VPs" → REPLACE: { job_title_keywords: ["VP"] }

Response Behavior

• Summarize the search briefly (e.g., "Found 20 engineers at OpenAI").
• The tool returns a taskId for use with add-contact-data-points, add-company-data-points, custom functions, or get-task-context.
• For emails/phones, use add-contact-data-points with the taskId.

Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Zero Results

Suggest broadening in order: 1. Remove or broaden title keywords (e.g., "Software Engineer" → "Engineer") 2. Remove location filter 3. Remove tenure filter 4. Verify company domain is correct

Find and enrich specific named contacts at their companies.

Quick Reference

• This tool: Find SPECIFIC named people (e.g., "John Smith at OpenAI", "Jane Doe at Stripe")
• find-and-enrich-contacts-at-company: Find TYPES of people (e.g., "engineers at Stripe")
• Do NOT use if user only provides company names without contact names
• Do NOT use to enrich contacts already in an existing search — use add-contact-data-points with entityIds instead

Parameters

contacts (required)

Array of { contactName, companyIdentifier } objects.

• contactName: Full name (e.g., "John Smith")
• companyIdentifier: Domain or company LinkedIn URL (NOT person LinkedIn URLs)
• Domains: "openai.com", "stripe.com"
• LinkedIn: "linkedin.com/company/openai"
• Company names: Convert if confident (e.g., "Stripe" → "stripe.com"), otherwise ask user

dataPoints (optional)

Enrich contacts/companies when creating a NEW search. For existing searches, use add-contact-data-points or add-company-data-points instead.

⚠️ CRITICAL: NEVER add data points unless the user EXPLICITLY asks for them. Enrichments cost credits. Only include data points when the user's message specifically requests that data.

• "Find engineers at Stripe" → NO data points
• "Find engineers at Stripe and get their emails" → add Email (user explicitly asked)
• "Tell me about OpenAI" → NO data points
• Do NOT add Headcount Growth, Recent News, or any other data point "to be helpful" — only what the user asked for

Structure: { contactDataPoints?: DataPoint[], companyDataPoints?: DataPoint[] }

DataPoint format:

• Standard: { type: "<DataPointType>" }
• Custom: { type: "Custom", customDataPoint: "<brief description>" }

Important: Only include customDataPoint field when type is "Custom"

Available contactDataPoints: Email, Summarize Work History, Find Thought Leadership

Available companyDataPoints: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding

Examples: | User request | dataPoints | |--------------|------------| | "engineers at Stripe" | NONE — user did not ask for enrichments | | "engineers at Stripe with emails" | { contactDataPoints: [{type: "Email"}] } | | "Canva's competitors and funding" | { companyDataPoints: [{type: "Company Competitors"}, {type: "Latest Funding"}] } | | "VPs at Figma with emails + company tech stack" | { contactDataPoints: [{type: "Email"}], companyDataPoints: [{type: "Tech Stack"}] } | | "Notion's product roadmap" (custom) | { companyDataPoints: [{type: "Custom", customDataPoint: "product roadmap"}] } |

Examples

| User request | contacts | |--------------|----------| | "Find John Smith at OpenAI" | [{ contactName: "John Smith", companyIdentifier: "openai.com" }] | | "Look up Jane Doe at Stripe and Bob Lee at Figma" | [{ contactName: "Jane Doe", companyIdentifier: "stripe.com" }, { contactName: "Bob Lee", companyIdentifier: "figma.com" }] |

Follow-ups

• "Add [name] at [company] too" → Re-call with ALL contacts (previous + new)
• "Actually look up [different people]" → Re-call with only the new contacts

Response Behavior

• Summarize the search briefly (e.g., "Found 20 engineers at OpenAI").
• The tool returns a taskId for use with add-contact-data-points, add-company-data-points, custom functions, or get-task-context.
• For emails/phones, use add-contact-data-points with the taskId.

Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Check if credits are available for the workspace. Returns hasWorkspaceCredits and hasPlatformCredits.

Retrieve an existing search by task ID. This tool retrieves the current state of search results including any enrichments that have completed since the search was created.

When to Use This Tool

This is a private tool, the chat and user are not exposed to it.

Parameters

taskId (required)

• The task ID identifying the search to retrieve. This should be a taskId that was returned from a previous find-and-enrich-contacts-at-company or find-and-enrich-list-of-contacts tool call.

Search your Salesforce accounts synced to Clay. Returns accounts you own in Salesforce, with optional filters. Optionally scope results to a specific Clay Audiences segment.

Quick Reference

• This tool: Search YOUR Salesforce accounts (accounts where you are the owner)
• Optionally scope to a named audience segment (e.g., "Enterprise", "ICP")
• Requires Salesforce User and Account syncs to be configured in Clay Audiences

Parameters

audienceName (optional)

Name of a Clay Audiences segment to scope results to. When provided, only accounts that belong to the named segment AND are owned by you will be returned. Use this when the user mentions a specific audience, segment, or list name. Omit when the user just wants to search across all of their accounts.

filters (optional)

Narrow results by account attributes. All filters combine with AND (and are also AND-ed with the audience segment filter if provided).

| Filter | Type | Description | |--------|------|-------------| | companyName | string | Partial match on account name (e.g., "Acme") | | domain | string | Exact domain match (e.g., "acme.com"). Use the full domain, not a partial string. | | industry | string | Partial match on industry (e.g., "Technology") | | location | string | Match on headquarters location. Be specific: use a city name (e.g., "San Francisco"), state (e.g., "California"), or country (e.g., "United States") — not a combination. | | headcountMin | number | Minimum number of employees (inclusive, >=) | | headcountMax | number | Maximum number of employees (inclusive, <=) |

limit (optional)

Number of results to return. Default: 50, max: 100.

offset (optional)

Number of results to skip for pagination. Default: 0.

Examples

| User says | Parameters | |-----------|------------| | "Show me my accounts" | {} | | "My tech accounts" | { filters: { industry: "Technology" } } | | "Accounts in California with 100+ employees" | { filters: { location: "California", headcountMin: 100 } } | | "Find my account Acme Corp" | { filters: { companyName: "Acme" } } | | "Find acme.com" | { filters: { domain: "acme.com" } } | | "Accounts in my Enterprise segment" | { audienceName: "Enterprise" } | | "ICP accounts in San Francisco" | { audienceName: "ICP", filters: { location: "San Francisco" } } | | "My accounts from the Mid-Market audience with 50+ employees" | { audienceName: "Mid-Market", filters: { headcountMin: 50 } } |

Response Behavior

• Summarize results concisely (e.g., "Found 15 accounts matching your filters")
• List key details: account name, industry, and location
• Each account includes an accountId (numeric) that can be passed to ask-question-about-accounts for deeper analysis
• If zero results, suggest broadening filters or checking that Salesforce sync is configured
• If an audience name was provided but not found, suggest checking the segment name in Clay Audiences

Get task status and results by task ID. This tool handles all task types (search, direct) and returns the current state.

When to Use This Tool

This is a private tool used by the widget for polling task status.

Parameters

taskId (required)

• The task ID to retrieve. Accepts:
• Universal task IDs: mcp-task-* (from run_subroutine_direct, etc.)
• Legacy search IDs: cgas-search-id-* (backwards compatible)

Retrieve the current state of a task — all entities, enrichment values, and statuses.

When to Use

Call this when you need the actual data behind an entity to answer the user's question — e.g. the user asks "what's John's email?" or "show me the enrichment results". The initial response from search/data-points tools includes a taskId for the generated task; call get-task-context to pull the latest entity and enrichment values when you actually need them.

Parameters

• taskId (required): Task ID from a previous tool call. Accepts mcp-task-* IDs and legacy cgas-* search IDs.

Response

Returns all entities and their enrichment values for the task. Each enrichment has a name, state ("completed" / "in-progress" / "error"), and value.

List available custom functions. Available functions: Find Linkedin From Email, [GTMOps] AI Account Enrichment, Find Email from LinkedIn Profile, Get Phone Number, Write a poem, Alex's LinkedIn URL to Clay Pitch Example, Kick off Outbound Flow, Riddle Demo, Enrich Person Test, Consolidate Portfolio Company Information. Call this to see their required inputs before using run_subroutine.

Query audience accounts, contacts, or deals using natural language. This tool translates your description into a structured filter, validates it against the database, and returns matching entities with their field values.

Parameters

query (required)

Describe what you're looking for in plain language. The tool automatically determines whether you're querying accounts, contacts, or deals.

audienceName (optional, string)

Name of a saved audience segment to scope results to. The query filter is applied within this segment.

onlyMine (optional, boolean)

When true, restrict results to accounts owned by the calling user in Salesforce. Only applies when the query targets accounts.

limit (optional, default 50, max 100)

Max number of rows returned. Keep below 100 to stay LLM-context friendly.

offset (optional, default 0)

Pagination offset. Increment by limit to fetch additional pages.

Response

{ entityType, explanation, totalMatched, accounts | contacts }

• entityType: The detected entity type (ACCOUNT or CONTACT)
• explanation: Human-readable summary of the applied filter
• totalMatched: Total entities matching the filter
• Each entity carries its entityId, externalRecordId, and fields (keyed by display name) with values

Examples

| User says | query parameter | |-----------|----------------| | "Show me my healthcare accounts" | "healthcare accounts" (+ onlyMine: true) | | "Find contacts whose title is VP Engineering" | "contacts with title VP Engineering" | | "Accounts with open opportunities over $100k" | "accounts with opportunities over $100k" | | "VPs at tech companies with 500+ employees" | "VPs at tech companies with 500+ employees" | | "Healthcare accounts in my Enterprise Target list" | "healthcare accounts" (+ audienceName: "Enterprise Target") |

Notes

• No need to discover field IDs first — this tool handles field discovery internally
• If the filter cannot be constructed from your description, a descriptive error is returned
• For deep analysis of specific accounts (contacts, emails, calls), use ask-question-about-accounts with the account IDs from this tool's results

Execute a function on contacts/companies FROM AN EXISTING SEARCH (Find Linkedin From Email, [GTMOps] AI Account Enrichment, Find Email from LinkedIn Profile, Get Phone Number, Write a poem, Alex's LinkedIn URL to Clay Pitch Example, Kick off Outbound Flow, Riddle Demo, Enrich Person Test, Consolidate Portfolio Company Information).

STOP! Choose the right tool:

• User gave you specific values (LinkedIn URL, name, email)? → Use run_subroutine_direct instead!
• User wants to run on contacts from a previous search? → Use THIS tool (run_subroutine)

Usage (only if you have a taskId from a previous search)

• Single contact: pass taskId + entityIds + fieldMapping
• All contacts: pass taskId + fieldMapping

fieldMapping format

Format: { "entityField": "subroutineInput" }

• KEY = entity field name (from contact data, e.g. "name", "url", "domain")
• VALUE = subroutine input name (from list_subroutines, e.g. "full_name", "linkedin_url")

Example: {"name": "full_name", "url": "linkedin_url", "domain": "company_domain"}

IMPORTANT

Do NOT try to generate or summarize the function results yourself from your own knowledge. Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Execute a custom function directly with provided inputs. NO existing task or entityIds needed.

When to Use This Tool

Use this tool when the user provides specific input values (like a LinkedIn URL, name, email, etc.) and wants to run a function on that data directly. This is the PREFERRED tool when the user gives you concrete values to work with.

When NOT to Use This Tool

Do NOT use this tool if you need to run on contacts from an existing search. Use run_subroutine instead for batch operations on search results.

Usage

Just provide:

• subroutine_id: from list_subroutines
• inputs: the actual values (e.g., {"Linkedin URL": "https://linkedin.com/in/someone", "Full name": "John Doe"})

IMPORTANT

Do NOT try to generate or summarize the function results yourself from your own knowledge.

• Just confirm briefly that the function is running.

Clay may render results in a widget in web chat hosts such as ChatGPT or claude.ai. Terminal/coding-agent hosts such as Codex, Claude Code, Cursor, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.

• If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
• In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
• Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
• If get-task-context is not available, fall back to get-task.

Response Behavior

Confirm briefly: "Running [function name]—results will appear shortly."

Run a custom subroutine on search entities. The backend automatically generates the field mapping.

Track an analytics event with optional properties.