# Signals actions

> Signals: 22 Xholic actions (12 read, 10 change), each with its MCP tool, REST endpoint and CLI command.

Source: https://docs.xholic.ai/actions/signals/

22 actions. Every field marked *Required* must be sent; `account`, `dryRun`, `idempotencyKey`, `confirmCredits` and `quoteId` are the [control fields](/api/responses/#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" | Yes |  |
| `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 | Default: `"HIGH_PRECISION"`. |
| `dmPolicy` | "ANYONE" \\| "OPEN_DMS_ONLY" | No | Default: `"ANYONE"`. |
| `destinationListId` | string (uuid) | No |  |
| `baselineMode` | "FUTURE_ONLY" \\| "RECENT" | No | Default: `"FUTURE_ONLY"`. |
| `intervalHours` | integer 4–24 | No | Default: `6`. |
| `status` | "ACTIVE" \\| "PAUSED" | No | Default: `"ACTIVE"`. |
| `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. |