> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firsttouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For API operations, fetch https://gateway.firsttouch.ai/api/public/openapi.json for the complete input/output schemas, internal references, and x-mcp-annotations. Endpoint Markdown intentionally omits generated schema fragments. Select /api/public/tools/<tool_name> using the exact underscore-separated name. Send requests to https://gateway.firsttouch.ai; the canonical document currently omits servers. Start at https://docs.firsttouch.com/api-reference/agent-start.md.

# Add Dynamic Action

> Create or extend one MCP Dynamic Actions enrollment for exactly one contact.

**Required preflight**

- Call get_guide with topic=dynamic_actions before this tool.
- Before calling this tool, call find_contact_data with every known identity unless verified enrichment was returned earlier in the conversation.
- Then call find_mcp_enrollment with the known identifiers; if candidates are returned, ask which enrollment to continue or whether to start a new sequence, and if none is returned, continue with the requested new action.
- Resolve action.assignedUserId with get_current_user and list_team_members before calling this tool.
- On the first attempt, omit allowExcludedContact or set it to false.

<details>
<summary><strong>Workflow and write receipt</strong></summary>
<ul>
<li>The tool then checks the effective contact email and company domain against the FirstTouch exclusions list before creating an enrollment or appending any action type.</li>
<li>If either is excluded, the operation is rejected before any enrollment or action mutation: no new enrollment is created, no action is appended, and an existing enrollment remains unchanged.</li>
<li>Tell the customer whether the email or company domain is excluded and ask whether they explicitly want to bypass exclusions for this action.</li>
<li>Retry with allowExcludedContact=true only after that confirmation.</li>
<li>The bypass applies only to this call and does not remove the exclusion.</li>
<li>Use get_exclusions only when the customer wants to inspect the matching exclusion.</li>
<li>When content uses variables, use only fully qualified templates such as {ft.flow.prospect_first_name}; do not use aliases such as {{firstName}}.</li>
<li>This tool adds one action step per call and returns flowPlanId, enrollmentId, nodeId, assignedUserId, approval/task flags, taskIds when task rows are available, taskIdsPending/taskMaterializationStatus for async task materialization, uiLinks, and nextSteps.</li>
<li>Treat enrollmentId + nodeId as the write receipt; if nodeAppended=true, do not retry add_dynamic_action for the same requested step just because taskIds is empty or get_flow_enrollment has not materialized actions/tasks yet.</li>
</ul>
</details>

<details>
<summary><strong>Contact identity</strong></summary>
<ul>
<li>Every appended action requires contact.firstName and contact.lastName in its effective identity.</li>
<li>For a new sequence, provide both names in contact plus contact.email, contact.linkedInUrl, contact.phone, or company.domain; contact.prospectId is also supported when it resolves to a full name.</li>
<li>When continuing a selected enrollment that lacks either name, provide both names in contact to backfill it.</li>
<li>Ask the customer for missing names and do not invoke an enrichment tool automatically.</li>
<li>Use the optional contact and company objects for verified context returned by find_contact_data or explicit enrichment; their fields are all optional.</li>
<li>Populate every other verified known field.</li>
</ul>
</details>

<details>
<summary><strong>Content and email behavior</strong></summary>
<ul>
<li>This tool does not enrich request inputs or generate content; pass final email, LinkedIn send, call, or task text written by the MCP client.</li>
<li>linkedin_profile_view has no content and supports delay, appendTarget, assignedUserId, and isHumanApprovalRequired.</li>
<li>MCP Dynamic Actions do not use AI to generate email subjects.</li>
<li>For a new email enrollment, omit action.subjectType: it defaults to new_thread and action.subject is required.</li>
<li>For an existing enrollment, action.subjectType is required: choose new_thread and provide action.subject for a separate conversation, or choose reply only when the selected append branch has a prior email;<br />reply inherits that subject and must omit action.subject.</li>
<li>Use find_mcp_enrollment candidate.root to trace the requested append branch.</li>
<li>Use get_flow_enrollment after selecting an enrollment only when complete enrollment/action/task details are needed.</li>
</ul>
</details>

<details>
<summary><strong>Existing enrollment and priority</strong></summary>
<ul>
<li>To continue an existing MCP Dynamic Actions enrollment, pass enrollmentId;<br />existing enrollment identity wins, and supplied contact.email, contact.linkedInUrl, contact.phone, or contact.prospectId can only backfill missing values, not retarget the enrollment.</li>
<li>Other contact and company context only fills missing enrollment properties and never overwrites an existing value.</li>
<li>Set whole-enrollment scheduling priority only when the customer explicitly asks: use 1 for High, 0 or omit for normal, and -1 for Low.</li>
<li>Priority on an existing enrollment updates it.</li>
</ul>
</details>

<details>
<summary><strong>Sender eligibility</strong></summary>
<ul>
<li>Resolve and pass action.assignedUserId before every call: use the current MCP user when no sender is requested, a named member when requested, or one eligible team member when the customer asks for any capable sender.</li>
<li>Email requires Email actions permission and a connected email account.</li>
<li>LinkedIn connect/message/profile requires Social permission plus a live synced LinkedIn account; InMail additionally requires an eligible Premium or Sales Navigator plan.</li>
<li>A linkedin_connect requires the selected sender not to be a saved 1st-degree connection of the contact; if already connected, use linkedin_message instead.</li>
<li>A linkedin_message outside a connection_accepted branch requires the selected sender to be a saved 1st-degree connection; when another team member is connected instead, the validation error identifies that member for reassignment.</li>
<li>When the selected sender is not connected, use linkedin_connect followed by a message on connection_accepted, or use linkedin_inmail if the sender has an eligible Premium or Sales Navigator plan.</li>
<li>Call and manual tasks require their matching permissions.</li>
<li>If the selected user lacks a required capability, this tool rejects the action instead of silently assigning another user.</li>
</ul>
</details>

<details>
<summary><strong>Action requirements and scheduling</strong></summary>
<ul>
<li>Pass exactly one action with type email, linkedin_connect, linkedin_message, linkedin_inmail, linkedin_profile_view, manual_task, or call_task.</li>
<li>Each action type exposes only its supported fields.</li>
<li>Email requires action.prompt and an effective recipient email.</li>
<li>LinkedIn messages require action.message and an effective linkedInUrl.</li>
<li>linkedin_inmail requires non-empty action.prompt and action.subject, and does not accept action.message.</li>
<li>linkedin_profile_view supports one action per default, connection accepted, or connection timeout branch and cannot have content.</li>
<li>Manual tasks require action.name.</li>
<li>Call tasks require action.message and an effective phone; action.name is not a call script.</li>
<li>Every action type requires human approval by default.</li>
<li>Omit action.isHumanApprovalRequired to keep approval enabled; set it to false only when the customer explicitly asks to disable approval.</li>
<li>Omit action.delay or use 00:00:00 for no delay/immediate execution.</li>
<li>For a delay, use d.hh:mm:ss or hh:mm:ss, for example 5.00:00:00 for 5 days; do not use natural language such as &#39;5 days&#39;.</li>
<li>Use action.appendTarget only for LinkedIn connection accepted/timeout branches.</li>
<li>For linkedin_connect, action.connectionTimeout optionally sets the acceptance window using a positive d.hh:mm:ss or hh:mm:ss TimeSpan; omit it for the 14-day default.</li>
</ul>
</details>

<details>
<summary><strong>Shared Flow Plan settings</strong></summary>
<ul>
<li>This tool has no per-action HubSpot enrichment or task-sync flags: those are shared MCP Flow Plan settings configured only with update_flow_plan as mcpDynamicActionsOptions.is_enrich_hubspot and mcpDynamicActionsOptions.is_push_to_hubspot_tasks.</li>
<li>The task setting updates call, manual, and approval task sync together.</li>
<li>The returned flowPlanId is read-only for its name, flow structure, and other normal mutations; do not use it with flow-root, publication, audience, or enrollment mutation tools.</li>
</ul>
</details>



## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.firsttouch.com/llms.txt).