External Agents — Tool Reference

All tools are called via tools/call on POST https://chatdrift.com/external-agent/mcp. Each tool returns a response with a content array containing a text result.

See External Agents — Getting Started for auth setup and connection examples.

Response shape

Every tool returns:

{
  "content": [
    {
      "type": "text",
      "text": "<JSON string of the result>"
    }
  ]
}

Parse content[0].text as JSON to access the structured result.

---

Conversations

list_conversations

List conversations for your team.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_conversations",
    "arguments": {
      "status": "unassigned",
      "limit": 25
    }
  }
}

Example result (content[0].text parsed)

{
  "conversations": [
    {
      "id": "conv_abc123",
      "status": "unassigned",
      "createdAt": "2026-06-09T08:00:00.000Z",
      "contact": {
        "id": "ctc_xyz",
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "lastMessage": {
        "text": "Hi, I need help with my order.",
        "createdAt": "2026-06-09T08:01:00.000Z"
      }
    }
  ],
  "total": 1
}

---

get_conversation

Fetch a single conversation and its full message thread.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_conversation",
    "arguments": {
      "conversationId": "conv_abc123"
    }
  }
}

Example result

{
  "id": "conv_abc123",
  "status": "unassigned",
  "createdAt": "2026-06-09T08:00:00.000Z",
  "contact": {
    "id": "ctc_xyz",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "text": "Hi, I need help with my order.",
      "createdAt": "2026-06-09T08:01:00.000Z"
    }
  ]
}

---

assign_conversation_to_self

Assign a conversation to this agent. The conversation's assignee is set to the authenticated external agent.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "assign_conversation_to_self",
    "arguments": {
      "conversationId": "conv_abc123"
    }
  }
}

Example result

{
  "success": true,
  "conversationId": "conv_abc123"
}

---

reply_to_conversation

Send a reply in a conversation.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "reply_to_conversation",
    "arguments": {
      "conversationId": "conv_abc123",
      "text": "Thanks for reaching out! I've looked into your order and it should arrive by Friday."
    }
  }
}

Example result

{
  "success": true,
  "messageId": "msg_002"
}

---

Tickets

list_tickets

List support tickets for your team.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_tickets",
    "arguments": {
      "status": "open",
      "limit": 10
    }
  }
}

Example result

{
  "tickets": [
    {
      "id": "tkt_001",
      "subject": "Cannot log in to my account",
      "status": "open",
      "priority": "high",
      "createdAt": "2026-06-09T07:00:00.000Z",
      "contact": {
        "id": "ctc_xyz",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    }
  ],
  "total": 1
}

---

get_ticket

Fetch a single ticket and its full reply thread.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_ticket",
    "arguments": {
      "ticketId": "tkt_001"
    }
  }
}

Example result

{
  "id": "tkt_001",
  "subject": "Cannot log in to my account",
  "status": "open",
  "priority": "high",
  "createdAt": "2026-06-09T07:00:00.000Z",
  "contact": {
    "id": "ctc_xyz",
    "name": "Jane Smith"
  },
  "thread": [
    {
      "id": "reply_001",
      "body": "I keep getting 'invalid credentials' even though my password is correct.",
      "isPrivate": false,
      "createdAt": "2026-06-09T07:01:00.000Z"
    }
  ]
}

---

assign_ticket_to_self

Assign a ticket to this agent.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "assign_ticket_to_self",
    "arguments": {
      "ticketId": "tkt_001"
    }
  }
}

Example result

{
  "success": true,
  "ticketId": "tkt_001"
}

---

reply_to_ticket

Post a reply on a ticket thread.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "reply_to_ticket",
    "arguments": {
      "ticketId": "tkt_001",
      "body": "Hi Jane, I've reset your account. Please try logging in again with your email address.",
      "isPrivate": false
    }
  }
}

Example result

{
  "success": true,
  "replyId": "reply_002"
}

---

update_ticket_status

Change the status of a ticket.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "update_ticket_status",
    "arguments": {
      "ticketId": "tkt_001",
      "status": "resolved"
    }
  }
}

Example result

{
  "success": true,
  "ticketId": "tkt_001",
  "status": "resolved"
}

---

Tasks

list_tasks

List tasks for your team.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": {
      "tab": "open",
      "limit": 10
    }
  }
}

Example result

{
  "tasks": [
    {
      "id": "task_001",
      "title": "Follow up with Jane about login issue",
      "status": "open",
      "dueAt": "2026-06-10T17:00:00.000Z",
      "createdAt": "2026-06-09T08:00:00.000Z"
    }
  ],
  "total": 1
}

---

create_task

Create a new task, optionally linked to conversations, tickets, or contacts.

Input

TaskLink

Example request

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "title": "Follow up with Jane about login issue",
      "dueAt": 1749571200000,
      "links": [
        {
          "resourceType": "ticket",
          "resourceId": "tkt_001",
          "label": "Cannot log in ticket"
        }
      ]
    }
  }
}

Example result

{
  "id": "task_001",
  "title": "Follow up with Jane about login issue",
  "status": "open",
  "dueAt": "2026-06-10T16:00:00.000Z"
}

---

update_task

Update a task's title, due date, or links.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "update_task",
    "arguments": {
      "taskId": "task_001",
      "title": "Follow up with Jane — urgent",
      "dueAt": 1749484800000
    }
  }
}

Example result

{
  "success": true,
  "taskId": "task_001"
}

---

close_task

Mark a task as closed/completed.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "close_task",
    "arguments": { "taskId": "task_001" }
  }
}

Example result

{
  "success": true,
  "taskId": "task_001"
}

---

reopen_task

Reopen a previously closed task.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "reopen_task",
    "arguments": { "taskId": "task_001" }
  }
}

Example result

{
  "success": true,
  "taskId": "task_001"
}

---

archive_task

Archive a task (soft delete). Archived tasks are hidden from all lists.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "archive_task",
    "arguments": { "taskId": "task_001" }
  }
}

Example result

{
  "success": true,
  "taskId": "task_001"
}

---

search_task_resources

Search for resources (conversations, tickets, contacts) that can be linked to a task.

Input

Example request

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "search_task_resources",
    "arguments": {
      "query": "Jane Smith",
      "limit": 5
    }
  }
}

Example result

{
  "results": [
    {
      "resourceType": "contact",
      "resourceId": "ctc_xyz",
      "label": "Jane Smith",
      "url": "/contacts/ctc_xyz"
    },
    {
      "resourceType": "ticket",
      "resourceId": "tkt_001",
      "label": "Cannot log in to my account",
      "url": "/tickets/tkt_001"
    }
  ]
}

---

Approvals

list_pending_approvals

List workflow approval steps that are currently waiting for a decision.

Input

None.

Example request

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "list_pending_approvals",
    "arguments": {}
  }
}

Example result

{
  "approvals": [
    {
      "stepRunId": "step_abc",
      "workflowName": "Human-Approved Refund",
      "prompt": "Customer Jane Smith is requesting a $49 refund for order #1234. Approve?",
      "createdAt": "2026-06-09T09:00:00.000Z"
    }
  ],
  "total": 1
}

---

submit_approval

Approve or reject a pending approval step. This resumes the paused workflow.

Input

Example request — approve

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "tools/call",
  "params": {
    "name": "submit_approval",
    "arguments": {
      "stepRunId": "step_abc",
      "approved": true,
      "note": "Verified order history — refund is valid."
    }
  }
}

Example request — reject

{
  "jsonrpc": "2.0",
  "id": 19,
  "method": "tools/call",
  "params": {
    "name": "submit_approval",
    "arguments": {
      "stepRunId": "step_abc",
      "approved": false,
      "note": "Order is outside the 30-day return window."
    }
  }
}

Example result

{
  "success": true,
  "stepRunId": "step_abc",
  "approved": true
}