External Agents — Tool Reference

All tools are called via tools/call on POST https://chatdrift.com/external-agent/mcp. Each tool returns an MCP result with a content array and a structuredContent object.

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

Response shape

Every tool returns an MCP tool result with two parts:

{
  "content": [
    {
      "type": "text",
      "text": "<result text>"
    }
  ],
  "structuredContent": { "<key>": "<result>" }
}

• content[0].text — for list and get tools, the result serialized as JSON; for tools that change data, a short confirmation sentence such as Task task_001 created.
• structuredContent — the result as an object under a tool-specific key (for example conversations, ticket, or task). Use this for programmatic access.

Records are returned as stored by the platform: field names are camelCase, timestamps are Unix seconds, and a record can include more fields than the examples below show. If a tool fails, the MCP result has isError: true and the text content describes the problem.

---

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
    }
  }
}

Result

structuredContent.conversations is an array of conversation summaries. Timestamps are Unix seconds.

{
  "conversations": [
    {
      "id": "conv_abc123",
      "status": "unassigned",
      "assigneeId": null,
      "assigneeType": null,
      "isHumanHandover": false,
      "lastMessage": { "text": "Hi, I need help with my order." },
      "createdAt": 1781000000,
      "updatedAt": 1781000060
    }
  ]
}

---

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"
    }
  }
}

Result

structuredContent.conversation contains the conversation record and its messages in chronological order. Records include additional fields beyond those shown, and timestamps are Unix seconds.

{
  "conversation": {
    "conversation": {
      "id": "conv_abc123",
      "status": "unassigned",
      "assigneeId": null,
      "assigneeType": null,
      "isHumanHandover": false,
      "createdAt": 1781000000,
      "updatedAt": 1781000060
    },
    "messages": [
      {
        "id": "msg_001",
        "chatSession": "conv_abc123",
        "content": { "text": "Hi, I need help with my order." },
        "createdAt": 1781000060
      }
    ]
  }
}

---

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"
    }
  }
}

Result

The text content is a confirmation such as Conversation conv_abc123 assigned to Triage Bot. structuredContent.conversation is the updated conversation record: its status becomes "active", and assigneeId / assigneeType identify your external agent.

{
  "conversation": {
    "id": "conv_abc123",
    "status": "active",
    "assigneeId": "<your external agent id>",
    "assigneeType": "external_agent",
    "isHumanHandover": true
  }
}

---

reply_to_conversation

Send a reply in a conversation as this external agent. The conversation must be active — call assign_conversation_to_self first for an unassigned 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."
    }
  }
}

Result

The text content is a confirmation such as Reply created for conversation conv_abc123. structuredContent.message is the new message record.

{
  "message": {
    "id": "msg_002",
    "chatSession": "conv_abc123",
    "content": { "text": "Thanks for reaching out! I've looked into your order and it should arrive by Friday." },
    "createdAt": 1781000300
  }
}

---

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
    }
  }
}

Result

structuredContent.tickets is an array of ticket records, most recently updated first. Timestamps are Unix seconds.

{
  "tickets": [
    {
      "id": "tkt_001",
      "subject": "Cannot log in to my account",
      "status": "open",
      "priority": "high",
      "requesterName": "Jane Smith",
      "requesterEmail": "jane@example.com",
      "createdAt": 1780990000,
      "updatedAt": 1780990060
    }
  ]
}

---

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"
    }
  }
}

Result

structuredContent.ticket contains the ticket record and its reply threads, newest first. Records include additional fields beyond those shown.

{
  "ticket": {
    "ticket": {
      "id": "tkt_001",
      "subject": "Cannot log in to my account",
      "status": "open",
      "priority": "high"
    },
    "threads": [
      {
        "id": "reply_001",
        "ticketId": "tkt_001",
        "body": "I keep getting 'invalid credentials' even though my password is correct.",
        "private": false,
        "incoming": true,
        "createdAt": 1780990060
      }
    ]
  }
}

---

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"
    }
  }
}

Result

The text content is a confirmation such as Ticket tkt_001 assigned to Triage Bot. structuredContent.ticket is the updated ticket record, with assigneeId / assigneeType identifying your external agent.

{
  "ticket": {
    "id": "tkt_001",
    "assigneeId": "<your external agent id>",
    "assigneeType": "external_agent"
  }
}

---

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
    }
  }
}

Result

The text content is a confirmation such as Reply created for ticket tkt_001. structuredContent.threadEntry is the new thread entry.

{
  "threadEntry": {
    "id": "reply_002",
    "ticketId": "tkt_001",
    "body": "Hi Jane, I've reset your account. Please try logging in again with your email address.",
    "private": false,
    "incoming": false,
    "createdAt": 1781000400
  }
}

---

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"
    }
  }
}

Result

The text content is a confirmation such as Ticket tkt_001 status updated to resolved. structuredContent.ticket is the updated ticket record.

{
  "ticket": {
    "id": "tkt_001",
    "status": "resolved"
  }
}