How to connect Clay MCP with Python

Search for contacts at a company by role, title, name, or department. ## Quick Reference - **This tool**: Find TYPES of people (e.g., "engineers at Stripe", "VPs at OpenAI") or search by name (e.g., "someone named Urmanov at Allstate") - **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 | |--------|------|-------------| | names | string[] | Search by name — can be first name, last name, or full name (e.g., ["Smith"], ["John Smith"]) | | 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"] } | | "Find someone named Urmanov at Allstate" | companyIdentifier: "allstate.com", contactFilters: { names: ["Urmanov"] } | ## 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, use add-contact-data-points with the taskId. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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**: First name, last name, or full name (e.g., "John", "Smith", or "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, use add-contact-data-points with the taskId. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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.

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") - **query-objects** + **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 query-objects and ask-question-about-accounts instead - For ambiguous queries about a company (e.g., "Tell me about Acme"), prefer checking query-objects 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 hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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, 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 **Check before enriching:** If the user asks about a specific contact's data (e.g. "what's Patrick's email?"), call get-task-context FIRST — the user may have already enriched it through the widget. Only call this tool if get-task-context shows the enrichment hasn't been run. Call this tool whenever the user asks to FETCH or ADD new information about contacts, including: - Standard data points (email, 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 or get-task-context 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 work history" | [{ 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 hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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 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, 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 **Check before enriching:** If the user asks about a specific company's data (e.g. "what's their tech stack?"), call get-task-context FIRST — the user may have already enriched it through the widget. Only call this tool if get-task-context shows the enrichment hasn't been run. Call this tool whenever the user asks to FETCH or ADD new 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 or get-task-context 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-company, 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 hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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, hasSalesRepCredits, (when credit budgets are enabled) hasBudgetCredits, and exhaustedMessage when one of them is exhausted.

Report which Clay workspace this connection is pinned to. Returns workspaceName, workspaceId, and workspaceUrl. Use when the user asks which workspace they are connected to, or to confirm where searches and enrichments will run.

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) **page** (optional) - For direct tasks: 1-based page of entities (100 per page). Defaults to 1. The response includes totalEntities, hasMore, and overall completion status so callers don't need every entity to know the task state. isComplete means every entity finished (completed or errored), not that all succeeded.

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?", "what X profiles did you get?", "show me the enrichment results", or any question about data that may have been enriched. The initial response from search/data-points tools only includes base fields (name, title, company, LinkedIn); ALL enrichment values (emails, X/Twitter profiles, work history, custom data points) are only available through this tool. **IMPORTANT:** If the user asks about a data type and you don't see it in the initial search response, that does NOT mean it wasn't found — it means you need to call this tool to check. ## Parameters - taskId (required): Task ID from a previous tool call. Accepts mcp-task-* IDs and legacy cgas-* search IDs. - entityIds (optional): Return only these entities. - page (optional): For direct tasks (run_subroutine_direct), a 1-based page of entities — up to 100 per page. Defaults to 1. Ignored when entityIds is provided. ## Response Returns entities and their enrichment values for the task. Each enrichment has a name, state ("completed" / "in-progress" / "error"), and value. Direct tasks are paginated: the response includes page, pageSize, totalEntities, and hasMore, plus processedEntities/isComplete for overall progress. isComplete means every entity finished (completed or errored), not that all succeeded. When hasMore is true, call again with the next page to retrieve more entities — or pass entityIds to fetch specific ones.

Track an analytics event with optional properties.

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

Fetch the available dropdown options for a subroutine input that has a configured options source.

List available functions. Available functions: Company Address, Company Domain, Company Employee Count, Company Industry, Enrich Company, Company News, Company Latest Funding, Company Revenue (Exact), Company Job Openings, Person Full Name, Enrich Person, Find People at Company, Mobile Phone Number, Enrich Person and Find Contact Details, Person Location, Website Technology Stack, Person Job Title, Website Traffic, Work Email. Call this to see their required inputs before using run_subroutine.

Execute a function on contacts/companies FROM AN EXISTING SEARCH (Company Address, Company Domain, Company Employee Count, Company Industry, Enrich Company, Company News, Company Latest Funding, Company Revenue (Exact), Company Job Openings, Person Full Name, Enrich Person, Find People at Company, Mobile Phone Number, Enrich Person and Find Contact Details, Person Location, Website Technology Stack, Person Job Title, Website Traffic, Work Email). ## STOP! Choose the right tool: - User gave you specific values (LinkedIn URL, name, email) and no previous search is involved? → Use run_subroutine_direct instead! - User wants to run on contacts from a previous search? → Use THIS tool (run_subroutine). A user-supplied value that is the same for every contact (an account ID, a campaign name) goes in `inputs`; a value that differs per contact (email, name, LinkedIn URL) comes from `fieldMapping` ## 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 hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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 on one or more sets of 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, or a list of domains) 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 — for one value or many. ## 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 Provide: - subroutine_id: from list_subroutines - inputs: an ARRAY of input objects, one per run. Each object's keys must match the input names from list_subroutines. Use a single-element array to run once. Example (one): [{"Linkedin URL": "https://linkedin.com/in/someone"}] Example (many): [{"Domain": "clay.com"}, {"Domain": "google.com"}] ## IMPORTANT Each input set consumes credits (N sets = N runs). Do NOT try to generate or summarize the function results yourself from your own knowledge. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, 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. - **NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context.** The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context. - **When the user asks about a specific value** (e.g. "what's Patrick's email?", "what X profiles did you get?"), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn't been run yet. - 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."

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?") - **query-objects**: Call this first to get account entity IDs before calling this tool, unless you already have account IDs. Find and list accessible accounts by natural-language filters. - **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 query-objects 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 `query-objects` to find accounts by name or other natural-language 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 returned account `entityId` values as `accountIds` 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 returned account `entityId` values in the `query-objects` 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 `query-objects` with query: "Acme account" to get the account entityId. 2. Call this tool with that entityId in accountIds and the question. | | "What's happening with my Acme deal?" | 1. Call `query-objects` with query: "Acme account" and onlyMine: true to get the account entityId. 2. If Clay says owner-scoped filtering is unavailable, explain that Clay can still search audience accounts but cannot determine ownership in this workspace. 3. Otherwise call this tool with that entityId in accountIds and the question. | | "Compare my top two accounts" | 1. Call `query-objects` with query: "my accounts" and onlyMine: true to find 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 entityIds in 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

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