External Agents — Tool Reference

All tools are called via tools/call on POST https://app.nexvio.ai/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

Field	Type	Required	Description
status	"all" | "active" | "unassigned" | "completed"	No	Filter by status. Defaults to "all".
limit	integer (1–100)	No	Max results to return. Defaults to 25.

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

Field	Type	Required	Description
conversationId	string	Yes	ID of the conversation to fetch.

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

Field	Type	Required	Description
conversationId	string	Yes	ID of the conversation to assign.

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

Field	Type	Required	Description
conversationId	string	Yes	ID of the conversation to reply to.
text	string	Yes	The reply message text.

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

Field	Type	Required	Description
status	string	No	Filter by ticket status (e.g. "open", "closed"). Omit for all.
limit	integer (1–100)	No	Max results. Defaults to 25.

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

Field	Type	Required	Description
ticketId	string	Yes	ID of the ticket to fetch.

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

Field	Type	Required	Description
ticketId	string	Yes	ID of the ticket to assign.

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

Field	Type	Required	Description
ticketId	string	Yes	ID of the ticket to reply to.
body	string	Yes	The reply body text.
isPrivate	boolean	No	Post as an internal note (not visible to the contact). Defaults to false.

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

Field	Type	Required	Description
ticketId	string	Yes	ID of the ticket to update.
status	string	Yes	New status value (e.g. "open", "pending", "resolved", "closed").

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

---

Tasks

list_tasks

List tasks assigned to this external agent.

Input

Field	Type	Required	Description
tab	"open" | "closed"	No	Filter by task state. Defaults to "open", which also includes tasks closed within the last 24 hours.
limit	integer (1–100)	No	Max results. Defaults to 50.

Example request

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

Result

structuredContent.tasks is an array of tasks assigned to your external agent, each with its linked resources in links. Timestamps are Unix seconds.

{
  "tasks": [
    {
      "id": "task_001",
      "title": "Follow up with Jane about login issue",
      "status": "open",
      "dueAt": 1781049600,
      "links": [
        {
          "resourceType": "ticket",
          "resourceId": "tkt_001",
          "label": "Cannot log in ticket"
        }
      ],
      "createdAt": 1780990000,
      "updatedAt": 1780990000
    }
  ]
}

---

create_task

Create a new task assigned to this external agent, optionally linked to conversations or tickets.

Input

Field	Type	Required	Description
title	string	Yes	Task title.
dueAt	integer | null	No	Unix timestamp (seconds) of the due date.
links	TaskLink[]	No	Resources to link to this task (up to 10) — see below.

TaskLink

Field	Type	Required	Description
resourceType	"conversation" | "ticket"	Yes	Type of resource.
resourceId	string	Yes	ID of the linked resource.
label	string	Yes	Display label for the link.
url	string	No	Optional URL for the link.

Example request

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

Result

The text content is a confirmation such as Task task_001 created. structuredContent.task is the new task, assigned to your external agent.

{
  "task": {
    "id": "task_001",
    "title": "Follow up with Jane about login issue",
    "status": "open",
    "dueAt": 1749571200,
    "links": [
      {
        "resourceType": "ticket",
        "resourceId": "tkt_001",
        "label": "Cannot log in ticket"
      }
    ]
  }
}

---

update_task

Update the title, due date, or links of a task assigned to this external agent.

Input

Field	Type	Required	Description
taskId	string	Yes	ID of the task to update.
title	string	No	New title.
dueAt	integer | null	No	New due date as a Unix timestamp (seconds).
links	TaskLink[]	No	Replace all task links with this list.

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

Result

The text content is a confirmation such as Task task_001 updated. structuredContent.task is the updated task.

{
  "task": {
    "id": "task_001",
    "title": "Follow up with Jane — urgent",
    "status": "open",
    "dueAt": 1749484800
  }
}

---

close_task

Mark a task assigned to this external agent as closed.

Input

Field	Type	Required	Description
taskId	string	Yes	ID of the task to close.

Example request

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

Result

The text content is a confirmation such as Task task_001 closed. structuredContent.task is the updated task, with status set to "closed".

{
  "task": {
    "id": "task_001",
    "status": "closed"
  }
}

---

reopen_task

Reopen a closed task assigned to this external agent.

Input

Field	Type	Required	Description
taskId	string	Yes	ID of the task to reopen.

Example request

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

Result

The text content is a confirmation such as Task task_001 reopened. structuredContent.task is the updated task, with status set back to "open".

{
  "task": {
    "id": "task_001",
    "status": "open"
  }
}

---

archive_task

Archive a task assigned to this external agent (soft delete). Archived tasks are hidden from all lists.

Input

Field	Type	Required	Description
taskId	string	Yes	ID of the task to archive.

Example request

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

Result

The text content is a confirmation such as Task task_001 archived. structuredContent.task is the archived task.

{
  "task": {
    "id": "task_001"
  }
}

---

search_task_resources

Search team conversations and tickets that can be linked to a task.

Input

Field	Type	Required	Description
query	string	No	Search query string.
limit	integer (1–25)	No	Max results.

Example request

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

Result

structuredContent.resources is an array of matching tickets and conversations that can be passed as links to create_task or update_task.

{
  "resources": [
    {
      "resourceType": "ticket",
      "resourceId": "tkt_001",
      "label": "Ticket #1001",
      "description": "Cannot log in to my account",
      "url": "/tickets/1001"
    }
  ]
}

---

Approvals

list_pending_approvals

List workflow human-approval steps that are currently waiting for a decision for your team.

Input

None.

Example request

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

Result

structuredContent.approvals is an array of pending approval steps, most recently requested first. requestedAt is a Unix timestamp in seconds.

{
  "approvals": [
    {
      "stepRunId": "step_abc",
      "runId": "run_123",
      "nodeId": "node_approval",
      "workflowId": "wf_456",
      "workflowName": "Human-Approved Refund",
      "prompt": "Customer Jane Smith is requesting a $49 refund for order #1234. Approve?",
      "requestedAt": 1781000500
    }
  ]
}

---

submit_approval

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

Input

Field	Type	Required	Description
stepRunId	string	Yes	ID of the pending approval step. Obtained from list_pending_approvals.
approved	boolean	Yes	true to approve, false to reject.
note	string	No	Optional note explaining the decision.

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

Result

The text content is a confirmation such as Approval step_abc approved. (or rejected.). structuredContent.decision echoes the decision:

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

An error is returned if the step is not found or has already been decided.