Signals actions

22 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.

Agents set up on the account

signals.automation_setup · read

Every Worker and Signals agent with its settings, for planning changes.

• MCP tool: signals_automation_setup. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/automation-setup
• CLI: xholic signals automation-setup
• Scope: read
• Plan: Every plan, including the trial
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Customer brief

signals.customer_brief · read

Who the account’s customers are, what they ask, and where to find them, from Signals.

• MCP tool: signals_customer_brief. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/customer-brief
• CLI: xholic signals customer-brief
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Draft a lead audience

signals.draft_audience · read

Draft who a Signals agent should find, from a product, a URL or a description.

• MCP tool: signals_draft_audience. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/draft-audience
• CLI: xholic signals draft-audience
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
mode	“product” \	“website” \	“refine”
productId	string (uuid)	No	mode product: the saved product’s ID.
url	string ≤ 2048 chars	No	mode website: the site to read.
audienceDescription	string ≤ 3000 chars	No	mode refine: the audience description to sharpen.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Suggest lead sources

signals.suggest_sources · read

Suggest keywords, profiles and lists a Signals agent should watch.

• MCP tool: signals_suggest_sources. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/suggest-sources
• CLI: xholic signals suggest-sources
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
audienceDescription	string ≤ 3000 chars	Yes
rubric	object or null	No
rubric.who	string ≤ 600 chars	Yes
rubric.needs	array of string ≤ 200 chars (max 8)	No	Default: [].
rubric.disqualifiers	array of string ≤ 200 chars (max 8)	No	Default: [].
rubric.exampleMatch	string ≤ 600 chars or null	No	Default: null.
rubric.exampleNonMatch	string ≤ 600 chars or null	No	Default: null.
productId	string (uuid) or null	No
existing	array of object (max 15)	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Test lead searches

signals.test_searches · read

Try search queries on live X before an agent uses them.

• MCP tool: signals_test_searches. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/test-searches
• CLI: xholic signals test-searches
• Scope: read
• Plan: Pro plan or higher
• Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
• Rate limit bucket: live_x

Input

Field	Type	Required	Description
queries	array of string ≤ 500 chars (min 1, max 6)	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Create a Signals agent

signals.create_agent · write

Create an always-on agent that finds leads on X from sources and an audience description. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: create_signal_agent. Loaded by default in MCP clients.
• REST: POST /v1/signals/create-agent
• CLI: xholic signals create-agent
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
name	string ≤ 80 chars	Yes
productId	string ≤ 160 chars or null	No
audienceDescription	string ≤ 3000 chars	Yes
exclusions	string ≤ 1500 chars or null	No
rubric	object or null	No
rubric.who	string ≤ 600 chars	Yes
rubric.needs	array of string ≤ 200 chars (max 8)	No	Default: [].
rubric.disqualifiers	array of string ≤ 200 chars (max 8)	No	Default: [].
rubric.exampleMatch	string ≤ 600 chars or null	No	Default: null.
rubric.exampleNonMatch	string ≤ 600 chars or null	No	Default: null.
strictness	“HIGH_PRECISION” \	“DISCOVERY”	No
dmPolicy	“ANYONE” \	“OPEN_DMS_ONLY”	No
destinationListId	string (uuid)	No
baselineMode	“FUTURE_ONLY” \	“RECENT”	No
intervalHours	integer 4–24	No	Default: 6.
status	“ACTIVE” \	“PAUSED”	No
sources	array of object (min 1, max 15)	Yes
newListName	string ≤ 80 chars	No	A name for a new contact list to save leads to.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Find customers for a product

signals.find_customers · write

One-click agent that finds people asking for what a product does, and its competitors’ customers. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: find_customers. Loaded by default in MCP clients.
• REST: POST /v1/signals/find-customers
• CLI: xholic signals find-customers
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
productId	string ≤ 160 chars	Yes
replaceAgentId	string ≤ 160 chars	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Edit a Signals agent

signals.update_agent · write

Change a Signals agent’s audience, sources, rubric or schedule. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: signals_update_agent. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/update-agent
• CLI: xholic signals update-agent
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
agentId	string (uuid)	Yes
changes	object	Yes
changes.name	string ≤ 80 chars	No
changes.productId	string ≤ 160 chars or null	No
changes.audienceDescription	string ≤ 3000 chars	No
changes.exclusions	string ≤ 1500 chars or null	No
changes.rubric	object or null	No
changes.rubric.who	string ≤ 600 chars	Yes
changes.rubric.needs	array of string ≤ 200 chars (max 8)	No	Default: [].
changes.rubric.disqualifiers	array of string ≤ 200 chars (max 8)	No	Default: [].
changes.rubric.exampleMatch	string ≤ 600 chars or null	No	Default: null.
changes.rubric.exampleNonMatch	string ≤ 600 chars or null	No	Default: null.
changes.strictness	“HIGH_PRECISION” \	“DISCOVERY”	No
changes.dmPolicy	“ANYONE” \	“OPEN_DMS_ONLY”	No
changes.baselineMode	“FUTURE_ONLY” \	“RECENT”	No
changes.intervalHours	integer 4–24	No
changes.sources	array of object (min 1, max 15)	No	The agent’s full list of sources after the change, kept ones included.
changes.destinationListId	string (uuid)	No
changes.newListName	string ≤ 80 chars	No	A name for a new contact list to save leads to.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Pause or resume a Signals agent

signals.set_status · write

Pause or resume a Signals agent.

• MCP tool: signals_set_status. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/set-status
• CLI: xholic signals set-status
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
agentId	string (uuid)	Yes
status	“ACTIVE” \	“PAUSED”	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Signals overview

signals.dashboard · read

Every Signals agent with its status, sources, last run and lead counts, plus the month’s scoring quota and any ready-made or product agent that needs a rebuild.

• MCP tool: signals_dashboard. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/dashboard
• CLI: xholic signals dashboard
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Find accounts to watch

signals.search_profiles · read

Search X accounts by name or handle to watch in a Signals agent (Profile or Followers sources). Stored profiles first, then live X.

• MCP tool: signals_search_profiles. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/search-profiles
• CLI: xholic signals search-profiles
• Scope: read
• Plan: Pro plan or higher
• Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
• Rate limit bucket: live_x

Input

Field	Type	Required	Description
q	string ≤ 80 chars	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Watched source details

signals.source_details · read

Names and avatars for X accounts and X lists a Signals agent watches.

• MCP tool: signals_source_details. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/source-details
• CLI: xholic signals source-details
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
usernames	string ≤ 600 chars	No	Comma-separated X usernames without @, up to 30.
listIds	string ≤ 2000 chars	No	Comma-separated numeric X list ids, up to 30.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Create the ready-made Signals agent

signals.create_ready_made · write

Create the one-click Signals agent built from the account’s context and tested searches. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: signals_create_ready_made. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/create-ready-made
• CLI: xholic signals create-ready-made
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Rebuild the ready-made Signals agent

signals.rebuild_ready_made · write

Refresh the ready-made Signals agent from the account’s current context. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: signals_rebuild_ready_made. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/rebuild-ready-made
• CLI: xholic signals rebuild-ready-made
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
keepTargeting	boolean	No	Keep the user’s own description and rubric and refresh only the searches.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Add searches to the ready-made agent

signals.expand_ready_made · write

Top the ready-made Signals agent up to the paid plan’s size with more searches from the profile, keeping its current ones. Not available on a trial. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: signals_expand_ready_made. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/expand-ready-made
• CLI: xholic signals expand-ready-made
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Hide the add-searches offer

signals.dismiss_expand · write

Hide the offer to add more searches to the ready-made Signals agent, for good.

• MCP tool: signals_dismiss_expand. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/dismiss-expand
• CLI: xholic signals dismiss-expand
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Update a Find customers agent

signals.rebuild_product_agent · write

Rebuild a product’s Find customers agent after the product changed. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: signals_rebuild_product_agent. Catalog: reach it with find_actions and run_write_action, or turn on the full toolset.
• REST: POST /v1/signals/rebuild-product-agent
• CLI: xholic signals rebuild-product-agent
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Run a Signals agent now

signals.run_agent · write

Queue a Signals agent to search for leads now instead of waiting for its schedule. Leads it scores count toward the month’s Signals quota, and each agent has a few manual runs per 24 hours. Returns right away; new leads arrive in get_leads. Call it only when the user asked for this in the conversation; never on your own initiative.

• MCP tool: run_signal_agent. Loaded by default in MCP clients.
• REST: POST /v1/signals/run-agent
• CLI: xholic signals run-agent
• Scope: write
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: write

Input

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Signals runs

signals.runs · read

Recent Signals agent runs, newest first, with what each found and scored.

• MCP tool: signals_runs. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/runs
• CLI: xholic signals runs
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
limit	integer 1–100	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Agent’s customer brief

signals.agent_brief · read

One Signals agent’s weekly brief: themes, questions and competitors its leads talk about, with the people and posts behind each. Says NOT_ENOUGH under 3 leads.

• MCP tool: signals_agent_brief. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/agent-brief
• CLI: xholic signals agent-brief
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Market brief

signals.market_brief · read

The weekly brief across all of the account’s Signals agents: one view of what the market asks for and who to reply to.

• MCP tool: signals_market_brief. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/market-brief
• CLI: xholic signals market-brief
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Products and their customer agents

signals.products · read

The account’s products, each with its Find customers agent (and build progress) and competitors.

• MCP tool: signals_products. Catalog: reach it with find_actions and run_read_action, or turn on the full toolset.
• REST: GET /v1/signals/products
• CLI: xholic signals products
• Scope: read
• Plan: Pro plan or higher
• Cost: Free.
• Rate limit bucket: read

Input

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.