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

# Tools

> Complete reference of all MCP tools exposed by the ChatbotX MCP Server, including default tools, discovery endpoints, and meta-tools.

The ChatbotX MCP Server gives AI agents direct programmatic access to your self-hosted ChatbotX Workspace. Tools are automatically generated from the ChatbotX OpenAPI specification (`public-spec.json`), exposing over 380 operations across the entire platform without manual tool definitions.

## How Tools Reach Your Context

Listing all \~380 API operations at once would overwhelm an AI agent's context window, increasing token cost and leading to hallucinated arguments. To prevent this, ChatbotX MCP uses a two-tier tool discovery model:

<CardGroup cols={2}>
  <Card title="Curated Default Set (43 Tools)" icon="list-check">
    A curated set of 43 essential tools (plus 2 meta-tools) is always visible in `tools/list` for common operations: contacts, conversations, flows, broadcasts, sequences, and analytics.
  </Card>

  <Card title="Meta-Tools (Full API Access)" icon="magnifying-glass">
    Two fixed meta-tools (`search_tools` and `call_tool`) allow the agent to discover and run any of the \~337 extended API operations on demand with zero context cost.
  </Card>
</CardGroup>

### Meta-Tools

When an agent needs an operation outside the default set (such as managing coupons, webhooks, tags, triggers, or workspace members), it uses the meta-tools:

| Tool           | Description                                                                                                        | Input Arguments                                                                                                                      |
| :------------- | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `search_tools` | Search the full catalog of \~380 ChatbotX API tools. Returns matching tool names, descriptions, and input schemas. | `query` (string, required): Task description in natural language.<br />`limit` (number, optional): Max results (default 10, max 25). |
| `call_tool`    | Execute any ChatbotX tool by name, including tools discovered through `search_tools`.                              | `name` (string, required): Exact tool name.<br />`arguments` (object, optional): Arguments JSON object for the tool.                 |

### Scope-Based Filtering

On connect, the server introspects the caller's Workspace Token (`GET /v1/token`) and filters the visible tool list:

* **Missing Scopes:** If a token lacks a required scope (e.g. `broadcasts`), tools requiring that scope are hidden from `tools/list`.
* **Read-Only Tokens:** Tokens with `read_only` permission only see read operations (`GET` endpoints, protecting your workspace against unintended writes).
* **Auto-Refresh:** The server re-fetches the OpenAPI specification and token cache every 5 minutes (`CHATBOTX_SPEC_TTL_MS`), ensuring newly deployed endpoints become available without restarting the MCP server.

## Discovery Tools (Call These First)

Before performing business actions, AI agents should invoke discovery tools to inspect available workspace resources and verify permissions:

| Tool                | Method | Description                                                                                                                                                             |
| :------------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `capabilities_get`  | `GET`  | Discover active inboxes, WhatsApp templates, custom fields, bot fields, tags, AI agents, sequences, and flows. Returns the actual IDs needed for subsequent tool calls. |
| `token_get`         | `GET`  | Retrieve the calling token's workspace ID, permission level (`read_only` or `full`), and assigned scopes. Always check this before attempting write operations.         |
| `schemas_flow_spec` | `GET`  | Retrieve the complete JSON Schema for the Flow DSL specification. Serves as the authoritative guide for building or updating flow nodes.                                |

## Default Tools (43 Core Tools)

The following 43 tools are registered in the default `tools/list` set. Tool names follow the OpenAPI `operationId` converted to `snake_case`.

### Capabilities (3 tools)

Tools for environment discovery, token introspection, and schema validation.

| Tool                | Description                                                                       |
| :------------------ | :-------------------------------------------------------------------------------- |
| `capabilities_get`  | Discover workspace inboxes, templates, custom fields, tags, sequences, and flows. |
| `schemas_flow_spec` | Get JSON Schema for the flow-spec DSL used by flow builders.                      |
| `token_get`         | Get calling token workspace ID, permission, and authorized scopes.                |

### AI Agents (5 tools)

Manage autonomous AI agents, knowledge base files, and custom AI functions.

| Tool                | Description                                                              |
| :------------------ | :----------------------------------------------------------------------- |
| `ai_agents_list`    | List all AI agents configured in the workspace.                          |
| `ai_agents_create`  | Create a new AI agent with model settings and system instructions.       |
| `ai_agents_update`  | Update configuration, prompt, or attached tools of an existing AI agent. |
| `ai_files_list`     | List knowledge base documents and media uploaded for AI agents.          |
| `ai_functions_list` | List custom AI functions available to AI agents.                         |

### Analytics (5 tools)

Access workspace growth, contact activity, flow engagement, and sequence performance.

| Tool                                   | Description                                                          |
| :------------------------------------- | :------------------------------------------------------------------- |
| `analytics_new_contact_counts_per_day` | Get daily counts of newly acquired contacts over a date range.       |
| `analytics_blocked_contacts_per_day`   | Get daily counts of contacts blocked by channel or user action.      |
| `analytics_flow_stats`                 | Retrieve node-level execution and completion metrics for a flow.     |
| `analytics_broadcast_stats`            | Retrieve delivery, read, and failure metrics for a broadcast.        |
| `analytics_sequence_step_stats`        | Retrieve step-by-step progression and drop-off stats for a sequence. |

### Broadcasts (3 tools)

Send and control mass outbound campaigns across connected channels.

| Tool              | Description                                                                  |
| :---------------- | :--------------------------------------------------------------------------- |
| `broadcasts_list` | List recent broadcast campaigns and their current delivery status.           |
| `broadcasts_get`  | Retrieve detailed configuration and target audience of a specific broadcast. |
| `broadcasts_stop` | Halt an ongoing broadcast campaign immediately.                              |

### Contacts (12 tools)

Comprehensive contact data management, tag assignment, custom fields, and direct messaging.

| Tool                           | Description                                                                                  |
| :----------------------------- | :------------------------------------------------------------------------------------------- |
| `contacts_create`              | Add a new contact with phone, email, or channel identifiers.                                 |
| `contacts_get`                 | Retrieve a contact by ID or identifier (`id:123`, `email:user@example.com`, `phone:+84...`). |
| `contacts_list`                | List contacts in the workspace with pagination and advanced filter conditions.               |
| `contacts_list_tags`           | List all tags applied to a specific contact.                                                 |
| `contacts_add_tags_by_name`    | Add one or more tags to a contact using human-readable tag names.                            |
| `contacts_list_custom_fields`  | Retrieve all custom field values stored on a contact.                                        |
| `contacts_set_custom_field`    | Update or set a custom field value for a contact.                                            |
| `contacts_list_messages`       | Retrieve message history for a specific contact.                                             |
| `contacts_send_message`        | Send a direct text message or interactive response to a contact.                             |
| `contacts_send_flow`           | Trigger an automation flow for a contact.                                                    |
| `contacts_list_sequences`      | List active sequence subscriptions for a contact.                                            |
| `contacts_subscribe_sequences` | Enroll a contact into one or more automated sequences.                                       |

### Conversations (3 tools)

Live chat inbox management and agent assignment.

| Tool                   | Description                                                          |
| :--------------------- | :------------------------------------------------------------------- |
| `conversations_list`   | List active, pending, or closed inbox conversations.                 |
| `conversations_get`    | Retrieve full details and metadata for a conversation thread.        |
| `conversations_assign` | Assign or unassign a conversation to a specific agent or inbox team. |

### Error Logs (1 tool)

Inspect runtime execution errors across flows, webhooks, and integrations.

| Tool              | Description                                                    |
| :---------------- | :------------------------------------------------------------- |
| `error_logs_list` | List recent system and execution error logs with stack traces. |

### Flows (6 tools)

Build, validate, test, and publish conversational automation flows.

| Tool                 | Description                                                                                |
| :------------------- | :----------------------------------------------------------------------------------------- |
| `flows_list`         | List all automation flows in the workspace.                                                |
| `flows_get`          | Retrieve the complete flow definition and node graph by ID.                                |
| `flows_create`       | Create a new flow draft with initial nodes and optionally publish immediately in one call. |
| `flows_update_draft` | Update node connections and contents of an unpublished flow draft.                         |
| `flows_publish`      | Publish flow draft to make it live for incoming messages.                                  |
| `flows_validate`     | Compile and validate a flow spec DSL against schema rules without publishing.              |

### Keywords (1 tool)

Automated keyword triggers that match customer messages.

| Tool            | Description                                                          |
| :-------------- | :------------------------------------------------------------------- |
| `keywords_list` | List configured keywords, matching rules, and linked response flows. |

### Messages (1 tool)

Conversation thread message inspection.

| Tool            | Description                                        |
| :-------------- | :------------------------------------------------- |
| `messages_list` | List messages within an inbox conversation thread. |

### Sequences (3 tools)

Drip campaigns and delayed follow-up messaging sequences.

| Tool               | Description                                                                  |
| :----------------- | :--------------------------------------------------------------------------- |
| `sequences_list`   | List all sequence automations configured in the workspace.                   |
| `sequences_get`    | Retrieve sequence configuration, steps, delays, and enrolled contacts count. |
| `sequences_update` | Update sequence name, scheduling parameters, or active state.                |

## Extended Operations via Meta-Tools

All other ChatbotX API endpoints (\~337 operations) are fully functional through `search_tools` and `call_tool`. The agent can search by natural language keyword, receive the exact parameter schema, and invoke the operation.

Common resource areas reachable via meta-tools:

<AccordionGroup>
  <Accordion title="Tags Management">
    Manage tags at the workspace level:

    * `tags_list`: List all available workspace tags.
    * `tags_create`: Create a new tag for audience segmentation.
    * `tags_get`: Get tag details by ID.
    * `tags_update`: Rename or re-color an existing tag.
    * `tags_delete`: Remove a tag from the workspace.
  </Accordion>

  <Accordion title="Custom Fields and Bot Fields">
    Define global variables and contact attributes:

    * `custom_fields_list`: List custom field definitions.
    * `custom_fields_create`: Define a new contact custom field (text, number, date, boolean).
    * `custom_fields_delete`: Remove a custom field definition.
    * `bot_fields_list`: List global workspace bot fields.
    * `bot_fields_set`: Set or update the global value of a bot field.
  </Accordion>

  <Accordion title="Triggers and Webhooks">
    Handle real-time event triggers and incoming webhooks:

    * `triggers_list`: List automation event triggers.
    * `triggers_create`: Create an event trigger (e.g. tag added, field changed).
    * `webhooks_list`: List registered incoming and outgoing webhooks.
    * `webhooks_create`: Register a new webhook endpoint.
    * `webhooks_delete`: Delete an obsolete webhook.
  </Accordion>

  <Accordion title="Saved Replies and Templates">
    Canned responses and multi-channel message templates:

    * `saved_replies_list`: List canned replies for live chat agents.
    * `saved_replies_create`: Add a new saved reply shortcut.
    * `whatsapp_templates_list`: List approved WhatsApp message templates.
  </Accordion>

  <Accordion title="Coupons and Gamification">
    Promotional marketing tools:

    * `coupons_list`: List active promotional coupon batches.
    * `coupons_create`: Generate single-use or multi-use discount coupons.
    * `coupons_validate`: Validate coupon code validity and redemption limits.
  </Accordion>

  <Accordion title="Team Members and Inboxes">
    Workspace collaboration and inbox management:

    * `workspace_members_list`: List workspace collaborators and roles.
    * `invites_create_invite_token`: Generate an invitation link for new team members.
    * `inboxes_list`: List connected inboxes and communication channels.
  </Accordion>
</AccordionGroup>

## Tool Execution Protocol

When an AI assistant calls a tool, it formats the request as a standard JSON-RPC 2.0 message:

### Example: Direct Tool Call (`contacts_create`)

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "contacts_create",
    "arguments": {
      "first_name": "Minh",
      "last_name": "Nguyen",
      "phone": "+84901234567",
      "email": "minh.nguyen@example.com"
    }
  },
  "id": 1
}
```

### Example: Discovery via Meta-Tool (`search_tools` and `call_tool`)

<Steps>
  <Step title="Search for an extended operation">
    The agent searches for tag management tools:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "tools/call",
      "params": {
        "name": "search_tools",
        "arguments": {
          "query": "create new tag for contacts"
        }
      },
      "id": 2
    }
    ```
  </Step>

  <Step title="Inspect search results">
    The server returns matching tool definitions including `tags_create` with its `inputSchema`.
  </Step>

  <Step title="Execute the tool via call_tool">
    The agent invokes `call_tool` passing the target name and arguments:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "tools/call",
      "params": {
        "name": "call_tool",
        "arguments": {
          "name": "tags_create",
          "arguments": {
            "name": "VIP Customer",
            "color": "#155dfc"
          }
        }
      },
      "id": 3
    }
    ```
  </Step>
</Steps>

<Note>
  For instructions on setting up ChatbotX MCP with Claude, Cursor, ChatGPT, Codex, or OpenClaw, see [Platform Setup](./platform-setup.mdx).
</Note>