FirstTouch

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

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

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

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. Omit enrollmentId 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

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

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

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, and effective capability scopes. A team owner has full team-management rights in the current team; sender and billing capabilities are reported separately. Granted scopes are the source of truth for which MCP actions the current user can perform. Contains no access tokens, raw auth headers, or secret values.

get_current_user

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

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 one named contact, still use find_contact_data before add_dynamic_action.

get_flow_available_variables

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

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 as Markdown. Topics cover the domain overview, reusable flow creation, one-contact Dynamic Actions, contact discovery, audiences, enrollments, tasks and approvals, contact identity, and senders and capabilities.

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

Returns the current FirstTouch Social Engagement setup for the team. Requires team owner/admin access. Includes whether linkedin_engagement is enabled/unlocked, the existing UI-linked Social Engagement flow plan, and monitored profile counts. Use this to refresh or inspect current state when no profile mutation was just performed; manage_social_engagement_monitored_profile already returns socialEngagement.flowPlan. Adding a monitored profile does not require this tool. Like the UI config read, this may initialize missing default signal config; it does not relink the signal flow.

get_social_engagement_config

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

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

Returns existing audiences that can be inspected or attached to a flow.

list_audiences

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

Call get_guide with topic=enrollment_management for enrollment, Awaiting, queue-item, identifier, and status guidance. Advanced search for lightweight real enrollment rows. Uses the enrollment read model and returns source=flow rows only; it does not return queue-only rows or UI page rows. Do not use this for active/current LinkedIn actions, LinkedIn action/request status, LinkedIn queue diagnostics, or why a LinkedIn action has not sent; use list_linkedin_outreach_queue instead. If the customer asks for enrollments/activities and specifically mentions LinkedIn actions, check list_linkedin_outreach_queue as well because enrollment rows do not expose provider request status, awaiting requirements, or request gates. Use this, rather than list_flow_plan_enrollments, when filtering completed, failed, or canceled enrollments by when that terminal status happened—for example, 'canceled enrollments for this flow in the last 12 hours'. Pass flowPlanId, statuses, and finishedFrom/finishedTo; from/to filter enrollment creation time only. For a simple one-flow status page without a terminal-date range, use list_flow_plan_enrollments. Rows include replySummary with counts and latest timestamp, but not reply bodies; use enrollmentId with get_flow_enrollment only when canInspectEnrollment is true to read individual replies. Omits root, tasks, and action payloads.

list_enrollments

Lists credits spent by the current team's flow plans from the same source as the flow-plan/credits-usage-cursor UI endpoint. Requires team billing access. Use fromUtc and toUtc for the reporting period. Follow cursor pages to calculate a complete total across all matching plans.

list_flow_plan_credits_usage

List enrollment page rows for one flow plan and one status bucket. Use this for a simple request in a specific flow, such as 'show in-progress enrollments for this flow'. It does not filter by when an enrollment completed, failed, or was canceled. For a terminal-status time range, such as 'canceled enrollments for this flow in the last 12 hours', use list_enrollments with flowPlanId, statuses, and finishedFrom/finishedTo. Uses the flow-plan enrollment page service and can return both source=flow rows and source=queue rows. Rows include replySummary with counts and latest timestamp, but not reply bodies; use get_flow_enrollment with enrollmentId to read individual replies. Queue rows do not have enrollmentId yet; use queueItemId for queue actions, not get_flow_enrollment.

list_flow_plan_enrollments

List compact flow plans for the caller's team. Does not return the flow root/tree. Metrics and estimated per-enrollment cost are optional; request includeMetrics/includeCost only when needed. Supports sorting by created, name, enrollments, replies, opportunities, or awaiting. For top/most/highest flow questions, sort by the requested metric and use limit=5 unless the customer asks for more.

list_flow_plans

Returns HubSpot contact lists available to the current team.

list_hubspot_lists

Lists FirstTouch LinkedIn outreach queue rows. Use this when the customer asks for active LinkedIn actions, current LinkedIn actions, LinkedIn actions waiting to run, LinkedIn action status, where a LinkedIn request/action/outreach step stands, why a LinkedIn action has not sent yet, what needs review or approval, what is pending for a sender/source/contact, or which LinkedIn actions completed, failed, or were canceled. Use view for common slices: active returns pending provider requests plus pre-provider-request blockers and excludes terminal history; review_required returns only pre-provider-request actions blocked by requirements; in_queue returns created provider requests still pending; done, canceled, and failed return terminal provider requests; all returns normal outreach rows across pending, blocked, and terminal states for view_profile, send_connection, and send_message; diagnostic_all returns an expanded debug view across all LinkedIn request types, including non-standard/internal requests; custom uses the explicit advanced filters. Advanced filters can narrow by sender users, LinkedIn account ids, flow plans, action/request types, ids, search text, and date ranges. After calling, follow response.nextSteps for task approval, activity inspection, scheduler/limit delays, account blockers, and pagination. This reads stored FirstTouch data only and performs no external requests.

list_linkedin_outreach_queue

Lists synchronized FirstTouch LinkedIn Unibox conversations ordered by latest message descending. Search covers participant name, LinkedIn URL, company name, company domain, and latest-message preview. tags accepts hot and nurture; supplying both uses OR semantics, while omitted or empty tags applies no tag filter. unreadOnly=true returns only unread conversations. archived=true returns archived only, archived=false non-archived only, and omitted archived returns both. Date boundaries are inclusive and apply to latest-message time, falling back to conversation creation time. Defaults to 20 rows, caps at 100, and uses opaque nextCursor pagination. This does not trigger synchronization.

list_linkedin_unibox_conversations

Lists the current team's purchase history from the same billing source and with the same UTC date filters as the charge/cursor Billing UI endpoint. Requires team billing access. Results include subscription, additional-credits, and manual charges. Follow cursor pages to read the complete history.

list_purchases

Lists Social Engagement monitored LinkedIn profiles or company pages for the current team. Requires team owner/admin access. This corresponds to the UI section Monitored profiles / Profiles to monitor. Filter by status when the customer asks for active or inactive monitored profiles.

list_social_engagement_monitored_profiles

Call get_guide with topic=senders_and_capabilities before selecting flow candidates or Dynamic Action assignees. Lists active members of the current team with their FirstTouch user id, email, role, ownership, user-facing access level (Paid sender or View-only), connected email accounts, LinkedIn account state, and flow-assignment permissions. Paid sender seats allow account connections and sender actions. Viewers can access the product, but cannot connect accounts, act as senders, or be assigned flow work. For reusable flow plans, call this before choosing candidates: email requires isEmailConnected and isEmailSendingEnabled; LinkedIn requires isLinkedinReady and isLinkedinActionsEnabled; calls and manual tasks require their matching assignment permission; every flow needs at least one selected candidate with isApprovalEnabled. Use exact returned userIds in flow.candidates. For dynamic actions, resolve every sender before calling add_dynamic_action: when no sender was requested, find the current user and select that member; when named, compare the supplied identity with returned names, emails, and user ids; when any capable sender is requested, select one eligible returned member and report who was chosen. Pass that userId as action.assignedUserId. Email requires isEmailConnected and Email actions permission. LinkedIn connect/message/profile requires isLinkedinReady and Social actions permission; InMail also requires an eligible linkedinAccount.plan_type (Premium or Sales Navigator, subject to the team's Premium setting). Calls and manual tasks require their matching permissions. Do not use LinkedIn Unibox tools to choose a flow or dynamic-action sender. isEmailConnected, isLinkedinConnected, and isLinkedinReady filters use AND semantics when combined. LinkedIn ready means the account is alive and its relations sync has completed; dynamic actions validate the remaining capability requirements before creation.

list_team_members

Call get_guide with topic=tasks_and_approvals for task kinds, readiness, approval, editing, completion, and skipping guidance. List slim task summaries. Defaults to todo tasks assigned to the current user; callers can set includeTeamTasks=true to read tasks owned by active members of the current team, or assignedUserId for one user. For a general request to view pending tasks, omit types. Use preview_task for payload, properties, warnings, and action details.

list_user_tasks

Publish or unpublish an existing flow. Publishing activates the flow plan but does not enroll awaiting contacts. If validation fails, the tool fails with validation errors and links.

manage_flow_publication

Returns preview contacts for one HubSpot contact list.

preview_hubspot_list

Preview a single task by id, including payload, task status, blocking enrollment warnings, approval readiness, task.properties, and links. For MCP Dynamic Actions approval tasks, task.payload.actions[].branch_context and actionGroup.actions[].branchContext identify actions on the main, connection_accepted, and connection_timeout paths. task.properties is the task PropertyValueDto[] used for data variables and readiness checks, including prospect, company, routing, and enriched values when present.

preview_task