Tools reference

Complete parameter reference for all 32 MCP tools, grouped by category.

Tip: Call start_pipeline_journey first whenever you want to build a new pipeline — it returns a full guided plan and all the option IDs you'll need.

---

Analytics

get_account_summary

Account snapshot: total pipelines, opportunities, and message counts.

No parameters required.

---

get_ai_performance

Total AI messages, average response time, and total cost.

No parameters required.

---

get_messaging_stats

Messaging volume with optional filtering.

Parameter	Type	Required	Description
start_date	string	No	ISO 8601 lower bound on message date
end_date	string	No	ISO 8601 upper bound on message date
pipeline_id	integer	No	Restrict to a specific pipeline
provider	string	No	whatsapp, messenger, instagram, linkedin, web, or widget

---

Discover

list_pipelines

Your pipelines with status, description, and stage counts. No parameters required.

---

list_pipeline_stages

Stages of a pipeline ordered by stage order.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline to list stages for

---

list_actions

Actions for a pipeline, optionally filtered to a specific stage.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline that owns the actions
stage_id	integer	No	Restrict to a specific stage; omit to return all actions including pipeline-level ones

---

list_action_results

Execution log for a pipeline's actions — one row per recorded run. Use it to check whether a webhook actually fired, and what it returned.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline whose action results to list
opportunity_id	integer	No	Restrict to a single opportunity
conversation_id	integer	No	Restrict to opportunities linked to this conversation
action_id	integer	No	Restrict to a single action. Use list_actions
limit	integer	No	Results to return (default 50, max 100)
offset	integer	No	Results to skip for pagination (default 0)

---

list_variables

Pipeline variables available for use in actions. Call this before create_action to see which {{variable_name}} references already exist.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline to list variables for
q	string	No	Filter by variable name substring

---

list_contacts

Contacts (one row per contact) with merged custom overrides. Filters mirror those of the opportunities view.

Parameter	Type	Required	Description
pipeline_id	integer	No	Restrict to contacts in this pipeline
status	string	No	active, pending, won, or lost
priority	string	No	high, medium, or low
q	string	No	Search name, email, phone, or identifier
tag_ids	integer[]	No	Restrict to contacts tagged with any of these IDs
start_date	string	No	ISO 8601 lower bound on created_at
end_date	string	No	ISO 8601 upper bound on created_at
page	integer	No	Page number (default 1)
per_page	integer	No	Page size (default 25, max 100)

---

list_opportunities

Opportunities (one row per opportunity) with contact, stage, and tags context. A single contact can appear multiple times if they have multiple opportunities.

Parameter	Type	Required	Description
pipeline_id	integer	No	Restrict to this pipeline
stage_id	integer	No	Restrict to this stage
status	string	No	active, pending, won, or lost
priority	string	No	high, medium, or low
q	string	No	Search contact name, email, phone, identifier, or custom name
tag_ids	integer[]	No	Restrict to opportunities tagged with any of these IDs
tags	string[]	No	Same filter by tag name, case-insensitive. Prefer this when you know the name
start_date	string	No	ISO 8601 lower bound on created_at
end_date	string	No	ISO 8601 upper bound on created_at
page	integer	No	Page number (default 1)
per_page	integer	No	Page size (default 25, max 100)

---

list_messages

Messages across pipelines, returned in chunks via cursor pagination for large result sets.

Parameter	Type	Required	Description
pipeline_id	integer	No	Restrict to this pipeline
contact_id	integer	No	Restrict to a specific contact
role	string	No	user or assistant
start_date	string	No	ISO 8601 lower bound on message date
end_date	string	No	ISO 8601 upper bound on message date
cursor	string	No	Pagination cursor returned by the previous call
limit	integer	No	Chunk size (default 100, max 500)

Pass the returned next_cursor back to fetch the next chunk.

---

list_knowledge_tables

Lists the authenticated user's knowledge tables with column counts and attached pipelines. No parameters required.

---

search_knowledge_table

Search a knowledge table by natural-language query and return the most relevant rows.

Parameter	Type	Required	Description
knowledge_table_id	integer	Yes	The table to search. Use list_knowledge_tables to find IDs
query	string	Yes	Natural-language search query
limit	integer	No	Max results to return (default 5, max 20)
use_hybrid	boolean	No	true (default) for vector + keyword search; false for pure vector search

Search results carry point_ids, not default_ids — to delete or update a row you found here, look up its default_id with list_knowledge_points.

---

list_knowledge_points

Lists the rows stored in a knowledge table, with each row's default_id and column values. Use it to find the default_ids to pass to delete_knowledge_points or upsert_knowledge_points.

Parameter	Type	Required	Description
knowledge_table_id	integer	Yes	The table to list. Use list_knowledge_tables to find IDs
per_page	integer	No	Rows per page (default 20, max 100)
next_page_offset	string	No	Offset returned by the previous call. Omit for the first page

Each entry in points has point_id, default_id, data (the row's column values), and modified_date. Pass the returned next_page_offset back to fetch the next page; has_more is false on the last page. All IDs are returned as strings so they survive JSON parsing without rounding.

---

get_stage_followup

Returns the followup configuration for a stage, including the full interval schedule.

Parameter	Type	Required	Description
stage_id	integer	Yes	The stage to retrieve the followup for. Use list_pipeline_stages

Returns has_followup (boolean) and followup (object with id, is_active, intervals, instructions, after_followup_stage_id, max_messages).

---

list_model_pool

The Smart Routing model pool for a pipeline — the current router / simple / moderate / complex assignments. Call this before update_model_pool to see what you are changing.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline whose model pool to list. Use list_pipelines

---

get_pipeline_options

Returns available agent types, AI providers, AI models, languages, dialects, and user-connected channels. Call this before create_pipeline to obtain the valid IDs.

Models are returned per provider: call it once with no ai_provider_id to get the provider list, ask the user which one they want, then call it again with their choice to get that provider's models.

Parameter	Type	Required	Description
language_code	string	No	Defaults to en
ai_provider_id	integer	No	Omit to get ai_providers with an empty ai_models; supply it to get that provider's full model rows

---

Build

start_pipeline_journey

Begins a guided, step-by-step journey to build a complete pipeline: pipeline settings → stages → actions. Call this first whenever a user wants to create a pipeline. Returns the full plan, all available options, and the exact questions to ask at each step.

Parameter	Type	Required	Description
language_code	string	No	Language for the guided plan (default en)
ai_provider_id	integer	No	Provider to return models for. Omit on the first call to get ai_providers and ask the user to choose

---

create_pipeline

Creates a new AI pipeline.

Parameter	Type	Required	Description
agent_type_id	integer	Yes	Agent type (e.g. Sales, Support). Use get_pipeline_options for valid IDs
name	string	Yes	Unique name for the pipeline
ai_model_id	integer	Yes	AI model to use. Use get_pipeline_options for valid IDs
language_id	integer	Yes	Primary language. Use get_pipeline_options for valid IDs
description	string	No	Short description of the pipeline's purpose
persona	string	No	Top-level AI persona: voice, tone, and identity across all stages
instructions	string	No	Top-level AI behavioral guidelines across all stages
channel_id	integer	No	Link to a specific communication channel
rag_mode	string	No	none, vector, or hybrid
dialect_id	integer	No	Language dialect. Use get_pipeline_options
model_temperature	number	No	AI creativity (0.1 – 1.0)
no_of_relevant_points	integer	No	RAG knowledge points per request
agent_memory_window	integer	No	Size of the agent's memory window
max_conversation_cost	number	No	Cost cap per conversation
max_conversation_messages	integer	No	Message cap per conversation (min 1)
context_message_count	integer	No	Prior messages included as context in each AI request
followup_limit	integer	No	Max follow-up messages per opportunity (default 6, min 1)
is_unknown_contacts_enabled	boolean	No	Accept contacts the workspace has never seen and open opportunities for them. Defaults to true
is_model_routing_enabled	boolean	No	Enable Smart Routing. When true, is_model_routing is required
is_model_routing	object[]	No	Exactly 4 tier entries. Required when Smart Routing is on
is_model_routing[].tier	string	Yes	router, simple, moderate, or complex
is_model_routing[].ai_model_id	integer	Yes	Model for this tier. Use get_pipeline_options
is_model_routing[].instructions	string	No	When the router should pick this tier, or how the worker should behave

Smart Routing

Smart Routing is the user-facing name for model routing. A router model reads each request and hands it to one of three worker tiers — simple, moderate, complex — so cheap requests do not pay for an expensive model. On an existing pipeline, set the pool with update_model_pool instead.

---

create_stage

Creates a new stage inside a pipeline.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline this stage belongs to
name	string	Yes	Stage name (min 3 characters)
nature	string	Yes	neutral (in-progress), won (closed successfully), or lost (closed unsuccessfully)
order	integer	Yes	Position in the pipeline (1 = first)
description	string	No	Human-readable stage description
enter_condition	string	No	Natural-language criteria an opportunity must meet to enter this stage (min 20 characters). Strongly recommended for production
ai_persona	string	No	AI persona override for conversations in this stage
instructions	string	No	Stage-specific AI behavioral guidelines
notes	string	No	Internal notes (not visible to end users)
parent_id	integer	No	Parent stage ID for sub-stage hierarchy
is_opening_message	boolean	No	Whether to send an opening message when an opportunity enters this stage
opening_message_type	string	No	ai_generated or static. Required when is_opening_message is true
static_opening_message	string	No	The fixed opening message text. Used when opening_message_type is static

Production stages

enter_condition, ai_persona, instructions, and notes are what separates a stage that "kind of works" from one that performs. Add them on creation or update them immediately after.

---

create_variable

Creates a pipeline variable that actions can reference as {{variable_name}} in their URL, headers, or payload.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline that owns this variable
name	string	Yes	Variable name — letters, digits, underscores only (^[A-Za-z0-9_]+$). Must be unique within the pipeline
value	string	Yes	The variable's underlying value. Format depends on type (see below)
type	string	Yes	fixed, from_system, from_action, or from_ai
is_required	boolean	Yes	Whether the variable must resolve before any referencing action fires
description	string	No	Human-readable note about what this variable represents
data_type	string	No	string, integer, boolean, or float (default: string)

value format by type:

Type	Value format	Example
fixed	Literal string	Bearer abc123
from_system	entity.field — no braces	opportunity.contact_email
from_action	action_name.response.path.to.field or action_name.status	get_crm_user.response.data.id
from_ai	Short extraction instruction	The customer's preferred delivery date

Available from_system fields:

Entity	Fields
opportunity	id, contact_id, stage_id, pipeline_id, name, notes, status, contact_name, contact_priority, contact_identifier, contact_email, contact_phone, nature, conversation_id
stage	id, pipeline_id, pipeline_name, name, order
message	id, message, is_manual, role, call_type, files, status, error

Variables are the only way to inject runtime values into actions

Never put raw system placeholders like {{opportunity.contact_email}} directly in an action URL, header, or payload. Wrap them in a from_system variable first, then reference that variable by its name.

---

create_action

Creates an HTTP webhook action that fires when its trigger condition is met.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline that owns this action
name	string	Yes	Unique name within the pipeline (max 255 characters)
method	string	Yes	HTTP method: GET, POST, PUT, PATCH, or DELETE
url	string	Yes	External endpoint URL. May contain {{variable_name}} placeholders
is_active	boolean	Yes	Set false to create in draft mode
fixed_trigger	string	Yes	When the action fires (see below)
stage_id	integer	No	Attach to a specific stage. Omit for a pipeline-level (global) action
description	string	No	Human-readable description
headers	object	No	HTTP headers as key/value pairs. Values may contain {{variable_name}} placeholders
payload	object	No	Request body as a JSON object. Values may contain {{variable_name}} placeholders
instructions	string	No	Natural-language guidance for AI-driven triggers
max_fires	integer	No	Cap on how many times this action fires per opportunity (min 1)
retries	integer	No	Retry attempts on HTTP failure (1 – 10)
order	integer	No	Execution order among actions with the same trigger (lower runs first, min 1)
response_example	object	No	Example of the expected response (used to scaffold from_action variables)

fixed_trigger values:

Value	When it fires	Changeable after creation
stage_started	When an opportunity enters the stage	No
on_any_message	On every message	No
on_user_message	AI decides per user message	Yes
custom	AI triggers on its own logic	Yes

from_ai variables not compatible with system triggers

Variables of type from_ai are resolved after the AI processes a message. They cannot be used with stage_started or on_any_message actions, which fire before the AI runs.

---

create_followup

Creates a re-engagement followup sequence for a stage. Each stage supports one followup. The followup fires timed messages to opportunities that have gone quiet in that stage.

Parameter	Type	Required	Description
stage_id	integer	Yes	The stage to attach this followup to. Each stage can only have one followup
is_active	boolean	Yes	Start sending immediately (true) or create in draft mode (false)
intervals	object[]	Yes	Timed schedule (1 – 100 entries). Array order determines sequence
intervals[].interval_value	integer	Yes	Wait duration (1 – 100)
intervals[].interval_unit	string	Yes	minute, hour, day, week, or month
instructions	string	No	AI instructions for what to say in follow-up messages
after_followup_stage_id	integer	No	Stage to move the opportunity to once all intervals are exhausted
assets	string	No	Media or links to include in follow-up messages

Which stages need followups?

Use followups on neutral stages where leads go quiet (e.g. "Waiting for reply", "Proposal sent"). Won and lost stages never need followups. start_pipeline_journey will suggest candidates automatically.

---

create_knowledge_table

Creates a new knowledge table with its columns in one call. The table stores structured data the pipeline AI agent can search and retrieve during conversations.

Parameter	Type	Required	Description
name	string	Yes	Unique table name
description	string	No	What this table contains and when the agent should use it
columns	object[]	Yes	Column definitions (min 1)
columns[].name	string	Yes	Column name — unique within the table
columns[].data_type	string	Yes	string, number, or boolean
columns[].order	integer	Yes	Display order (1 = first)
columns[].is_searchable	boolean	No	Agent can search by this column. Enable for your primary text/content column
columns[].is_retrievable	boolean	No	Column is included in search results returned to the agent
columns[].is_filterable	boolean	No	Agent can filter results by this column value
columns[].is_unique	boolean	No	Values must be unique across rows

After creation, populate rows with upsert_knowledge_points, then attach the table to the pipeline that should use it.

A new table is inert until it is attached

Creating a table and filling it with rows does not make it reachable. Attach it with update_pipeline:

{ "pipeline_id": 12, "attach_knowledge_table_ids": [<the new table id>] }

list_knowledge_tables shows which pipelines each table is currently attached to.

---

upsert_knowledge_points

Inserts or updates rows in a knowledge table. Each row matched by default_id — existing rows are updated, new ones are inserted. This operation costs training credits.

Parameter	Type	Required	Description
knowledge_table_id	integer	Yes	The table to upsert rows into. Use list_knowledge_tables to find IDs
points	object[]	Yes	Rows to upsert (min 1). Each object must include default_id plus column values
points[].default_id	string	Yes	Stable identifier for the row — used to match for updates (e.g. a product SKU or an FAQ slug)

Include a key/value pair for every column defined on the table. Example:

{
  "knowledge_table_id": 42,
  "points": [
    { "default_id": "faq-001", "question": "What is your return policy?", "answer": "30 days, no questions asked." },
    { "default_id": "faq-002", "question": "Do you ship internationally?", "answer": "Yes, to 50+ countries." }
  ]
}

---

Update

update_pipeline

Updates an existing pipeline. Only the fields you provide are changed.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline to update. Use list_pipelines
name	string	No	New pipeline name
description	string	No	New description
persona	string	No	Updated AI persona
instructions	string	No	Updated AI behavioral guidelines
status	string	No	Pipeline status
is_archived	boolean	No	Archive or restore the pipeline
ai_model_id	integer	No	New AI model. Use get_pipeline_options
language_id	integer	No	New language. Use get_pipeline_options
dialect_id	integer	No	New dialect
model_temperature	number	No	AI creativity (0.1 – 1.0)
rag_mode	string	No	none, vector, or hybrid
no_of_relevant_points	integer	No	RAG points per request
agent_memory_window	integer	No	Memory window size
context_message_count	integer	No	Context message count
max_conversation_cost	number	No	Cost cap per conversation
max_conversation_messages	integer	No	Message cap per conversation
followup_limit	integer	No	Max follow-up messages per opportunity (min 1)
is_unknown_contacts_enabled	boolean	No	Accept contacts the workspace has never seen
is_model_routing_enabled	boolean	No	Toggle Smart Routing
attach_knowledge_table_ids	integer[]	No	Knowledge tables to attach, so this pipeline's agent can search them. Additive — tables already attached stay attached
detach_knowledge_table_ids	integer[]	No	Knowledge tables to unlink from this pipeline. The table and its rows survive; other pipelines using it are unaffected

Note: agent_type cannot be changed after pipeline creation. This tool toggles Smart Routing but does not carry the tier assignments — use update_model_pool for those.

Attaching knowledge

A knowledge table is inert until it is attached to a pipeline. Creating it and filling it with rows is not enough — no agent searches it until you attach it here.

Both fields are relative, not a replacement: they add or remove exactly the IDs you list and leave every other attachment on the pipeline alone. Both are idempotent — re-attaching a table that is already attached comes back under already_attached, and detaching one that was not attached comes back under not_attached, neither being an error. Sending the same ID in both lists is rejected outright, and nothing changes.

{
  "pipeline_id": 12,
  "attach_knowledge_table_ids": [3, 7],
  "detach_knowledge_table_ids": [4]
}

The response carries a knowledge_tables object with attached, detached, already_attached, not_attached, and now_attached — each a list of {id, name}, so you can read the change back without a follow-up call. A table you do not own fails the whole call before anything is written.

---

update_model_pool

Creates or replaces the Smart Routing model pool on an existing pipeline. Requires exactly 4 models — one per tier. Smart Routing is switched on for the pipeline once the update succeeds.

Parameter	Type	Required	Description
pipeline_id	integer	Yes	The pipeline to update. Use list_pipelines
models	object[]	Yes	Exactly 4 tier assignments — no more, no fewer
models[].tier	string	Yes	router, simple, moderate, or complex, each used once
models[].ai_model_id	integer	Yes	Model for this tier. Use get_pipeline_options
models[].instructions	string	No	When the router should pick this tier, or how the worker should behave

Call list_model_pool first to see the current assignments — this replaces all four, not just the ones you name.

---

update_stage

Updates an existing stage. Only the fields you provide are changed.

Parameter	Type	Required	Description
stage_id	integer	Yes	The stage to update. Use list_pipeline_stages
name	string	No	New stage name (min 3 characters)
description	string	No	New description
nature	string	No	neutral, won, or lost
order	integer	No	New position in the pipeline
enter_condition	string	No	Updated entry criteria (min 20 characters)
ai_persona	string	No	Updated AI persona for this stage
instructions	string	No	Updated stage-specific AI instructions
notes	string	No	Updated internal notes
is_opening_message	boolean	No	Toggle opening message
opening_message_type	string	No	ai_generated or static
static_opening_message	string	No	Updated static opening message text
is_folded	boolean	No	Collapse this stage in the UI

---

update_action

Updates an existing action. Only the fields you provide are changed.

Parameter	Type	Required	Description
action_id	integer	Yes	The action to update
name	string	No	New action name
description	string	No	New description
is_active	boolean	No	Enable or disable the action
method	string	No	New HTTP method
url	string	No	New endpoint URL
headers	object	No	Updated headers
payload	object	No	Updated request body
fixed_trigger	string	No	on_user_message or custom only — system triggers (stage_started, on_any_message) cannot be changed after creation
instructions	string	No	Updated AI trigger instructions
max_fires	integer	No	Updated fire cap
retries	integer	No	Updated retry count (1 – 10)
order	integer	No	Updated execution order
response_example	object	No	Updated response example

---

update_variable

Updates an existing pipeline variable. Only the fields you provide are changed.

Parameter	Type	Required	Description
variable_id	integer	Yes	The variable to update
name	string	No	New name. Ignored if the variable is already referenced by one or more actions
value	string	No	New value (format rules same as create_variable)
type	string	No	New type: fixed, from_system, from_action, or from_ai
is_required	boolean	No	Updated required flag
description	string	No	Updated description
data_type	string	No	string, integer, boolean, or float

---

update_opportunities

Bulk update one or many opportunities at once.

Parameter	Type	Required	Description
opportunity_ids	integer[]	Yes	IDs to update. Pass [123] for a single update
status	string	No	New status: pending, active, won, or lost
stage_id	integer	No	Move to this stage (must be in the same pipeline)
name	string	No	Override the opportunity name
notes	string	No	New notes
tags	string[]	No	Tag names to add (missing tags are created automatically)
deleted_tags	integer[]	No	Tag IDs to remove

Returns updated_ids and skipped entries with reasons (e.g. cross-pipeline stage moves are rejected).

---

update_followup

Updates an existing followup configuration. Only the fields you provide are changed. When intervals is provided it replaces the entire schedule — supply all intervals you want, not just the changed ones.

Parameter	Type	Required	Description
followup_id	integer	Yes	The followup to update. Use get_stage_followup to find this
is_active	boolean	No	Enable or disable the followup
intervals	object[]	No	Replacement interval schedule (see create_followup for item schema)
instructions	string	No	Updated AI instructions for follow-up message content
after_followup_stage_id	integer | null	No	Updated transition stage. Pass null to remove
assets	string | null	No	Updated assets

---

Delete

delete_knowledge_points

Remove specific rows from a knowledge table by their default_id values. Use list_knowledge_points to find them.

Parameter	Type	Required	Description
knowledge_table_id	integer	Yes	The table to delete rows from. Use list_knowledge_tables to find IDs
ids	string[]	Yes	Array of default_id values identifying the rows to delete

Returns deleted_count — the number of rows removed.