FirstTouch

Execute the primary action for a todo task. For call tasks, log the call; for manual tasks, mark the task done. For section_approval tasks, resolve every grouped action as approved or skipped: call preview_task immediately before this tool, copy task.payload.task_hash into taskHash, and submit exactly one decision for every id in actionGroup.expectedActionIds. Do not call when readiness.canExecute=false.

complete_task

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Creates an unlinked FirstTouch audience from supplied contacts, a connected HubSpot list, or a Sales Navigator search/list. Manual mode saves supplied contacts; hubspot_list schedules background synchronization; sales_navigator starts a background import using the selected LinkedIn account. This tool does not attach the audience to a Flow Plan, publish a flow, enroll contacts, or execute flow steps. Use attach_audience_to_flow as a separate call when the user wants to link the created audience to a flow. Read get_guide with topic=audience_management before creating an audience.

create_audience

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Create a manual audience from already fetched persisted prospect ids, for example selected prospectId values returned by enrichment/discovery tools. For a contact-discovery workflow, call get_guide with topic=contact_discovery first. Does not continue search and does not charge discovery credits.

create_audience_from_profiles

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Create a new sequence for exactly one contact with its first action and start processing it immediately. This is not a draft-only operation: an eligible action can execute when approval and scheduling permit. Always creates a new enrollment; never appends to an existing enrollment. Use add_contact_action with enrollmentId when continuing a sequence. For multiple requested steps, call this tool once for the first action, then add_contact_action once per later step with the returned enrollmentId. A new email sequence uses new_thread and requires a final subject. The first email and LinkedIn actions establish the enrollment-wide inbox and LinkedIn sender. Use another sequence when the customer requests a different sender. Read get_guide with topic=workflow_selection before choosing this workflow, then topic=dynamic_actions before writing. First call get_current_user and require authenticated access and granted flow:write for the active team. Use find_contact_data with every known identity unless verified enrichment was already returned in this conversation, then find_mcp_enrollment to resolve sequence continuity. Provide final content using exactly one typed action. Approval defaults to enabled; action.isHumanApprovalRequired=false is allowed only when the customer explicitly requests it. Actions may send messages, consume FirstTouch credits, or create user tasks. Execution follows approval, delay, branch, account readiness, and sender capability checks. Use the returned enrollmentId with enrollment inspection and cancellation tools; flowPlanId is not permission to modify the shared flow structure.

create_contact_sequence

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Create a reusable Flow Plan draft to manage a group as one unit with common settings and action structure, including personalized messages. This tool only saves configuration; it does not attach an audience, publish, enroll contacts, or execute the configured steps. Use attach_audience_to_flow and manage_flow_publication as separate calls when authorized. Before choosing this tool or the contact sequence tools, read get_guide with topic=workflow_selection first. If a reusable Flow Plan is selected, read get_guide with topic=flow_plan_creation before calling this tool.

create_flow_plan

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Read get_guide with topic=social_engagement before using this tool; reuse it if already read for the current request. Creates a named Social Engagement signal, its own draft Flow Plan, and zero or more monitored LinkedIn profiles/company pages. Requires team admin access and paid or trial access. The signal's tracking mode applies to all its profiles and cannot be changed. Collection starts asynchronously when eligible and can consume FirstTouch credits, even while the linked flow is draft; loadHistory can also consume credits. Each seat allows five nondeleted monitors across the team, including paused monitors. The generated flow starts in draft with manual enrollment; creation does not publish it, enroll contacts, or send outreach. Return signalId and flowPlanId for subsequent monitoring and flow configuration. This operation is not idempotent; inspect existing signals before retrying an uncertain result.

create_social_engagement_signal

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Read get_guide with topic=social_engagement before using this tool; reuse it if already read for the current request. Pauses one Social Engagement monitored profile using request.profileId from list_social_engagement_monitored_profiles. Requires team admin access. Retains its subscription and history; paused monitors still count toward capacity. Returns its owning signal and linked Flow Plan. Other profiles and existing enrollments/actions continue.

deactivate_social_engagement_monitored_profile

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Delete an existing audience. Before calling this tool, warn the user that deletion cannot be undone. Ask whether to cancel awaiting enrollments and whether to cancel enrollments already in progress if the user did not explicitly specify each choice. Both options default to true only after the user has been asked.

delete_audience

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Permanently remove an existing flow plan. This tool cannot delete the MCP Dynamic Actions or HubSpot Custom Actions flow plans because they are system-managed. Before calling this tool, warn the user and obtain explicit confirmation: all enrollments in the flow will be canceled, the flow plan cannot be restored, and its audience will continue to exist.

delete_flow_plan

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Read get_guide with topic=social_engagement before using this tool; reuse it if already read for the current request. Removes one monitored profile subscription using request.profileId from list_social_engagement_monitored_profiles. Requires team admin access. This matches Remove for a profile in the UI. Stops future collection for this subscription and retains captured history; retained history may no longer be accessible through this subscription. The owning signal and Flow Plan are retained. Use deactivate_social_engagement_monitored_profile to pause instead. Other profiles and existing enrollments/actions continue.

delete_social_engagement_monitored_profile

CHARGED TOOL. Call get_guide with topic=contact_discovery before this tool. Each generated Boolean filter expression must be at most 255 characters, including spaces, quotes, operators, parentheses, and exclusion prefixes; inclusion/exclusion values for the same field share this budget. Role-title filters use exact matches; multiple values in the same title array match any listed value (OR). Include the requested title plus up to 5 equivalent variants when available and within this limit, prioritizing requested titles and preserving role and seniority, unless the user requests only specific exact titles. Reduce optional variants or split inclusion searches within the approved credit budget if needed; preserve other filters and never silently drop requested criteria. Load one contact discovery page and return nextSteps for audience creation, pagination, background import, flow attachment, or enrollment. For general discovery, suggest pageSize=1 first to return totalResultCount plus a preview contact. After a preview or prior page, use returned nextPage as nextToken and request only additional rows; do not restart the same search without nextToken. Reserves pageSize credits and charges 1 credit per returned profile row, up to 10 rows per call.

discover_contacts

Edit one grouped action inside a todo section-approval task. Use preview_task first; use branchContext to distinguish Dynamic Actions paths and only send fields listed in actionGroup.actions[].editableFields.

edit_task_action

CHARGED TOOL. Find enriched company data by domain, website URL, or LinkedIn company URL. This consumes FirstTouch company enrichment credits. The enrichment result is not automatically applied or synchronized to any existing enrollment, Awaiting candidate, audience, HubSpot record, or saved prospect record. Tell the customer that nothing was injected automatically; a separate customer-requested write action is required to use the data elsewhere.

enrich_company

Enrich one identified person's professional profile for a business-related request. Returns available name, professional description, work experience, education, and languages. Fields may be missing. Provide linkedInUrl, work email, or firstName, lastName, and companyDomain. Costs 1 FirstTouch credit for a successful profile unlock; data already unlocked by the current team is not charged again. The result is not automatically applied or synchronized to any existing enrollment, Awaiting candidate, audience, HubSpot record, or saved prospect record. Tell the customer that nothing was injected automatically; a separate customer-requested write is required to apply the data elsewhere.

enrich_contact

Find one identified person's work email address for business communication. Provide linkedInUrl, or firstName, lastName, and companyDomain. Returns the available work email and catch-all status; a LinkedIn-based lookup may also return the matched professional profile. A lookup may return no match. Costs 2 FirstTouch credits for a successful email unlock; data already unlocked by the current team is not charged again. The result is not automatically applied or synchronized to any existing enrollment, Awaiting candidate, audience, HubSpot record, or saved prospect record. Tell the customer that nothing was injected automatically; a separate customer-requested write is required to apply the data elsewhere.

enrich_email

Find one identified person's work phone number for business communication. Provide linkedInUrl, or companyDomain with firstName or work email. Include lastName when known. Returns the available phone number, or no match when no number is found. Costs 7 FirstTouch credits for a successful phone unlock; data already unlocked by the current team is not charged again. The result is not automatically applied or synchronized to any existing enrollment, Awaiting candidate, audience, HubSpot record, or saved prospect record. Tell the customer that nothing was injected automatically; a separate customer-requested write is required to apply the data elsewhere.

enrich_phone

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Enroll awaiting items from an attached published flow source. Use this when the user names an existing flow and wants already-awaiting contact(s) or signal(s) started in that plan. First call get_flow_workspace for the flow, then pass awaiting.items[].candidate_id values; ids look like enrollment_candidate_*.

enroll_awaiting_flow_items

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Call get_guide with topic=contact_identity for matching, identifier, conflict, trace, enrichment, and persistence guidance. Find free existing contact data for the current team from saved FirstTouch contacts, enrollments, awaiting Flow Plan candidates, and audience contacts. Saved-contact matches identify existing prospects but may not return stored email, LinkedIn, or phone fields; enrollment, awaiting-candidate, and audience matches can return stored channel data when available. Use when the user names a contact or provides partial identity. Send every identity detail already known (for example firstName and lastName alongside email or linkedInUrl): exact identifiers are preferred, while the other details provide fallback matching. This does not enrich, spend credits, or create enrollments. Duplicate contact data across sources is collapsed. For action workflows, a customer-supplied exact email, LinkedIn URL, or phone is a constraint; do not replace it with candidate data unless the customer confirms the final action target.

find_contact_data

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Call get_guide with topic=dynamic_actions for the complete one-contact workflow. Find existing MCP Dynamic Actions enrollments for one contact, including completed or canceled history, so the MCP client can resolve whether the requested action continues the current conversational sequence or starts fresh outreach. If no candidate is returned and the requested action has all required identity and target data, create the new action without asking the customer to confirm the same request again. When candidates are returned, reuse the exact enrollmentId for a related step in an enrollment created or selected earlier in the conversation, even if its status is completed. use create_contact_sequence for clearly new, fresh, separate, or unrelated outreach. Historical matches alone must not force a confirmation question. Ask only when multiple enrollments plausibly overlap, an existing current sequence may conflict with apparently fresh outreach, or the intended sequence or branch is unclear. Do not use status alone as the intent boundary: in-progress and completed enrollments can be extended, while pending, failed, and canceled enrollments cannot. Search by enrollmentId, prospectId, email, LinkedIn URL, phone, HubSpot contact id, or name with optional companyDomain. This searches MCP Dynamic Actions enrollments across dynamic action flow plans; candidates include sourceDescription when known, flowPlanId, raw runtime status, hasFailedAction, flowPlanDisplayStatus, and a lightweight root with nodeId, type, payload.subject, payload.subjectType, next, onConnectionAccepted, and onConnectionTimeout. Use sourceDescription and root as context for sequence and branch selection. Use root to choose an email reply or new thread on the requested branch. Use get_flow_enrollment after selecting an enrollment only when complete enrollment/action/task details are needed.

find_mcp_enrollment

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Get status for a contact discovery audience import. Saved prospect ids are omitted by default; set includeProspectIds when you need to recover partial results after a failed import.

get_contact_discovery_audience_import_status

Return exact industry enum values for discover_contacts filters.current_company_primary_industry, filters.exclude_current_company_primary_industry, filters.current_company_industry, and filters.exclude_current_company_industry.

get_contact_discovery_industry_values

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Return a compact cross-system trace for a supplied identities array of at most 10 items: Flow Plans where a matching contact is awaiting or enrolled, audience memberships, enrollments, and readable tasks. For a selected contact, include every known supported identity as a separate array item: email, LinkedIn URL, phone, HubSpot contact id, and firstName, lastName, and companyDomain together when all three are known. Do not choose only one known identity. Each array item must contain exactly one direct identifier (email, LinkedIn URL, phone, or HubSpot contact id), or all of firstName, lastName, and companyDomain. This tool searches every item and returns the union of matching records, not one canonical contact. Every Flow Plan, audience, and enrollment includes matchedBy, showing the identity values that produced it. Use find_contact_data first for name-only searches or multiple matches. FirstTouch prospectId and enrollmentId are not accepted because they do not identify a contact across all trace sources. Each enrollment, awaiting-candidate, and audience-contact lookup is capped at 50 rows per identity; notes warns when a source reaches that cap and the trace may be incomplete. This is read-only and does not enrich, spend credits, or create an enrollment.

get_contact_trace

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Returns the current team credits account values. Reads the same billing account source used by the gateway credits balance API; contains no tokens or secret values.

get_credits_usage

Returns the current FirstTouch user, active team, available teams, current-team permissions including teamRole, effective capability scopes, and role-based toolAccess for this connection. toolAccess.mode=all allows all tools by role; mode=allowlist permits only allowedTools; mode=none permits no workspace actions. Subscription, billing, sender, and resource checks still apply. Recheck after caller or team changes. isTeamOwner identifies the actual team owner. Contains no access tokens, raw auth headers, or secret values.

get_current_user

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Requires team owner/admin access. Returns a page of excluded contact emails and company domains, plus all connected CRM exclusion segments. Segment results include synchronization status and timestamps. Follow cursor until it is null to read every contact and company exclusion.

get_exclusions

Returns the current billing feature cost table. Contains no account balance, access tokens, or secret values.

get_feature_costs

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Returns canonical fully qualified variable names for flow prompts, dynamic action prompts/messages, task text, email subjects, and branch expressions. Use returned templates exactly and do not use aliases or shorthand like {email} or {prospect_email}. Calling this tool does not mean a Flow Plan should be created; for Dynamic Actions, still use find_contact_data before the contact sequence tools for each contact.

get_flow_available_variables

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Get one enrollment/activity by id, including individual inbound email and LinkedIn replies with message content, tone, and received time; compact actions, tasks, warnings, interpretation notes, required follow-up action, and links. The notes explain how to assess deferred LinkedIn prospect enrichment and candidate account availability. Set includeFlowTree=true to inspect the root/tree stored on the enrollment; this snapshot can differ from the current flow-plan root after later edits. Omits the tree and enrollment.properties by default; action operationStatus is execution state, while taskStatus is the user-facing pending/done state.

get_flow_enrollment

Returns supported source modes and required request fields for flow creation.

get_flow_source_modes

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Get the current workspace for an existing flow: flow details, live details for its configured candidates, linked source status, estimated single-enrollment credit cost, awaiting contacts or signal events, enrollment counts/statistics, variable guidance, and available enrollment actions. candidateDetails is the source of truth for candidate account state; do not infer LinkedIn availability from the deprecated reassignment payload linkedin_account_id. Use this for flow-level enrollment statistics; use list_flow_plan_enrollments for this flow's page-style rows, list_enrollments for advanced multi-flow enrollment search, and get_flow_enrollment for one enrollment's actions/warnings.

get_flow_workspace

Returns FirstTouch documentation. Read workflow_selection before choosing a reusable Flow Plan or independent contact sequences, then read the selected workflow's guide. Read social_engagement for LinkedIn engagement monitoring or selecting people from captured engagement events. For contact sequences use dynamic_actions: create_contact_sequence starts a new sequence and add_contact_action extends its enrollment. Other topics cover reusable flows, audiences, discovery, enrollments, tasks, identity, sender capabilities, and issue reporting.

get_guide

Returns one synchronized FirstTouch LinkedIn Unibox conversation, its sender and participant context, and complete messages. Reading always uses mark_read=false, so inspection never changes unread state and does not trigger synchronization. Message output includes direction, timestamp, text, type, send status, and event/edit/delete/hidden indicators. Enrollment details, tasks, and activity-history payloads are intentionally excluded from this v1 response.

get_linkedin_unibox_conversation

Returns LinkedIn Unibox count buckets within the same accessible sender, search, and latest-message date scope. It returns allCount, hotCount, nurtureCount, unreadCount, and archiveCount. It does not accept tags, unreadOnly, or archived filters because those values are separate count buckets. This reads synchronized FirstTouch Unibox state and does not trigger synchronization.

get_linkedin_unibox_counts

Explains the canonical causes, resolution ownership, affected action counts, and reliable timing across the filtered active Social Outreach Queue. Use status_category and resolution_mode to determine whether human action is required or FirstTouch expects work to resume automatically; null timing means no reliable estimate exists, and ready for processing does not mean immediate send because queue order, Work Schedule, and safety spacing still apply. The response preserves the canonical queue insight fields and authorized sender identities unchanged. This reads stored FirstTouch data only and performs no external requests.

get_outreach_queue_insights

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Read get_guide with topic=social_engagement before using this tool; reuse it if already read for the current request. Returns one Social Engagement signal's enabled/unlocked state, fixed tracking mode, linked Flow Plan, and profile counts scoped to that signal. Requires team owner/admin access and an explicit signalId from list_social_engagement_signals. Profile mutation tools already return socialEngagement.flowPlan and socialEngagement.signal. Adding a monitored profile does not require this tool. May initialize missing default signal configuration; it does not relink the signal flow.

get_social_engagement_signal

Returns FirstTouch team metrics using the same core filters as the metrics endpoints: UTC date range, flow plan/source ids, and team member user ids. Use this when the customer asks for team performance, actions sent, manual task counts, email or LinkedIn engagement, replies, sentiment, opportunities, meetings booked, or email/LinkedIn chart trends. By default it returns totals, actions, engagement, and opportunity metrics; request emailChart or linkedinChart only when the customer asks for trend/chart/bucket data. flowPlanIds map to the API source_ids filter. Team owners can omit userIds to include all team users; non-owners are scoped by the service to their own user. This does not export CSV rows or return individual opportunities.

get_team_metrics

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Returns credits spent by one user in the current team, with a breakdown by billing feature. Requires team billing access. The UTC date bounds are inclusive. Optionally filter attributed transactions by source: Mcp, WebApp, Extension, PublicApi, or Unknown.

get_user_credit_usage

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Returns existing audiences that can be inspected or attached to a flow. Follow every cursor before making team-wide availability conclusions. These are API result pages, not the user's current UI page. Defaults to unlinked audiences; includeLinkedAudiences=true includes both linked and unlinked.

list_audiences

Requires the admin team role or global admin access. Check get_current_user.toolAccess before calling. Lists the current team's committed credits transaction history with UTC date, billing feature, user, and source filters. Requires team billing access. Use userId to return the exact transactions attributed to one user. Results can include committed spend, purchases, or administrative adjustments; inspect transaction type before describing an item as spent credits.

list_credit_transactions

Lists FirstTouch email send queue rows that have already been submitted to the email sending service. Use this for queued or awaiting submitted email sends, sent email history, failed or canceled attempts, and as the first execution-state check when a customer asks why an email has not sent. View is one of in_queue, awaiting, done, canceled, or failed and defaults to in_queue. The response includes the selected keyset page plus all five view counts using the same sender, search, and Flow Plan filters. expected send times describe FirstTouch sending, not inbox delivery. Omitted userIds always scopes to the current caller, including admins and team owners; elevated callers must select other team members explicitly. If an expected email is absent, follow response.nextSteps because phase 1 excludes actions that have not reached mail-service submission.

list_email_send_queue